mirror of
https://github.com/katanemo/plano.git
synced 2026-04-25 00:36:34 +02:00
81 lines
2.4 KiB
Markdown
81 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)
|