Span Metrics
Learn how span metrics provide enhanced application performance monitoring by attaching custom metrics directly to trace spans.
Span metrics enable you to attach metrics and important debugging context to your application's traces. This approach provides context-rich performance monitoring by connecting metrics directly to the operations that generate them.
Span metrics allow you to enrich trace spans with various types of measurement data:
- Performance metrics (memory usage, processing time, latency)
- Business metrics (transaction value, user engagement rates)
- Technical indicators (queue depth, cache hit ratios)
- Debugging context (input parameters, process states)
By attaching metrics directly to spans, you create a unified view of both the execution path and its associated performance data.
// Adding performance metrics to a database span
const span = Sentry.getActiveSpan();
if (span) {
span.setAttribute("db.rows_returned", 42);
span.setAttribute("db.execution_time_ms", 18);
}
Span metrics provide contextual data that connects execution flow with performance measurements. When investigating an issue, you can view both what occurred (the trace) and the performance characteristics (the metrics) in a single view.
By integrating metrics with tracing, you can maintain a single telemetry pipeline rather than managing separate systems for traces and metrics, resulting in simplified instrumentation and more efficient monitoring.
// Adding business context to a payment processing span
Sentry.startSpan(
{
name: "Process Payment",
op: "payment.process",
attributes: {
"payment.amount": 99.99,
"payment.currency": "USD",
"payment.method": "credit_card",
"customer.type": "returning",
},
},
async () => {
// Payment processing implementation
},
);
When performance issues arise, span metrics provide the necessary context to quickly identify bottlenecks. For example, when investigating slow checkout processes, you can immediately see which specific component (payment gateway, database query, third-party API) is causing the delay.
Span metrics enable correlation between technical performance data and business outcomes by connecting metrics like response time or error rates directly to business metrics such as conversion rates or revenue.
There are two primary methods for implementing span metrics:
Augment automatically-created or manually-defined spans with additional metric attributes:
// Adding metrics to an existing file upload span
const span = Sentry.getActiveSpan();
if (span) {
// Performance metrics
span.setAttribute("file.size_bytes", 15728640); // 15MB
span.setAttribute("upload.time_ms", 3500);
// User context
span.setAttribute("user.subscription_tier", "premium");
span.setAttribute("upload.type", "profile_photo");
// Multiple metrics in a single operation
span.setAttributes({
"memory.heap_used": 1024000,
"processing.steps_completed": 3,
"processing.total_steps": 5,
});
}
Create spans specifically for grouping related metrics, particularly useful for complex operations:
// Creating a span for monitoring external API usage
Sentry.startSpan(
{
name: "Third-Party API Usage",
op: "external.api",
attributes: {
// Performance metrics
"api.response_time_ms": 245,
"api.rate_limit_remaining": 95,
// Resource usage tracking
"api.calls_this_period": 1250,
"api.cost_per_call": 0.001,
// Context data
"feature.using_api": "image_recognition",
"user.plan": "enterprise",
},
},
async () => {
// API call implementation
},
);
The following examples demonstrate how span metrics can be applied to common application scenarios:
Monitor client-side performance metrics related to user experience:
// UI performance monitoring
Sentry.startSpan(
{
name: "Page Interaction",
op: "ui.interaction",
attributes: {
"ui.first_input_delay_ms": 24,
"ui.time_to_interactive_ms": 320,
"ui.frames_dropped": 0,
"user.device_type": "mobile",
"feature.being_used": "image_carousel",
},
},
async () => {
// UI interaction handling
},
);
Track database performance characteristics and their impact on application behavior:
// Database query monitoring
Sentry.startSpan(
{
name: "Product Search Query",
op: "db.query",
attributes: {
"db.query_type": "SELECT",
"db.table": "products",
"db.execution_time_ms": 145,
"db.rows_returned": 87,
"db.index_used": "product_category_idx",
"business.search_term": "winter jacket",
"business.search_filters_applied": 3,
},
},
async () => {
// Database query execution
},
);
Monitor file handling operations across your application stack:
// File processing monitoring
Sentry.startSpan(
{
name: "Process Uploaded Image",
op: "file.process",
attributes: {
// Technical metrics
"file.size_bytes": 2500000,
"file.type": "image/jpeg",
// Processing metrics
"processing.steps_completed": ["virus_scan", "resize", "compress"],
"processing.total_time_ms": 850,
// Context data
"feature.using_upload": "user_avatar",
"subscription.allows_hd": true,
},
},
async () => {
// Image processing implementation
},
);
Monitor performance and reliability of third-party service interactions:
// Payment gateway monitoring
Sentry.startSpan(
{
name: "Payment Gateway",
op: "payment.gateway",
attributes: {
// Performance metrics
"gateway.response_time_ms": 980,
"gateway.retry_count": 0,
// Transaction data
"order.total_amount": 159.99,
"order.items_count": 3,
// Service metrics
"gateway.fee_amount": 4.5,
"gateway.fee_percent": 0.029,
},
},
async () => {
// Payment gateway integration
},
);
To implement span metrics in your application:
- Ensure you have properly configured tracing in your application
- Identify key operations where performance or business metrics would provide valuable insights
- Determine whether to enhance existing spans or create dedicated metric spans
- Implement metrics iteratively, focusing on high-value areas first
Select metrics that provide actionable insights for debugging or performance monitoring. Consider which data points would help diagnose issues or make informed decisions about your application.
Maintain consistent naming patterns following the format category.metric_name to ensure metrics are discoverable and understandable across your organization.
Choose appropriate data types for your metrics:
- Numeric values for measurements (
response_time_ms: 250) - Boolean values for state indicators (
cache.hit: true) - String values for categorical data (
user.subscription: 'premium') - Arrays for multi-value data (
processing.steps_completed: ['download', 'process', 'upload'])
Be mindful of the performance impact of collecting metrics, especially for high-volume operations:
- Consider implementing sampling for high-frequency operations
- Prioritize metrics with the highest analytical value
- Avoid redundant or closely correlated metrics
If you're currently using Sentry's standalone Metrics product, migrating to span metrics offers several advantages:
- Enhanced context: Metrics are connected directly to the operations that generate them
- Implementation efficiency: A single consistent API for both traces and metrics
- Improved correlation: Direct association between metrics, traces, and errors
Migration process:
- Identify your current metric instrumentation points
- Locate corresponding spans in your application
- Transfer your metrics to span attributes
- Update any dashboards or alerts to reference the new metric sources
For more detailed implementation examples, refer to these guides:
- E-commerce transaction flow
- File upload and processing
- LLM integration monitoring
- Job scheduling and processing
These examples demonstrate how to implement comprehensive span metrics across distributed systems, providing end-to-end visibility into application performance and behavior.
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").