Documentation
Core Concepts/Attributes - Metadata and Context

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": "success",
    "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

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 provide the context and metadata that make your traces meaningful. They enable powerful analysis, debugging, and optimization of your AI applications.

Exclusive Early Access

Get Early Access to Noveum.ai Platform

Be the first one to get notified when we open Noveum Platform to more users. All users get access to Observability suite for free, early users get free eval jobs and premium support for the first year.

Sign up now. We send access to new batch every week.

Early access members receive premium onboarding support and influence our product roadmap. Limited spots available.

Previous

Spans - Individual Operations

Next

Events - Point-in-Time Occurrences

On this page