Attributes - Metadata and Context

Understanding attributes and how they provide rich metadata and context for your traces and spans

Attributes are key-value pairs that provide rich metadata and context for your traces and spans. They help you understand what happened during an operation, why it happened, and what the results were.

🎯 What are Attributes?

Attributes are structured data that describe:

What happened during an operation
Why an operation was performed
How an operation was configured
What the results were
Who or what triggered the operation

🏗️ Attribute Structure

Every attribute has:

Key: A descriptive name (e.g., customer.id, ai.model)
Value: The actual data (string, number, boolean, or object)
Type: Automatically inferred from the value
Scope: Trace-level or span-level

📊 Attribute Categories

System Attributes

span.set_attributes({
    "trace.id": "trace_12345",
    "span.id": "span_67890",
    "span.name": "gpt-4-completion",
    "span.duration_ms": 1800,
    "span.status": "ok",
    "span.start_time": "2024-01-15T10:30:00Z",
    "span.end_time": "2024-01-15T10:30:01.8Z"
})

AI-Specific Attributes

span.set_attributes({
    "ai.model": "gpt-4",
    "ai.provider": "openai",
    "ai.temperature": 0.7,
    "ai.max_tokens": 1000,
    "ai.prompt_tokens": 150,
    "ai.completion_tokens": 200,
    "ai.total_tokens": 350,
    "ai.cost_usd": 0.0023,
    "ai.finish_reason": "stop"
})

Business Attributes

span.set_attributes({
    "customer.id": "cust_12345",
    "customer.tier": "premium",
    "customer.region": "us-west",
    "query.type": "technical_support",
    "query.priority": "high",
    "query.language": "en",
    "query.sentiment": "neutral"
})

Performance Attributes

span.set_attributes({
    "performance.latency_ms": 1800,
    "performance.throughput_rps": 5.2,
    "performance.cpu_usage": 0.75,
    "performance.memory_mb": 512,
    "performance.cache_hit_rate": 0.85
})

🎯 Attribute Naming Conventions

Hierarchical Naming

Use dot notation to create logical hierarchies:

# AI-related attributes
"ai.model" = "gpt-4"
"ai.provider" = "openai"
"ai.temperature" = 0.7
"ai.max_tokens" = 1000

# Customer-related attributes
"customer.id" = "cust_123"
"customer.tier" = "premium"
"customer.region" = "us-west"

# Query-related attributes
"query.type" = "technical_support"
"query.priority" = "high"
"query.language" = "en"

Consistent Prefixes

Use consistent prefixes for related attributes:

# System attributes
"system.duration_ms" = 1800
"system.status" = "success"
"system.version" = "1.2.3"

# Business attributes
"business.operation" = "customer_support"
"business.priority" = "high"
"business.feature" = "chatbot"

# Performance attributes
"perf.latency_ms" = 1800
"perf.throughput_rps" = 5.2
"perf.cpu_usage" = 0.75

🔄 Setting Attributes

Single Attributes

span.set_attribute("customer.id", "cust_123")
span.set_attribute("query.type", "technical_support")
span.set_attribute("ai.model", "gpt-4")

Multiple Attributes

span.set_attributes({
    "customer.id": "cust_123",
    "customer.tier": "premium",
    "query.type": "technical_support",
    "query.priority": "high",
    "ai.model": "gpt-4",
    "ai.temperature": 0.7
})

Conditional Attributes

# Add attributes based on conditions
if customer_tier == "premium":
    span.set_attribute("customer.priority", "high")
    span.set_attribute("ai.model", "gpt-4")
else:
    span.set_attribute("customer.priority", "normal")
    span.set_attribute("ai.model", "gpt-3.5-turbo")

📈 Attribute Types

String Attributes

span.set_attributes({
    "customer.id": "cust_123",
    "query.type": "technical_support",
    "ai.model": "gpt-4",
    "ai.provider": "openai"
})

Numeric Attributes

span.set_attributes({
    "query.length": 45,
    "ai.temperature": 0.7,
    "ai.max_tokens": 1000,
    "performance.latency_ms": 1800
})

Boolean Attributes

span.set_attributes({
    "customer.is_premium": True,
    "query.is_urgent": False,
    "ai.fallback_used": False,
    "performance.cache_hit": True
})

Array Attributes

span.set_attributes({
    "query.keywords": ["support", "login", "error"],
    "ai.models_tried": ["gpt-4", "gpt-3.5-turbo"],
    "performance.regions": ["us-west", "us-east"]
})

Object Attributes

span.set_attributes({
    "customer.profile": {
        "id": "cust_123",
        "tier": "premium",
        "region": "us-west",
        "signup_date": "2024-01-01"
    },
    "ai.config": {
        "model": "gpt-4",
        "temperature": 0.7,
        "max_tokens": 1000
    }
})

🎪 Dynamic Attributes

Runtime Attributes

with trace_operation("process-query") as span:
    # Add attributes as the operation progresses
    span.set_attribute("query.length", len(query))
    
    # Process the query
    result = process_query(query)
    
    # Add result attributes
    span.set_attribute("result.length", len(result))
    span.set_attribute("result.confidence", result.confidence)
    
    # Add performance attributes
    span.set_attribute("processing.time_ms", time.time() - start_time)

Conditional Attributes

with trace_operation("ai-completion") as span:
    # Add base attributes
    span.set_attributes({
        "ai.model": model_name,
        "ai.temperature": temperature,
        "query.length": len(query)
    })
    
    # Add conditional attributes based on results
    if response.finish_reason == "stop":
        span.set_attribute("ai.completion_reason", "normal")
    elif response.finish_reason == "length":
        span.set_attribute("ai.completion_reason", "max_tokens")
        span.set_attribute("ai.truncated", True)
    
    # Add cost attributes
    if hasattr(response, 'usage'):
        span.set_attributes({
            "ai.prompt_tokens": response.usage.prompt_tokens,
            "ai.completion_tokens": response.usage.completion_tokens,
            "ai.total_tokens": response.usage.total_tokens
        })

🔍 Attribute Analysis

Filtering and Search

Attributes enable powerful filtering and search:

# Find all traces for premium customers
traces = search_traces(attributes={"customer.tier": "premium"})

# Find all GPT-4 completions
traces = search_traces(attributes={"ai.model": "gpt-4"})

# Find high-priority queries
traces = search_traces(attributes={"query.priority": "high"})

# Find traces with high latency
traces = search_traces(attributes={"performance.latency_ms": {"$gt": 5000}})

Aggregation and Analytics

# Average latency by model
avg_latency = aggregate_traces(
    group_by="ai.model",
    metric="performance.latency_ms",
    operation="avg"
)

# Cost by customer tier
cost_by_tier = aggregate_traces(
    group_by="customer.tier",
    metric="ai.cost_usd",
    operation="sum"
)

# Success rate by query type
success_rate = aggregate_traces(
    group_by="query.type",
    metric="span.status",
    operation="success_rate"
)

🚀 Next Steps

Now that you understand attributes, explore these related concepts:

Traces - Complete request journeys
Spans - Individual operations
Events - Point-in-time occurrences

Best Practices

Attributes Best Practices - Learn how to create effective attributes

Attributes provide the context and metadata that make your traces meaningful. They enable powerful analysis, debugging, and optimization of your AI applications.

Attributes - Metadata and Context

On this page