Sending Span Metrics

Span metrics allow you to extend the default metrics that are collected by tracing and track custom performance data and debugging information within your application's traces. There are two main approaches to instrumenting metrics:

1. Adding metrics to existing spans
2. Creating dedicated spans with custom metrics

Adding Metrics to Existing Spans

You can enhance existing spans with custom metrics by adding data. This is useful when you want to augment automatic instrumentation or add contextual data to spans you've already created.

span = sentry_sdk.get_current_span()
if span:
    # Add individual metrics
    span.set_data("database.rows_affected", 42)
    span.set_data("cache.hit_rate", 0.85)
    
    # Add multiple metrics at once
    span.set_data({
        "memory.heap_used": 1024000,
        "queue.length": 15,
        "processing.duration_ms": 127
    })

Best Practices for Span Data

When adding metrics as span data:

• Use consistent naming conventions (for example, category.metric_name)
• Keep attribute names concise but descriptive
• Use appropriate data types (string, number, boolean, or an array containing only one of these types)

Creating Dedicated Metric Spans

For more detailed operations, tasks, or process tracking, you can create custom dedicated spans that focus on specific metrics or attributes that you want to track. This approach provides better discoverability and more precise span configurations, however it can also create more noise in your trace waterfall.

with sentry_sdk.start_span(
    op="db.metrics",
    name="Database Query Metrics"
) as span:
    # Set metrics after creating the span
    span.set_data({
        "db.query_type": "SELECT",
        "db.table": "users",
        "db.execution_time_ms": 45,
        "db.rows_returned": 100,
        "db.connection_pool_size": 5
    })
    # Your database operation here
    pass

For detailed examples of how to implement span metrics in common scenarios, see our Span Metrics Examples guide.

Adding Metrics to All Spans

To consistently add metrics across all spans in your application, you can use the before_send_transaction callback:

def before_send_transaction(event):
    # Add metrics to the root span
    if "trace" in event.get("contexts", {}):
        if "data" not in event["contexts"]["trace"]:
            event["contexts"]["trace"]["data"] = {}
        
        event["contexts"]["trace"]["data"].update({
            "app.version": "1.2.3",
            "environment.region": "us-west-2"
        })

    # Add metrics to all child spans
    for span in event.get("spans", []):
        if "data" not in span:
            span["data"] = {}
            
        span["data"].update({
            "app.component_version": "2.0.0",
            "app.deployment_stage": "production"
        })

    return event

sentry_sdk.init(
    # Your other Sentry configuration options here
    before_send_transaction=before_send_transaction
)

Best Practices for Span Metrics

1. Metric Naming

   • Use clear, consistent naming patterns
   • Include the metric category (examples: db, cache, http)
   • Use snake_case for metric names

2. Data Types

   • Use appropriate numeric types for measurements
   • Use booleans for status flags
   • Use strings for categorical data
   • Use arrays when grouping related values

3. Performance Considerations

   • Consider the overhead of metric collection
   • Use sampling when collecting high-frequency metrics
   • Balance metric granularity with system performance

4. Debugging and Monitoring

   • Include correlation IDs for related operations
   • Add context that helps with troubleshooting

Best Practices for Implementation

When implementing span metrics in your application:

1. Start Small and Iterate

   • Begin with basic metrics that directly relate to your debugging or performance monitoring needs
   • Add more detailed tracking as specific debugging needs emerge
   • Remove metrics that aren't providing actionable insights

2. Maintain Consistency

   • Use consistent naming patterns across your application
   • Document metric meanings and units in your codebase
   • Share common metrics across similar operations

3. Focus on Actionability

   • Track metrics that help diagnose specific issues
   • Consider what alerts or dashboard visualizations you'll want to create
   • Ensure metrics can drive issue resolution or decision making

For detailed examples of how to implement span metrics in common scenarios, see our Span Metrics Examples guide.