Sending Span Metrics

Learn how to add attributes to spans in Sentry to monitor performance and debug applications

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

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.

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

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)

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.

Copied
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.

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

Copied
import sentry_sdk
from sentry_sdk.types import Event, Hint

def before_send_transaction(event: Event, hint: Hint) -> Event | None:
    # 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(
    # ...
    before_send_transaction=before_send_transaction
)

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

Previous
Span Lifecycle
Next
Example Instrumentation
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").