docs: document x-bf-dim-* unified dimensions and deprecate x-bf-prom-* headers (#3099)

## Summary

Introduces `x-bf-dim-*` as the canonical unified header prefix for per-request observability dimensions in Bifrost. Previously, users had to use separate header families (`x-bf-prom-*`, `x-bf-maxim-*`) to propagate metadata to different backends. The new `x-bf-dim-*` prefix sends dimensions to all observability backends simultaneously — internal logs, OpenTelemetry spans, Prometheus custom labels, and Maxim tags — from a single set of headers.

## Changes

- Documented `x-bf-dim-*` as the new canonical runtime dimension prefix, replacing `x-bf-prom-*` for cross-backend observability metadata
- Added `BifrostContextKeyDimensions` (`map[string]string`) as the corresponding Go SDK context key
- Deprecated `x-bf-prom-*` headers; they remain functional for Prometheus-only backward compatibility, but `x-bf-dim-*` takes precedence when both are present for the same label
- Clarified the relationship between `x-bf-dim-*` and `x-bf-maxim-*`: shared dimensions flow to Maxim at lower priority, and explicit `x-bf-maxim-*` tags override same-named dimensions for Maxim only
- Added a dedicated "Unified dimensions" section in `request-options.mdx` with cURL and Go SDK examples
- Added a "Shared observability dimensions" section in the Maxim observability doc explaining forwarding behavior and priority rules

## Type of change

- [ ] Bug fix
- [ ] Feature
- [ ] Refactor
- [x] Documentation
- [ ] Chore/CI

## Affected areas

- [ ] Core (Go)
- [ ] Transports (HTTP)
- [ ] Providers/Integrations
- [ ] Plugins
- [ ] UI (React)
- [x] Docs

## How to test

Verify the documented header behavior against a running Bifrost gateway:

```sh
# Send a request with x-bf-dim-* headers and confirm dimensions appear in Prometheus metrics,
# OpenTelemetry spans, and Maxim tags
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-dim-environment: production" \
  -H "x-bf-dim-team: engineering" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello!"}]}'

# Confirm legacy x-bf-prom-* headers still work
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-prom-environment: production" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello!"}]}'

# Confirm x-bf-dim-* wins when both prefixes supply the same label
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "x-bf-dim-environment: production" \
  -H "x-bf-prom-environment: staging" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello!"}]}'
```

## Screenshots/Recordings

N/A

## Breaking changes

- [ ] Yes
- [x] No

`x-bf-prom-*` headers continue to work. No existing behavior is removed.

## Related issues

## Security considerations

Dimensions set via `x-bf-dim-*` are propagated to all observability backends including logs, spans, and external services such as Maxim. Callers should not include secrets or PII in dimension values.

## Checklist

- [ ] I read `docs/contributing/README.md` and followed the guidelines
- [ ] I added/updated tests where appropriate
- [x] I updated documentation where needed
- [ ] I verified builds succeed (Go and UI)
- [ ] I verified the CI pipeline passes locally if applicable

Author: BearTS

docs/features/observability/maxim.mdx

@@ -188,6 +188,21 @@ Reserved keys are `session-id`, `trace-id`, `trace-name`, `generation-id`, `gene
 </Tab>
 </Tabs>
 
+### Shared observability dimensions
+
+For tags that should be visible beyond Maxim, use `x-bf-dim-*` instead of `x-bf-maxim-*`.
+
+`x-bf-dim-*` is the canonical per-request dimension prefix in Bifrost. Those dimensions are forwarded to Maxim as tags at lower priority than explicit `x-bf-maxim-*` tags, and they are also propagated to internal logs, OpenTelemetry spans, and Prometheus custom labels.
+
+```bash
+curl -X POST http://localhost:8080/v1/chat/completions \
+  -H "x-bf-dim-environment: production" \
+  -H "x-bf-dim-team: platform" \
+  -d '{"model": "gpt-4", "messages": [...]}'
+```
+
+If you send both `x-bf-dim-environment` and `x-bf-maxim-environment`, Maxim uses the explicit `x-bf-maxim-*` tag value while the shared dimension still flows to the other observability backends.
+
 ## Supported Request Types
 
 The plugin supports the following Bifrost request types:

docs/features/telemetry.mdx

@@ -13,7 +13,7 @@ Bifrost provides built-in telemetry and monitoring capabilities through Promethe
 - **Prometheus Integration** - Native metrics collection at `/metrics` endpoint
 - **Comprehensive Tracking** - Success/error rates, token usage, costs, and cache performance
 - **Custom Labels** - Configurable dimensions for detailed analysis
-- **Dynamic Headers** - Runtime label injection via `x-bf-prom-*` headers
+- **Dynamic Headers** - Runtime label injection via `x-bf-dim-*` headers
 - **Cost Monitoring** - Real-time tracking of AI provider costs in USD
 - **Cache Analytics** - Direct and semantic cache hit tracking
 - **Async Collection** - Zero-latency impact on request processing
@@ -207,28 +207,33 @@ curl -X PATCH http://localhost:8080/config \
 
 ### Dynamic Label Injection
 
-Add custom label values at runtime using `x-bf-prom-*` headers:
+Add custom label values at runtime using `x-bf-dim-*` headers:
 
 ```bash
 # Add custom labels to specific requests
 curl -X POST http://localhost:8080/v1/chat/completions \
   -H "Content-Type: application/json" \
-  -H "x-bf-prom-team: engineering" \
-  -H "x-bf-prom-environment: production" \
-  -H "x-bf-prom-organization: my-org" \
-  -H "x-bf-prom-project: my-project" \
+  -H "x-bf-dim-team: engineering" \
+  -H "x-bf-dim-environment: production" \
+  -H "x-bf-dim-organization: my-org" \
+  -H "x-bf-dim-project: my-project" \
   -d '{
     "model": "gpt-4o-mini",
     "messages": [{"role": "user", "content": "Hello!"}]
   }'
 ```
 
 **Header Format:**
-
-- Prefix: `x-bf-prom-`
-- Label name: Any string after the prefix
+- Prefix: `x-bf-dim-`
+- Label name: Any string after the prefix, except reserved metric labels like `path` and `method`
 - Value: String value for the label
 
+These runtime dimensions are also forwarded to the other observability backends. The same `x-bf-dim-*` values appear in internal logs, OpenTelemetry span attributes, and Maxim tags.
+
+<Note>
+Legacy `x-bf-prom-*` headers still work for Prometheus-only behavior, but they are deprecated. When both prefixes provide the same label, `x-bf-dim-*` wins.
+</Note>
+
 ---
 
 ## Infrastructure Setup

docs/providers/request-options.mdx

@@ -37,7 +37,8 @@ Bifrost provides request options that control behavior, enable features, and pas
 | `maxim.TraceIDKey`                         | `x-bf-maxim-trace-id`                                | `string`              | Maxim trace ID                                                                                                                        |
 | `maxim.GenerationIDKey`                    | `x-bf-maxim-generation-id`                           | `string`              | Maxim generation ID                                                                                                                   |
 | `maxim.TagsKey`                            | `x-bf-maxim-*`                                       | `map[string]string`   | Maxim tags (custom tag names)                                                                                                         |
-| `BifrostContextKey(labelName)`             | `x-bf-prom-*`                                        | `string`              | Prometheus metric labels                                                                                                              |
+| `BifrostContextKeyDimensions` | `x-bf-dim-*` | `map[string]string` | Unified per-request dimensions forwarded to logs, spans, Prometheus custom labels, and Maxim tags |
+| `BifrostContextKey(labelName)` | `x-bf-prom-*` | `string` | Deprecated Prometheus-only label headers for backward compatibility |
 
 ## Request Configuration Options
 
@@ -1065,14 +1066,67 @@ Input: messages,
 </Tab>
 </Tabs>
 
+### Unified dimensions (x-bf-dim-*)
+
+**Context Key:** `BifrostContextKeyDimensions`  
+**Header Pattern:** `x-bf-dim-{name}`  
+**Type:** `map[string]string`  
+**Required:** No
+
+Add per-request dimensions once and have Bifrost forward them to all observability backends:
+- internal logs as request metadata
+- OpenTelemetry span attributes
+- Prometheus custom labels when the dimension name matches a configured label
+- Maxim generation and trace tags
+
+`x-bf-dim-*` is now the canonical header prefix for runtime observability metadata.
+
+<Tabs>
+<Tab title="Gateway (cURL)">
+```bash
+curl --location 'http://localhost:8080/v1/chat/completions' \
+--header 'x-bf-dim-environment: production' \
+--header 'x-bf-dim-team: engineering' \
+--header 'Content-Type: application/json' \
+--data '{
+    "model": "openai/gpt-4o-mini",
+    "messages": [{"role": "user", "content": "Hello!"}]
+}'
+```
+</Tab>
+<Tab title="Go SDK">
+```go
+dims := map[string]string{
+    "environment": "production",
+    "team":        "engineering",
+}
+ctx := context.Background()
+ctx = context.WithValue(ctx, schemas.BifrostContextKeyDimensions, dims)
+
+response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
+    Provider: schemas.OpenAI,
+    Model:    "gpt-4o-mini",
+    Input:    messages,
+})
+```
+</Tab>
+</Tabs>
+
+<Note>
+`x-bf-dim-*` values cannot override reserved Bifrost context keys such as request IDs or virtual keys. Also avoid sending secrets or PII in dimensions because they are propagated to observability backends.
+For `x-bf-dim-*`, reserved metric labels `path` and `method` are ignored at runtime.
+</Note>
+
 ### Maxim Tags (x-bf-maxim-*)
 
 **Context Key:** `maxim.TagsKey`
 **Header Pattern:** `x-bf-maxim-{tag-name}`
 **Type:** `map[string]string`
 **Required:** No
 
-Add custom tags to Maxim traces. Any header starting with `x-bf-maxim-` that isn't a reserved header becomes a tag.
+Add Maxim-specific tags to traces. Any header starting with `x-bf-maxim-` that isn't a reserved header becomes a tag.
+
+Use `x-bf-dim-*` for tags that should also appear in logs, OpenTelemetry, and Prometheus. Use `x-bf-maxim-*` only for Maxim-specific tagging or when you need to override a same-named dimension for Maxim.
 
 <Tabs>
 <Tab title="Gateway (cURL)">
@@ -1116,6 +1170,8 @@ Input: messages,
 
 Add custom labels to Prometheus metrics. The `x-bf-prom-` prefix is stripped and the remainder becomes the label name.
 
+This header family is deprecated. Prefer `x-bf-dim-*`, which feeds Prometheus and the other observability backends together. If both `x-bf-dim-foo` and `x-bf-prom-foo` are present, the `x-bf-dim-*` value takes precedence for Prometheus.
+
 <Tabs>
 <Tab title="Gateway (cURL)">
 ```bash