From a1f316331c4f7d06272742429e6e4b7445a5b1eb Mon Sep 17 00:00:00 2001 From: Anuj Parihar Date: Tue, 26 May 2026 13:53:22 +0530 Subject: [PATCH] docs: update otel and prometheus docs --- docs/features/observability/otel.mdx | 15 ++++++---- docs/features/observability/prometheus.mdx | 34 ++++++++++++++++++++-- 2 files changed, 40 insertions(+), 9 deletions(-) diff --git a/docs/features/observability/otel.mdx b/docs/features/observability/otel.mdx index 2eb665f8e65..d33cddb74c0 100644 --- a/docs/features/observability/otel.mdx +++ b/docs/features/observability/otel.mdx @@ -35,18 +35,19 @@ The plugin supports multiple trace formats to match your observability platform: | Field | Type | Required | Description | |-------|------|----------|-------------| | `service_name` | `string` | ❌ No | Service name to be used for tracing, defaults to `bifrost` | -| `collector_url` | `string` | ✅ Yes | OTLP collector endpoint URL | +| `collector_url` | `string \| EnvVar` | ✅ Yes | OTLP collector endpoint URL — supports `env.VAR_NAME` | | `trace_type` | `string` | ✅ Yes | One of: `genai_extension`, `vercel`, `open_inference` | | `protocol` | `string` | ✅ Yes | Transport protocol: `http` or `grpc` | -| `headers` | `object` | ❌ No | Custom headers for authentication (supports `env.VAR_NAME`) | +| `headers` | `object` | ❌ No | Custom headers for authentication — values support `env.VAR_NAME` | | `tls_ca_cert` | `string` | ❌ No | File path to client CA certificate for TLS. Optional. Works with both gRPC and HTTP protocol | ### Environment Variable Substitution -Headers support environment variable substitution using the `env.` prefix: +`collector_url`, `metrics_endpoint`, and individual header values all support the `env.` prefix to read from environment variables at runtime. This keeps sensitive URLs and credentials out of stored configuration. ```json { + "collector_url": "env.OTEL_COLLECTOR_URL", "headers": { "Authorization": "env.OTEL_API_KEY", "X-Custom-Header": "env.CUSTOM_VALUE" @@ -750,7 +751,7 @@ The OTel plugin supports **push-based metrics export** via OTLP, which is essent | Field | Type | Required | Description | |-------|------|----------|-------------| | `metrics_enabled` | `boolean` | ❌ No | Enable push-based metrics export (default: `false`) | -| `metrics_endpoint` | `string` | ✅ Yes (if enabled) | OTLP metrics endpoint URL | +| `metrics_endpoint` | `string \| EnvVar` | ✅ Yes (if enabled) | OTLP metrics endpoint URL — supports `env.VAR_NAME` | | `metrics_push_interval` | `integer` | ❌ No | Push interval in seconds (default: `15`, range: 1-300) | ### Example Configuration @@ -897,17 +898,19 @@ The plugin accumulates streaming chunks and emits a single complete span when th ### Environment Variable Security -Sensitive credentials never appear in config files: +Sensitive URLs and credentials never need to appear in stored configuration. The `collector_url`, `metrics_endpoint`, and header values all accept the `env.VAR_NAME` format: ```json { + "collector_url": "env.OTEL_COLLECTOR_URL", + "metrics_endpoint": "env.OTEL_METRICS_ENDPOINT", "headers": { "Authorization": "env.OTEL_API_KEY" } } ``` -The plugin reads `OTEL_API_KEY` from the environment at runtime. +The plugin resolves each `env.VAR_NAME` reference from the process environment at runtime. Stored configuration (database or config file) retains the `env.VAR_NAME` string — the resolved value is never persisted. API responses return `EnvVar` objects with sensitive resolved values redacted. ### Filtering Plugin Spans diff --git a/docs/features/observability/prometheus.mdx b/docs/features/observability/prometheus.mdx index c783e4c809f..f2d93e99eb3 100644 --- a/docs/features/observability/prometheus.mdx +++ b/docs/features/observability/prometheus.mdx @@ -68,7 +68,7 @@ For multi-node cluster deployments, the Prometheus plugin pushes metrics to a [P | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| -| `push_gateway_url` | `string` | ✅ Yes | - | Push Gateway URL (e.g., `http://pushgateway:9091`) | +| `push_gateway_url` | `string \| EnvVar` | ✅ Yes | - | Push Gateway URL — supports `env.VAR_NAME` | | `job_name` | `string` | ❌ No | `bifrost` | Job label for pushed metrics | | `instance_id` | `string` | ❌ No | hostname | Instance identifier for metric grouping | | `push_interval` | `integer` | ❌ No | `15` | Push interval in seconds (1-300) | @@ -78,8 +78,9 @@ For multi-node cluster deployments, the Prometheus plugin pushes metrics to a [P | Field | Type | Required | Description | |-------|------|----------|-------------| -| `username` | `string` | ✅ Yes | Basic auth username | -| `password` | `string` | ✅ Yes | Basic auth password | +| `username` | `string \| EnvVar` | ✅ Yes | Basic auth username — supports `env.VAR_NAME` | +| `password` | `string \| EnvVar` | ✅ Yes | Basic auth password — supports `env.VAR_NAME` | + --- @@ -146,6 +147,33 @@ For multi-node cluster deployments, the Prometheus plugin pushes metrics to a [P } ``` +### With Environment Variables + +Use `env.VAR_NAME` to reference environment variables for the Push Gateway URL and credentials: + +```json +{ + "plugins": [ + { + "name": "telemetry", + "enabled": true, + "config": { + "push_gateway": { + "enabled": true, + "push_gateway_url": "env.PUSHGATEWAY_URL", + "job_name": "bifrost", + "push_interval": 15, + "basic_auth": { + "username": "env.PUSHGATEWAY_USER", + "password": "env.PUSHGATEWAY_PASS" + } + } + } + } + ] +} +``` +