Attributes Best Practices

Best practices for creating effective attributes in your AI applications

Follow these best practices to create meaningful, well-organized attributes that provide valuable context and metadata for your traces and spans.

🎯 Consistent Naming

Hierarchical Naming

# Good: Consistent and descriptive
"customer.id" = "cust_123"
"customer.tier" = "premium"
"customer.region" = "us-west"
 
# Bad: Inconsistent and unclear
"cust_id" = "cust_123"
"tier" = "premium"
"region" = "us-west"

Use Consistent Prefixes

# 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

📊 Logical Grouping

# Group related attributes together
span.set_attributes({
    # Customer context
    "customer.id": customer_id,
    "customer.tier": customer_tier,
    "customer.region": customer_region,
    
    # Query context
    "query.type": query_type,
    "query.priority": query_priority,
    "query.language": query_language,
    
    # AI context
    "ai.model": model_name,
    "ai.provider": provider,
    "ai.temperature": temperature
})

Use Meaningful Values

# Good: Descriptive and meaningful
"query.type" = "technical_support"
"customer.tier" = "premium"
"ai.model" = "gpt-4"
 
# Bad: Generic or unclear
"query.type" = "type1"
"customer.tier" = "tier2"
"ai.model" = "model1"

🎪 Performance Considerations

Essential Attributes Only

# Good: Essential attributes only
span.set_attributes({
    "customer.id": customer_id,
    "query.type": query_type,
    "ai.model": model_name
})
 
# Bad: Too many attributes
span.set_attributes({
    "customer.id": customer_id,
    "customer.name": customer_name,
    "customer.email": customer_email,
    "customer.phone": customer_phone,
    "customer.address": customer_address,
    # ... 50 more attributes
})

Use 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")

🔄 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 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
    }
})

🔍 Business Context

Include Business Metrics

span.set_attributes({
    "business.operation": "customer_support",
    "business.priority": "high",
    "business.customer_tier": "premium",
    "business.region": "us-west",
    "business.feature": "chatbot",
    "business.cost_center": "support_team"
})

Track Business Outcomes

span.set_attributes({
    "business.outcome.satisfaction": 4.5,
    "business.outcome.resolution_time_minutes": 15,
    "business.outcome.escalation_required": False,
    "business.outcome.follow_up_needed": True
})

🎯 AI-Specific Attributes

Model Configuration

span.set_attributes({
    "ai.model": "gpt-4",
    "ai.provider": "openai",
    "ai.temperature": 0.7,
    "ai.max_tokens": 1000,
    "ai.top_p": 0.9,
    "ai.frequency_penalty": 0.0,
    "ai.presence_penalty": 0.0
})

Usage and Cost

span.set_attributes({
    "ai.prompt_tokens": 150,
    "ai.completion_tokens": 200,
    "ai.total_tokens": 350,
    "ai.cost_usd": 0.0023,
    "ai.cost_per_token": 0.0000066
})

Response Quality

span.set_attributes({
    "ai.finish_reason": "stop",
    "ai.response_length": 200,
    "ai.confidence_score": 0.85,
    "ai.quality_rating": "high"
})

🛠️ Debugging Support

Include Debug Information

span.set_attributes({
    "debug.trace_id": trace_id,
    "debug.span_id": span_id,
    "debug.timestamp": time.time(),
    "debug.version": "1.2.3",
    "debug.environment": "production"
})

Trace Correlation

# Use consistent correlation IDs
correlation_id = generate_correlation_id()
span.set_attribute("correlation.id", correlation_id)
 
# Pass correlation ID to external services
external_service_call(correlation_id=correlation_id)

🔍 Filtering and Search

Searchable Attributes

# Make attributes searchable with consistent naming
span.set_attributes({
    "customer.tier": "premium",  # Searchable: customer.tier:premium
    "query.type": "technical_support",  # Searchable: query.type:technical_support
    "ai.model": "gpt-4",  # Searchable: ai.model:gpt-4
    "performance.latency_ms": 1800  # Searchable: performance.latency_ms:>1000
})

Aggregation-Friendly Attributes

# Use consistent naming for aggregation
span.set_attributes({
    "ai.model": "gpt-4",  # Group by: ai.model
    "customer.tier": "premium",  # Group by: customer.tier
    "performance.latency_ms": 1800,  # Aggregate: performance.latency_ms
    "ai.cost_usd": 0.0023  # Aggregate: ai.cost_usd
})

🚀 Next Steps

Now that you understand attribute best practices, explore these related concepts:

Traces Best Practices - Best practices for complete request journeys
Spans Best Practices - Best practices for individual operations
Events Best Practices - Best practices for point-in-time occurrences

Well-organized attributes provide the context and metadata that make your traces meaningful. By following these best practices, you'll create attributes that enable powerful analysis and debugging.