Skip to content

Commit a5cda2d

Browse files
codydecodyde
committed
Adding additional examples and clarity
1 parent d1f10a1 commit a5cda2d

File tree

3 files changed

+213
-134
lines changed

3 files changed

+213
-134
lines changed

‎docs/platforms/javascript/common/tracing/span-metrics/examples.mdx

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
title: Examples
3+
description: "Examples of using span metrics to debug performance issues and monitor application behavior."
4+
sidebar_order: 10
5+
---
6+
7+
<Alert>
8+
9+
These examples assume you have already <PlatformLink to="/tracing/">set up tracing</PlatformLink> in your application.
10+
11+
</Alert>
12+
13+
This guide provides practical examples of using span metrics to solve common monitoring and debugging challenges. Each example includes the context, implementation, and specific benefits of tracking these metrics.
14+
15+
## File Upload and Processing Pipeline
16+
17+
**Challenge:** Understanding bottlenecks and failures in multi-step file processing operations.
18+
19+
**Solution:** Track the entire file processing pipeline with detailed metrics at each stage.
20+
21+
```javascript
22+
Sentry.startSpan(
23+
{
24+
name: 'File Upload and Processing',
25+
op: 'file.process',
26+
attributes: {
27+
// File metadata for correlation and context
28+
'file.size_bytes': 15728640, // 15MB
29+
'file.type': 'image/jpeg',
30+
'file.name': 'user-profile.jpg',
31+
32+
// Track each processing step for pipeline visibility
33+
'processing.steps_completed': ['resize', 'compress', 'metadata'],
34+
'processing.output_size_bytes': 524288, // 512KB
35+
'processing.compression_ratio': 0.033,
36+
37+
// Upload performance metrics
38+
'upload.chunk_size': 1048576, // 1MB chunks
39+
'upload.chunks_completed': 15,
40+
'upload.storage_provider': 's3',
41+
'upload.cdn_propagation_ms': 1500,
42+
43+
// Error tracking
44+
'error.count': 0
45+
}
46+
},
47+
async () => {
48+
// Your file processing implementation
49+
}
50+
);
51+
```
52+
53+
**Benefits:**
54+
- Identify which processing steps are taking longest
55+
- Track upload performance across different file sizes
56+
- Monitor CDN propagation delays
57+
- Calculate processing efficiency through compression ratios
58+
- Detect partial failures in the pipeline
59+
60+
## LLM Integration Monitoring
61+
62+
**Challenge:** Managing costs and performance of LLM API integrations while ensuring optimal user experience.
63+
64+
**Solution:** Comprehensive tracking of token usage, timing, and configuration metrics.
65+
66+
```javascript
67+
Sentry.startSpan(
68+
{
69+
name: 'LLM Generation',
70+
op: 'ai.completion',
71+
attributes: {
72+
// Model configuration for context
73+
'llm.model': 'gpt-4',
74+
'llm.temperature': 0.7,
75+
'llm.max_tokens': 2000,
76+
'llm.stream_mode': true,
77+
78+
// Token usage for cost monitoring
79+
'llm.prompt_tokens': 425,
80+
'llm.completion_tokens': 632,
81+
'llm.total_tokens': 1057,
82+
83+
// Performance metrics
84+
'llm.time_to_first_token_ms': 245,
85+
'llm.total_duration_ms': 3250,
86+
87+
// Request outcome
88+
'llm.request_status': 'success'
89+
}
90+
},
91+
async () => {
92+
// Your LLM API implementation
93+
}
94+
);
95+
```
96+
97+
**Benefits:**
98+
- Monitor API costs through token usage
99+
- Track user experience metrics like time to first token
100+
- Identify optimal model configurations
101+
- Debug streaming vs non-streaming performance
102+
- Correlate model parameters with response quality
103+
104+
## E-Commerce Transaction Flow
105+
106+
**Challenge:** Understanding the complete purchase flow and identifying revenue-impacting issues.
107+
108+
**Solution:** Track the entire checkout process with business and technical metrics.
109+
110+
```javascript
111+
Sentry.startSpan(
112+
{
113+
name: 'Purchase Transaction',
114+
op: 'commerce.checkout',
115+
attributes: {
116+
// Cart analytics
117+
'cart.item_count': 3,
118+
'cart.total_amount': 159.99,
119+
'cart.currency': 'USD',
120+
'cart.items': ['SKU123', 'SKU456', 'SKU789'],
121+
122+
// Payment processing
123+
'payment.provider': 'stripe',
124+
'payment.method': 'credit_card',
125+
'payment.status': 'success',
126+
127+
// Transaction metadata
128+
'transaction.id': 'ord_123456789',
129+
'customer.type': 'returning',
130+
131+
// Fulfillment details
132+
'shipping.method': 'express',
133+
134+
// Promotion tracking
135+
'promotion.code_applied': 'SUMMER23',
136+
'promotion.discount_amount': 20.00
137+
}
138+
},
139+
async () => {
140+
// Your checkout process implementation
141+
}
142+
);
143+
```
144+
145+
**Benefits:**
146+
- Track conversion rates by customer type
147+
- Monitor payment provider performance
148+
- Analyze promotion effectiveness
149+
- Identify abandoned cart patterns
150+
- Debug payment processing issues
151+
152+
## API Integration Health
153+
154+
**Challenge:** Maintaining reliability and performance of critical API integrations.
155+
156+
**Solution:** Detailed tracking of API request patterns and performance.
157+
158+
```javascript
159+
Sentry.startSpan(
160+
{
161+
name: 'External API Call',
162+
op: 'http.client',
163+
attributes: {
164+
// Request context
165+
'http.endpoint': '/api/users',
166+
'http.method': 'POST',
167+
168+
// Performance metrics
169+
'http.response_time_ms': 200,
170+
'http.response_size_bytes': 2048,
171+
172+
// Reliability metrics
173+
'http.retry_count': 0,
174+
'http.cache_status': 'miss',
175+
176+
// Request outcome
177+
'http.status_code': 200,
178+
'http.error_type': null
179+
}
180+
},
181+
async () => {
182+
// Your API call implementation
183+
}
184+
);
185+
```
186+
187+
**Benefits:**
188+
- Monitor API endpoint performance
189+
- Track retry patterns
190+
- Optimize cache usage
191+
- Identify slow or failing endpoints
192+
- Debug integration issues
193+
194+
For more information about implementing these examples effectively, see our <PlatformLink to="/tracing/span-metrics/">Span Metrics guide</PlatformLink> which includes detailed best practices and implementation guidelines.

‎docs/platforms/javascript/common/tracing/span-metrics/index.mdx

Lines changed: 17 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -66,47 +66,7 @@ Sentry.startSpan(
6666
);
6767
```
6868

69-
### Common Metric Span Patterns
70-
71-
Here are some common patterns for creating metric-focused spans:
72-
73-
#### Performance Monitoring
74-
```javascript
75-
Sentry.startSpan(
76-
{
77-
name: 'Resource Usage Metrics',
78-
op: 'system.metrics',
79-
attributes: {
80-
'cpu.usage_percent': 75.5,
81-
'memory.used_mb': 1024,
82-
'memory.free_mb': 512,
83-
'disk.iops': 150
84-
}
85-
},
86-
async () => {
87-
// System operation being monitored
88-
}
89-
);
90-
```
91-
92-
#### Application Metrics
93-
```javascript
94-
Sentry.startSpan(
95-
{
96-
name: 'User Session Metrics',
97-
op: 'app.metrics',
98-
attributes: {
99-
'session.duration_sec': 300,
100-
'session.interactions': 25,
101-
'session.errors': 0,
102-
'session.latency_ms': 150
103-
}
104-
},
105-
() => {
106-
// Session-related code
107-
}
108-
);
109-
```
69+
For detailed examples of how to implement span metrics in common scenarios, see our <PlatformLink to="/tracing/span-metrics/examples/">Span Metrics Examples</PlatformLink> guide.
11070

11171
## Adding Metrics to All Spans
11272

@@ -162,98 +122,23 @@ Sentry.init({
162122
- Include correlation IDs for related operations
163123
- Add context that helps with troubleshooting
164124

165-
## Common Use Cases
125+
## Best Practices for Implementation
166126

167-
### File Processing Operations
168-
```javascript
169-
Sentry.startSpan(
170-
{
171-
name: 'File Upload and Processing',
172-
op: 'file.process',
173-
attributes: {
174-
'file.type': 'image/jpeg',
175-
'file.name': 'user-profile.jpg',
176-
'processing.steps_completed': ['resize', 'compress', 'metadata'],
177-
'processing.compression_ratio': 0.033,
178-
'upload.chunks_completed': 15,
179-
'upload.storage_provider': 's3',
180-
'error.count': 0
181-
}
182-
},
183-
async () => {
184-
// Existing file processing and upload functionality
185-
}
186-
);
187-
```
127+
When implementing span metrics in your application:
188128

189-
### API Request Tracking
190-
```javascript
191-
Sentry.startSpan(
192-
{
193-
name: 'External API Call',
194-
op: 'http.client',
195-
attributes: {
196-
'http.endpoint': '/api/users',
197-
'http.response_size_bytes': 2048,
198-
'http.retry_count': 0,
199-
'http.cache_status': 'miss',
200-
'http.response_time_ms': 200
201-
}
202-
},
203-
async () => {
204-
// Existing API call functionality
205-
}
206-
);
207-
```
129+
1. **Start Small and Iterate**
130+
- Begin with basic metrics that directly relate to your debugging or performance monitoring needs
131+
- Add more detailed tracking as specific debugging needs emerge
132+
- Remove metrics that aren't providing actionable insights
208133

209-
### LLM API Integration
210-
```javascript
211-
Sentry.startSpan(
212-
{
213-
name: 'LLM Generation',
214-
op: 'ai.completion',
215-
attributes: {
216-
'llm.model': 'gpt-4',
217-
'llm.prompt_tokens': 425,
218-
'llm.completion_tokens': 632,
219-
'llm.total_tokens': 1057,
220-
'llm.time_to_first_token_ms': 245,
221-
'llm.total_duration_ms': 3250,
222-
'llm.temperature': 0.7,
223-
'llm.max_tokens': 2000,
224-
'llm.stream_mode': true,
225-
'llm.request_status': 'success'
226-
}
227-
},
228-
async () => {
229-
// LLM API call execution
230-
}
231-
);
232-
```
134+
2. **Maintain Consistency**
135+
- Use consistent naming patterns across your application
136+
- Document metric meanings and units in your codebase
137+
- Share common metrics across similar operations
233138

234-
### E-commerce Transaction
235-
```javascript
236-
Sentry.startSpan(
237-
{
238-
name: 'Purchase Transaction',
239-
op: 'commerce.checkout',
240-
attributes: {
241-
'cart.item_count': 3,
242-
'cart.total_amount': 159.99,
243-
'cart.currency': 'USD',
244-
'cart.items': ['SKU123', 'SKU456', 'SKU789'],
245-
'payment.provider': 'stripe',
246-
'payment.method': 'credit_card',
247-
'payment.status': 'success',
248-
'transaction.id': 'ord_123456789',
249-
'customer.type': 'returning',
250-
'shipping.method': 'express',
251-
'promotion.code_applied': 'SUMMER23',
252-
'promotion.discount_amount': 20.00
253-
}
254-
},
255-
async () => {
256-
// Existing checkout process functionality
257-
}
258-
);
259-
```
139+
3. **Focus on Actionability**
140+
- Track metrics that help diagnose specific issues
141+
- Consider what alerts or dashboard visualizations you'll want to create
142+
- Ensure metrics can drive issue resolution or decision-making
143+
144+
For detailed examples of how to implement span metrics in common scenarios, see our <PlatformLink to="/tracing/span-metrics/examples/">Span Metrics Examples</PlatformLink> guide.

‎redirects.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -969,8 +969,8 @@ const userDocsRedirects = [
969969
destination: '/platforms/javascript/tracing/distributed-tracing/',
970970
},
971971
{
972-
source: '/platforms/javascript/tracing/instrumentation/custom-instrumentation/',
973-
destination: '/platforms/javascript/tracing/span-metrics/custom-instrumentation/',
972+
source: '/platforms/javascript/tracing/instrumentation/custom-instrumentation/:path*',
973+
destination: '/platforms/javascript/tracing/span-metrics/custom-instrumentation/:path*',
974974
},
975975
{
976976
source: '/platforms/javascript/tracing/instrumentation/performance-metrics/',

0 commit comments

Comments
 (0)