Instrumentation quality determines how useful observability and improvement workflows become. Adaline can show traces without rich metadata, but filters, Deep Search, Behaviors, datasets, and Improve all work better when your application sends consistent context.
Good trace metadata lets your team answer:
- Which environment produced this request?
- Which release, feature flag, route, or workflow was active?
- Which user segment or tenant type was involved?
- Which prompt, agent, tool, or provider path ran?
- Which traces belong to a known incident or experiment?
- Which examples are safe and useful for datasets?
| Metadata | Best for | Examples |
|---|
| Tags | Short labels for grouping and filtering. | production, staging, checkout, release-2026-06, vip-customer |
| Attributes | Key-value context. | route=/refunds, region=us-east, tenant_tier=enterprise, feature_flag=new-router |
| Trace name | Human-readable workflow name. | support-chat, policy-lookup, running-plan-generator |
| Span name | Human-readable step name. | model:answer-user, tool:get-order, retrieval:policy-search |
| IDs | Exact debugging and API lookup. | trace ID, span ID, session ID, reference ID |
Recommended attributes
For most production integrations, send:
environment: production, staging, development, or QA.release: application version, deployment ID, or commit SHA.route or workflow: the product path.feature: the AI feature or agent name.tenant_tier or segment: if allowed by your privacy policy.region or locale: when behavior varies by location or language.experiment or feature_flag: when comparing variants.prompt_key or prompt context: when your runtime can attach it safely.
Avoid raw emails, API keys, access tokens, secrets, private IDs, and unnecessary personal data.
Span naming
Name spans so operators can understand the trace tree without reading every payload.
Good span names:
model:classify-intentretrieval:search-policytool:get-customer-planguardrail:pii-checkorchestration:route-to-agent
Weak span names:
callstep1llmfunctiontemp
Clear span names make Traces, Behavior analysis, Deep Search source filters, and debugging much easier.
Prompt and deployment context
When possible, attach the prompt, environment, or release context your application used. This helps connect runtime traces back to:
- Prompt library rows.
- Deployment snapshots.
- Deployment environments.
- Improve cycles.
- Evaluation and regression evidence.
Your exact integration may use SDK, API, proxy, or deployment reads. The important principle is that runtime evidence should point back to the object a reviewer can change.
Behaviors cluster semantic patterns from traces. Good metadata helps reviewers interpret those clusters:
- Route and workflow explain where the behavior happens.
- Release tags help identify new or changed patterns after deployment.
- Tool span names show whether a behavior is user, assistant, or tool-related.
- Segment attributes show whether an issue is concentrated in one user group.
- Environment tags keep staging and production traffic from being confused.
When a trace becomes a dataset row or Improve evidence, metadata helps reviewers understand the source:
- Was the case production or staging?
- Which release produced the failure?
- Which Behavior did it belong to?
- Which route or customer segment was affected?
- Is the row safe to keep as long-term regression data?
See Add spans to datasets for the production-evidence workflow.
Privacy checklist
Before sending metadata:
- Use stable internal labels instead of raw personal identifiers.
- Hash or omit user identifiers when possible.
- Do not send secrets, keys, headers, tokens, or credentials.
- Do not put API keys in tags, attributes, trace names, or span names.
- Follow your team’s retention and data-handling policy.
- Sanitize screenshots and exports that include trace data.
Instrumentation is easiest to fix before an incident. Add route, environment, release, and meaningful span names during integration, then your future debugging sessions will have the map already drawn.
