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.

Attributes Best Practices

On this page