From 8f62e5bfbfe5d5187e7b821c57ef58d2efca27ac Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Thu, 2 Oct 2025 10:26:49 -0500 Subject: [PATCH] docs(influxdb3): Add system:metrics:read token examples and clarify authentication - Add system:metrics:read token creation examples to Enterprise token docs - Document both CLI and HTTP API approaches for creating metrics tokens - Clarify that Enterprise supports both admin and fine-grained tokens for /metrics - Add node identification explanation to monitoring documentation Addresses PR #6422 review comments about authentication and token permissions. Test validation: All examples validated with InfluxDB 3.5.0 Enterprise. --- .../admin/tokens/resource/create.md | 48 +++++++++++++++++-- .../shared/influxdb3-admin/monitor-metrics.md | 26 ++++++++++ 2 files changed, 71 insertions(+), 3 deletions(-) diff --git a/content/influxdb3/enterprise/admin/tokens/resource/create.md b/content/influxdb3/enterprise/admin/tokens/resource/create.md index e7de10b61..ce5814223 100644 --- a/content/influxdb3/enterprise/admin/tokens/resource/create.md +++ b/content/influxdb3/enterprise/admin/tokens/resource/create.md @@ -402,12 +402,24 @@ In your terminal, run the `influxdb3 create token --permission` command and prov - `health`: The specific system resource to grant permissions to. - `read`: The permission to grant to the token (system tokens are always read-only). -{{% code-placeholders "System health token|1y" %}} +The following example shows how to create specific system tokens: + +{{% code-placeholders "(System [a-z]+ token|1y" %}} ```bash influxdb3 create token \ --permission "system:health:read" \ --name "System health token" \ --expiry 1y + +influxdb3 create token \ + --permission "system:metrics:read" \ + --name "System metrics token" \ + --expiry 1y + +influxdb3 create token \ + --permission "system:ping:read" \ + --name "System ping token" \ + --expiry 1y ``` {{% /code-placeholders %}} @@ -444,9 +456,9 @@ In the request body, provide the following parameters: - `permissions`: an array of token permission actions (only `"read"` for system tokens) - `expiry_secs`: Specify the token expiration time in seconds. -The following example shows how to use the HTTP API to create a system token: +The following example shows how to use the HTTP API to create specific system tokens: -{{% code-placeholders "AUTH_TOKEN|System health token|300000" %}} +{{% code-placeholders "AUTH_TOKEN|(System [a-z]+ token)|300000" %}} ```bash curl \ @@ -463,6 +475,36 @@ curl \ }], "expiry_secs": 300000 }' + +curl \ +"http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \ +--header 'Accept: application/json' \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer AUTH_TOKEN" \ +--data '{ + "token_name": "System metrics token", + "permissions": [{ + "resource_type": "system", + "resource_identifier": ["metrics"], + "actions": ["read"] + }], + "expiry_secs": 300000 +}' + +curl \ +"http://{{< influxdb/host >}}/api/v3/enterprise/configure/token" \ +--header 'Accept: application/json' \ +--header 'Content-Type: application/json' \ +--header "Authorization: Bearer AUTH_TOKEN" \ +--data '{ + "token_name": "System ping token", + "permissions": [{ + "resource_type": "system", + "resource_identifier": ["ping"], + "actions": ["read"] + }], + "expiry_secs": 300000 +}' ``` {{% /code-placeholders %}} diff --git a/content/shared/influxdb3-admin/monitor-metrics.md b/content/shared/influxdb3-admin/monitor-metrics.md index ca1688960..5ea2f183f 100644 --- a/content/shared/influxdb3-admin/monitor-metrics.md +++ b/content/shared/influxdb3-admin/monitor-metrics.md @@ -26,6 +26,11 @@ curl -s -H "Authorization: Token AUTH_TOKEN" http://node:8181/metrics {{% show-in "enterprise" %}} ### View metrics from specific nodes +> [!Note] +> {{< product-name >}} supports two token types for the `/metrics` endpoint: +> - {{% token-link "Admin" %}}: Full access to all metrics +> - {{% token-link "Fine-grained" "resource/" %}} with `system:metrics:read` permission: Read-only access to metrics + ```bash { placeholders="AUTH_TOKEN" } # View metrics from specific nodes curl -s http://ingester-01:8181/metrics @@ -61,6 +66,27 @@ Metrics are exposed in [Prometheus exposition format](https://prometheus.io/docs metric_name{label1="value1",label2="value2"} 42.0 ``` +### Node identification in metrics + +{{< product-name >}} metrics don't include automatic node identification labels. +To identify which node produced each metric, you must configure your monitoring tool to add node labels during scraping. + +{{% show-in "enterprise" %}} +For multi-node clusters, node identification is essential for troubleshooting and monitoring individual node performance. +Many monitoring tools support adding static or dynamic labels during the scrape process (Prometheus calls this "relabeling")--for example: + +1. **Extract node hostname or IP** from the scrape target address +2. **Add extracted labels to metrics** during the scrape process + +| Hostname | Node Identification | Recommended? | +| -------------------------- | ------------------- | ----------------- | +| `ingester-01`, `query-02` | Extract role and ID | Yes | +| `node-01.cluster.internal` | Extract ID | Consider adding role information | +| `192.168.1.10` | IP address only | No, consider renaming with ID and role | + +For configuration examples, see [Add node identification with Prometheus](#add-node-identification-with-prometheus). +{{% /show-in %}} + ## Metric categories {{< product-name >}} exposes the following{{% show-in "enterprise" %}} base{{% /show-in %}} categories of metrics{{% show-in "enterprise" %}}, plus additional cluster-aware metrics{{% /show-in %}}: