Skip to content

docs: document env.VAR_NAME support for collector_url, metrics_endpoint, and Prometheus Push Gateway fields #3753

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
akshaydeo merged 1 commit into from
May 26, 2026
Merged

docs: document env.VAR_NAME support for collector_url, metrics_endpoint, and Prometheus Push Gateway fields #3753

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions docs/features/observability/otel.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
34 changes: 31 additions & 3 deletions docs/features/observability/prometheus.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand All @@ -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` |


---

Expand Down Expand Up @@ -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"
}
}
}
}
]
}
```

</Tab>
</Tabs>

Expand Down
Loading