Traccia enriches spans with structured attributes and events. This page documents all standard and Traccia-specific attributes you'll find in your traces.

Standard OpenTelemetry Attributes

These are standard OTel semantic conventions used by Traccia:

Attribute	Description
`service.name`	Service identifier (auto-detected or configured)
`http.method`	HTTP method (GET, POST, etc.)
`http.url`	Full request URL
`http.status_code`	HTTP response status code
`http.target`	Request target path

LLM Span Attributes

Automatically added to spans created by LLM calls (OpenAI, Anthropic):

Attribute	Description
`llm.model`	Model name (e.g., "gpt-4", "claude-3-opus")
`llm.provider`	Provider name ("openai", "anthropic")
`llm.usage.prompt_tokens`	Tokens in the prompt/input
`llm.usage.completion_tokens`	Tokens in the completion/output
`llm.usage.total_tokens`	Total tokens used (prompt + completion)
`llm.usage.source`	Where token counts came from (provider_usage, tiktoken, mixed)
`llm.cost.usd`	Estimated cost in USD
`llm.pricing.source`	Pricing snapshot source used for cost calculation
`llm.pricing.model_key`	Matched key in the pricing table
`llm.temperature`	Model temperature parameter
`llm.max_tokens`	Max tokens parameter
`llm.prompt`	Prompt text (truncated, if captured)

Agent Metadata Attributes

Added by the AgentEnrichmentProcessor to all spans:

Attribute	Description
`agent.id`	Agent identifier
`session.id`	Session identifier
`user.id`	User identifier
`tenant.id`	Tenant/organization identifier
`project.id`	Project identifier
`trace.debug`	Debug mode flag (true/false)

Span Classification Attributes

Used for categorizing and filtering spans:

Attribute	Description
`span.type`	Span type: "span", "llm", "tool"
`span.tags`	Array of string tags from @observe(tags=...)
`traccia.auto_started`	True if this is an auto-started root trace

Prompt Identity Attributes

Set on the active span when you call compile on a prompt loaded via the SDK. See Prompts in the SDK. Identity keys are allowlisted so redaction does not wipe them.

Attribute	Description
`traccia.prompt.name`	Library prompt name
`traccia.prompt.version`	Integer version number
`traccia.prompt.version_id`	Stable version UUID
`traccia.prompt.label`	Resolved deploy label, if any
`traccia.prompt.is_fallback`	true when an explicit fallback body was used (omit otherwise)

Error Attributes

Added automatically when exceptions occur:

Attribute	Description
`error.type`	Exception class name (e.g., "ValueError", "KeyError")
`error.message`	Exception message
`error.stack_trace`	Full stack trace (truncated to 2000 chars)

Function Arguments

When using @observe(), function arguments are automatically captured as span attributes (unless excluded withskip_args):

python

@observe()
def process_order(order_id: str, amount: float, priority: int):
    pass

# Resulting span attributes:
# - order_id: "12345"
# - amount: 99.99
# - priority: 1
# - result: <return value> (unless skip_result=True)

Type conversion

Complex types (objects, lists, dicts) are automatically converted to JSON strings and truncated to 1000 characters to keep spans manageable.

Span Events

Events are timestamped occurrences within a span. They're created byspan.add_event() or automatically when exceptions are recorded.

Standard Event Types

Attribute	Description
`exception`	Automatically created when `record_exception()` is called. Includes exception type, message, and stack trace.

Custom Events

python

from traccia import span

with span("process_payment") as s:
    s.add_event("Payment validation started")
    
    validate_card()
    s.add_event("Card validated", {
        "card_type": "visa",
        "last_four": "1234"
    })
    
    charge_card()
    s.add_event("Payment processed", {
        "transaction_id": "txn_abc123",
        "amount": 99.99
    })

Event Structure

json

{
  "name": "Payment processed",
  "timestamp": "2024-01-15T10:30:00.123456Z",
  "attributes": {
    "transaction_id": "txn_abc123",
    "amount": 99.99
  }
}

Resource Attributes

Resource attributes describe the entity producing the spans and apply to all spans from that process:

Attribute	Description
`service.name`	Service name (auto-detected or configured)
`tenant.id`	Tenant identifier (if configured)
`project.id`	Project identifier (if configured)
`session.id`	Session identifier (if configured)
`user.id`	User identifier (if configured)
`agent.id`	Agent identifier (if configured)
`agent.name`	Agent display name (if configured)
`env`	Deployment environment (e.g., production, staging)
`traccia.service_role`	Service role for multi-agent hosts (e.g., orchestrator)
`trace.debug`	Debug mode flag when debug tracing is enabled

Complete Span Example

Here's what a complete LLM span looks like in JSON format:

json

{
  "name": "openai.chat.completions.create",
  "context": {
    "trace_id": "0x1234567890abcdef1234567890abcdef",
    "span_id": "0xabcdef1234567890",
    "parent_span_id": "0x9876543210fedcba"
  },
  "kind": "INTERNAL",
  "start_time": "2024-01-15T10:30:00.000000Z",
  "end_time": "2024-01-15T10:30:02.500000Z",
  "status": {
    "status_code": "OK"
  },
  "attributes": {
    "span.type": "llm",
    "llm.model": "gpt-4",
    "llm.provider": "openai",
    "llm.temperature": 0.7,
    "llm.max_tokens": 500,
    "llm.usage.prompt_tokens": 45,
    "llm.usage.completion_tokens": 405,
    "llm.usage.total_tokens": 450,
    "llm.usage.source": "provider_usage",
    "llm.cost.usd": 0.0135,
    "llm.pricing.source": "bundled",
    "llm.pricing.model_key": "gpt-4",
    "agent.id": "research-assistant",
    "session.id": "session-abc123",
    "user.id": "user-xyz789",
    "tenant.id": "acme-corp",
    "project.id": "ml-research"
  },
  "events": [],
  "resource": {
    "service.name": "my-agent-app",
    "tenant.id": "acme-corp",
    "project.id": "ml-research",
    "agent.id": "research-assistant",
    "env": "production"
  }
}

Governance Attributes

Added when using governance enrichment, disclosure(), enrich_governance_attributes(), or ingest normalization. See Python SDK API (Governance section).

Attribute	Description
`governance.event_type`	inference, tool_call, transparency
`governance.timestamp_source`	sdk \| ingest
`governance.integrity_hash`	tamper-evident fingerprint
`governance.input_hash`	SHA-256 of input (not raw prompt)
`governance.output_hash`	SHA-256 of output
`governance.transparency.disclosed`	Art. 50 (disclosure())
`governance.redaction_applied`	after redact_pii
`eu_ai_act.risk_tier`	from init(compliance=...)

Querying by Attributes

Use these attributes to filter and query traces in Jaeger, Grafana, or the Traccia Platform:

Jaeger

text

# Find traces with high costs
tags: llm.cost.usd > 1.0

# Find traces for specific agent
tags: agent.id="billing-agent"

# Find errors
tags: error.type="ValueError"

Grafana (TraceQL)