Skip to content

Commit 91aa869

Browse files
codydecodyde
committed
adding span metrics to explore; setting redirect from metrics
1 parent 4c01d7f commit 91aa869

File tree

2 files changed

+304
-0
lines changed

2 files changed

+304
-0
lines changed

‎docs/product/tracing/span-metrics/index.mdx

+300
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,300 @@
1+
---
2+
title: Span Metrics
3+
description: "Learn how span metrics provide enhanced application performance monitoring by attaching custom metrics directly to trace spans."
4+
sidebar_order: 10
5+
---
6+
7+
# Span Metrics
8+
9+
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.
10+
11+
## What Are Span Metrics?
12+
13+
Span metrics allow you to enrich trace spans with various types of measurement data:
14+
15+
- Performance metrics (memory usage, processing time, latency)
16+
- Business metrics (transaction value, user engagement rates)
17+
- Technical indicators (queue depth, cache hit ratios)
18+
- Debugging context (input parameters, process states)
19+
20+
By attaching metrics directly to spans, you create a unified view of both the execution path and its associated performance data.
21+
22+
```javascript
23+
// Adding performance metrics to a database span
24+
const span = Sentry.getActiveSpan();
25+
if (span) {
26+
span.setAttribute('db.rows_returned', 42);
27+
span.setAttribute('db.execution_time_ms', 18);
28+
}
29+
```
30+
31+
## Benefits of Span Metrics
32+
33+
### Contextual Observability
34+
35+
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.
36+
37+
### Unified Telemetry
38+
39+
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.
40+
41+
```javascript
42+
// Adding business context to a payment processing span
43+
Sentry.startSpan(
44+
{
45+
name: 'Process Payment',
46+
op: 'payment.process',
47+
attributes: {
48+
'payment.amount': 99.99,
49+
'payment.currency': 'USD',
50+
'payment.method': 'credit_card',
51+
'customer.type': 'returning'
52+
}
53+
},
54+
async () => {
55+
// Payment processing implementation
56+
}
57+
);
58+
```
59+
60+
### Accelerated Troubleshooting
61+
62+
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.
63+
64+
### Technical-Business Correlation
65+
66+
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.
67+
68+
## Implementation Approaches
69+
70+
There are two primary methods for implementing span metrics:
71+
72+
### 1. Enhancing Existing Spans
73+
74+
Augment automatically created or manually defined spans with additional metric attributes:
75+
76+
```javascript
77+
// Adding metrics to an existing file upload span
78+
const span = Sentry.getActiveSpan();
79+
if (span) {
80+
// Performance metrics
81+
span.setAttribute('file.size_bytes', 15728640); // 15MB
82+
span.setAttribute('upload.time_ms', 3500);
83+
84+
// User context
85+
span.setAttribute('user.subscription_tier', 'premium');
86+
span.setAttribute('upload.type', 'profile_photo');
87+
88+
// Multiple metrics in a single operation
89+
span.setAttributes({
90+
'memory.heap_used': 1024000,
91+
'processing.steps_completed': 3,
92+
'processing.total_steps': 5
93+
});
94+
}
95+
```
96+
97+
### 2. Creating Dedicated Metric Spans
98+
99+
Create spans specifically for grouping related metrics, particularly useful for complex operations:
100+
101+
```javascript
102+
// Creating a span for monitoring external API usage
103+
Sentry.startSpan(
104+
{
105+
name: 'Third-Party API Usage',
106+
op: 'external.api',
107+
attributes: {
108+
// Performance metrics
109+
'api.response_time_ms': 245,
110+
'api.rate_limit_remaining': 95,
111+
112+
// Resource usage tracking
113+
'api.calls_this_period': 1250,
114+
'api.cost_per_call': 0.001,
115+
116+
// Context data
117+
'feature.using_api': 'image_recognition',
118+
'user.plan': 'enterprise'
119+
}
120+
},
121+
async () => {
122+
// API call implementation
123+
}
124+
);
125+
```
126+
127+
## Implementation Use Cases
128+
129+
The following examples demonstrate how span metrics can be applied to common application scenarios:
130+
131+
### User Interface Performance
132+
133+
Monitor client-side performance metrics related to user experience:
134+
135+
```javascript
136+
// UI performance monitoring
137+
Sentry.startSpan(
138+
{
139+
name: 'Page Interaction',
140+
op: 'ui.interaction',
141+
attributes: {
142+
'ui.first_input_delay_ms': 24,
143+
'ui.time_to_interactive_ms': 320,
144+
'ui.frames_dropped': 0,
145+
'user.device_type': 'mobile',
146+
'feature.being_used': 'image_carousel'
147+
}
148+
},
149+
async () => {
150+
// UI interaction handling
151+
}
152+
);
153+
```
154+
155+
### Database Operation Monitoring
156+
157+
Track database performance characteristics and their impact on application behavior:
158+
159+
```javascript
160+
// Database query monitoring
161+
Sentry.startSpan(
162+
{
163+
name: 'Product Search Query',
164+
op: 'db.query',
165+
attributes: {
166+
'db.query_type': 'SELECT',
167+
'db.table': 'products',
168+
'db.execution_time_ms': 145,
169+
'db.rows_returned': 87,
170+
'db.index_used': 'product_category_idx',
171+
'business.search_term': 'winter jacket',
172+
'business.search_filters_applied': 3
173+
}
174+
},
175+
async () => {
176+
// Database query execution
177+
}
178+
);
179+
```
180+
181+
### File Processing Operations
182+
183+
Monitor file handling operations across your application stack:
184+
185+
```javascript
186+
// File processing monitoring
187+
Sentry.startSpan(
188+
{
189+
name: 'Process Uploaded Image',
190+
op: 'file.process',
191+
attributes: {
192+
// Technical metrics
193+
'file.size_bytes': 2500000,
194+
'file.type': 'image/jpeg',
195+
196+
// Processing metrics
197+
'processing.steps_completed': ['virus_scan', 'resize', 'compress'],
198+
'processing.total_time_ms': 850,
199+
200+
// Context data
201+
'feature.using_upload': 'user_avatar',
202+
'subscription.allows_hd': true
203+
}
204+
},
205+
async () => {
206+
// Image processing implementation
207+
}
208+
);
209+
```
210+
211+
### External Service Integration
212+
213+
Monitor performance and reliability of third-party service interactions:
214+
215+
```javascript
216+
// Payment gateway monitoring
217+
Sentry.startSpan(
218+
{
219+
name: 'Payment Gateway',
220+
op: 'payment.gateway',
221+
attributes: {
222+
// Performance metrics
223+
'gateway.response_time_ms': 980,
224+
'gateway.retry_count': 0,
225+
226+
// Transaction data
227+
'order.total_amount': 159.99,
228+
'order.items_count': 3,
229+
230+
// Service metrics
231+
'gateway.fee_amount': 4.50,
232+
'gateway.fee_percent': 0.029
233+
}
234+
},
235+
async () => {
236+
// Payment gateway integration
237+
}
238+
);
239+
```
240+
241+
## Implementation Guidelines
242+
243+
### Getting Started
244+
245+
To implement span metrics in your application:
246+
247+
1. Ensure you have [properly configured tracing](/product/tracing/) in your application
248+
2. Identify key operations where performance or business metrics would provide valuable insights
249+
3. Determine whether to enhance existing spans or create dedicated metric spans
250+
4. Implement metrics iteratively, focusing on high-value areas first
251+
252+
### Best Practices
253+
254+
#### Metric Selection and Design
255+
256+
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.
257+
258+
#### Naming Conventions
259+
260+
Maintain consistent naming patterns following the format `category.metric_name` to ensure metrics are discoverable and understandable across your organization.
261+
262+
#### Data Type Selection
263+
264+
Choose appropriate data types for your metrics:
265+
- Numeric values for measurements (`response_time_ms`: 250)
266+
- Boolean values for state indicators (`cache.hit`: true)
267+
- String values for categorical data (`user.subscription`: 'premium')
268+
- Arrays for multi-value data (`processing.steps_completed`: ['download', 'process', 'upload'])
269+
270+
#### Performance Considerations
271+
272+
Be mindful of the performance impact of collecting metrics, especially for high-volume operations:
273+
- Consider implementing sampling for high-frequency operations
274+
- Prioritize metrics with the highest analytical value
275+
- Avoid redundant or closely correlated metrics
276+
277+
## Migrating from Standalone Metrics
278+
279+
If you're currently using Sentry's standalone Metrics product, migrating to span metrics offers several advantages:
280+
281+
- **Enhanced context**: Metrics are connected directly to the operations that generate them
282+
- **Implementation efficiency**: A single consistent API for both traces and metrics
283+
- **Improved correlation**: Direct association between metrics, traces, and errors
284+
285+
Migration process:
286+
1. Identify your current metric instrumentation points
287+
2. Locate corresponding spans in your application
288+
3. Transfer your metrics to span attributes
289+
4. Update any dashboards or alerts to reference the new metric sources
290+
291+
## Additional Resources
292+
293+
For more detailed implementation examples, refer to these guides:
294+
295+
- [E-commerce transaction flow](/platforms/javascript/tracing/span-metrics/examples/#e-commerce-transaction-flow)
296+
- [File upload and processing](/platforms/javascript/tracing/span-metrics/examples/#file-upload-and-processing-pipeline)
297+
- [LLM integration monitoring](/platforms/javascript/tracing/span-metrics/examples/#llm-integration-monitoring)
298+
- [Job scheduling and processing](/platforms/javascript/tracing/span-metrics/examples/#job-scheduling-and-processing-pipeline)
299+
300+
These examples demonstrate how to implement comprehensive span metrics across distributed systems, providing end-to-end visibility into application performance and behavior.

‎redirects.js

+4
Original file line numberDiff line numberDiff line change
@@ -984,6 +984,10 @@ const userDocsRedirects = [
984984
source: '/product/explore/feature-flags/:path*',
985985
destination: '/product/issues/issue-details/feature-flags/:path*',
986986
},
987+
{
988+
source: '/product/explore/metrics/:path*',
989+
destination: '/product/explore/tracing/span-metrics/',
990+
},
987991
// Redirects for JavaScript tracing docs
988992
{
989993
source: '/platforms/javascript/tracing/trace-propagation/:path*',

0 commit comments

Comments
 (0)