mirror of
https://github.com/katanemo/plano.git
synced 2026-04-25 00:36:34 +02:00
743d074184
Some checks are pending
CI / pre-commit (push) Waiting to run
CI / plano-tools-tests (push) Waiting to run
CI / native-smoke-test (push) Waiting to run
CI / docker-build (push) Waiting to run
CI / validate-config (push) Waiting to run
CI / security-scan (push) Blocked by required conditions
CI / test-prompt-gateway (push) Blocked by required conditions
CI / test-model-alias-routing (push) Blocked by required conditions
CI / test-responses-api-with-state (push) Blocked by required conditions
CI / e2e-plano-tests (3.10) (push) Blocked by required conditions
CI / e2e-plano-tests (3.11) (push) Blocked by required conditions
CI / e2e-plano-tests (3.12) (push) Blocked by required conditions
CI / e2e-plano-tests (3.13) (push) Blocked by required conditions
CI / e2e-plano-tests (3.14) (push) Blocked by required conditions
CI / e2e-demo-preference (push) Blocked by required conditions
CI / e2e-demo-currency (push) Blocked by required conditions
Publish docker image (latest) / build-arm64 (push) Waiting to run
Publish docker image (latest) / build-amd64 (push) Waiting to run
Publish docker image (latest) / create-manifest (push) Blocked by required conditions
Build and Deploy Documentation / build (push) Waiting to run
* feat: add initial documentation for Plano Agent Skills * feat: readme with examples * feat: add detailed skills documentation and examples for Plano --------- Co-authored-by: Adil Hafeez <adil.hafeez@gmail.com>
80 lines
2.4 KiB
Markdown
80 lines
2.4 KiB
Markdown
---
|
|
title: Add Custom Span Attributes for Correlation and Filtering
|
|
impact: MEDIUM
|
|
impactDescription: Without custom span attributes, traces cannot be filtered by user, session, or environment — making production debugging significantly harder
|
|
tags: observability, tracing, span-attributes, correlation
|
|
---
|
|
|
|
## Add Custom Span Attributes for Correlation and Filtering
|
|
|
|
Plano can automatically extract HTTP request headers and attach them as span attributes, plus attach static key-value pairs to every span. This enables filtering traces by user, session, tenant, environment, or any other dimension that matters to your application.
|
|
|
|
**Incorrect (no span attributes — traces are unfiltered blobs):**
|
|
|
|
```yaml
|
|
tracing:
|
|
random_sampling: 20
|
|
# No span_attributes — cannot filter by user, session, or environment
|
|
```
|
|
|
|
**Correct (rich span attributes for production correlation):**
|
|
|
|
```yaml
|
|
version: v0.3.0
|
|
|
|
tracing:
|
|
random_sampling: 20
|
|
trace_arch_internal: true
|
|
|
|
span_attributes:
|
|
# Match all headers with this prefix, then map to span attributes by:
|
|
# 1) stripping the prefix and 2) converting hyphens to dots
|
|
header_prefixes:
|
|
- x-katanemo-
|
|
|
|
# Static attributes added to every span from this Plano instance
|
|
static:
|
|
environment: production
|
|
service.name: plano-gateway
|
|
deployment.region: us-east-1
|
|
service.version: "2.1.0"
|
|
team: platform-engineering
|
|
```
|
|
|
|
**Sending correlation headers from client code:**
|
|
|
|
```python
|
|
import httpx
|
|
|
|
response = httpx.post(
|
|
"http://localhost:12000/v1/chat/completions",
|
|
headers={
|
|
"x-katanemo-request-id": "req_abc123",
|
|
"x-katanemo-user-id": "usr_12",
|
|
"x-katanemo-session-id": "sess_xyz456",
|
|
"x-katanemo-tenant-id": "acme-corp",
|
|
},
|
|
json={"model": "plano.v1", "messages": [...]}
|
|
)
|
|
```
|
|
|
|
**Querying by custom attribute:**
|
|
|
|
```bash
|
|
# Find all requests from a specific user
|
|
planoai trace --where user.id=usr_12
|
|
|
|
# Find all traces from production environment
|
|
planoai trace --where environment=production
|
|
|
|
# Find traces from a specific tenant
|
|
planoai trace --where tenant.id=acme-corp
|
|
```
|
|
|
|
Header prefix matching is a prefix match. With `x-katanemo-`, these mappings apply:
|
|
|
|
- `x-katanemo-user-id` -> `user.id`
|
|
- `x-katanemo-tenant-id` -> `tenant.id`
|
|
- `x-katanemo-request-id` -> `request.id`
|
|
|
|
Reference: [https://github.com/katanemo/archgw](https://github.com/katanemo/archgw)
|