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.
influxdb3-monitor-metrics
Jason Stirnaman 2025-10-02 10:26:49 -05:00
parent 3182f8bf6f
commit 8f62e5bfbf
2 changed files with 71 additions and 3 deletions

View File

@ -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 %}}

View File

@ -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 %}}: