docs(js): Update span metrics instrumentation examples #14610

codyde · 2025-08-11T10:14:40Z

Overview

Updates the span metrics instrumentation examples page with comprehensive, real-world use cases demonstrating how to instrument both frontend and backend code for distributed tracing.

What's New

Four Complete Examples with Sample Repositories

E-Commerce Checkout Flow (Crash Commerce)
- Frontend: React checkout button instrumentation with ui.action spans
- Backend: Order processing and payment provider spans
- Demonstrates: Cart metrics, payment provider tracking, end-to-end checkout flow
- Metrics to monitor: p95 duration by cart size, error rates by payment provider
Media Upload with Background Processing (SnapTrace)
- Frontend: Upload experience tracking with file.upload spans
- Backend: Validation spans and async media processing
- Demonstrates: User-perceived upload time, async background jobs, trace continuity
- Metrics to monitor: p95 by file size, processing success rates, storage optimization
Search Autocomplete (NullFlix)
- Frontend: Debounced search with abort handling
- Backend: Search performance with query categorization
- Demonstrates: Cancellable requests, slow query detection, performance patterns
- Metrics to monitor: p95 by query length, cancellation rates, empty result rates
Manual LLM Instrumentation (Customer Service Bot)
- Frontend: AI chat interface with agent spans
- Backend: Custom LLM integration with tool execution
- Demonstrates: AI agent conventions, token tracking, tool call monitoring
- Metrics to monitor: Token usage, tool performance, agent effectiveness

Key Improvements

✅ Practical, production-ready examples - Each example shows real-world monitoring scenarios
✅ End-to-end tracing - Demonstrates how frontend and backend spans work together in a distributed trace
✅ Best practices - Shows proper span naming, attribute usage, and error handling
✅ Actionable metrics - Each example includes specific span metrics queries to monitor
✅ Sample repos - Links to working example repositories with Arcade demos
✅ Implementation guidance - Clear notes on where to place instrumentation code

Content Structure

Each example includes:

Challenge statement - The monitoring problem to solve
Solution approach - How to instrument with spans and attributes
Code examples - Frontend and backend instrumentation
Implementation notes - Where to add code in your app
Trace flow explanation - How the spans connect in a distributed trace
Monitoring guidance - Specific span metrics queries to use

* 'master' of https://github.com/getsentry/sentry-docs: docs(dev-infra): Update development environment docs (#14585) add Sevvy integration docs (#14601) feat(dart/flutter): improve distinction between Logging integration and Structured Logs (#14527) correcting region storage for symbol and source map metadata (#14600)

…, Media Upload, Search Autocomplete) using existing Challenge/Solution/Frontend/Backend/How-it-works structure. Emphasizes where to instrument in React vs backend and low-cardinality attributes for span metrics.

…e auto-instrumentation; keep attributes minimal and business-focused for easier customization.

vercel · 2025-08-11T10:14:45Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
sentry-docs	Ready	Preview	Comment	Oct 27, 2025 9:21am

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
develop-docs	Ignored	Preview		Oct 27, 2025 9:21am

codecov · 2025-08-11T10:18:55Z

Bundle Report

Changes will decrease total bundle size by 32.95kB (-0.14%) ⬇️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sentry-docs-client-array-push	10.14MB	-20.4kB (-0.2%) ⬇️
sentry-docs-server-cjs	12.97MB	-12.55kB (-0.1%) ⬇️

Affected Assets, Files, and Routes:

view changes for bundle: sentry-docs-server-cjs

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`1729.js`	-3 bytes	1.78MB	-0.0%
`../instrumentation.js`	-3 bytes	1.1MB	-0.0%
`9523.js`	-3 bytes	1.08MB	-0.0%
`../app/[[...path]]/page.js`	-161 bytes	615.16kB	-0.03%
`9883.js` (New)	218.27kB	218.27kB	100.0% 🚀
`4873.js`	-24 bytes	91.43kB	-0.03%
`../app/platform-redirect/page.js`	-159 bytes	32.06kB	-0.49%
~~`8413.js`~~ (Deleted)	-218.92kB	0 bytes	-100.0% 🗑️
~~*`../../static/media/langgraph..svg`*~~ (Deleted)*	-5.77kB	0 bytes	-100.0% 🗑️
~~*`../../static/media/langgraph..svg`*~~ (Deleted)*	-5.78kB	0 bytes	-100.0% 🗑️

Files in 4873.js:

./src/components/platformIcon.tsx → Total Size: 37.2kB
./src/components/platformIcon.tsx → Total Size: 37.2kB

App Routes Affected:

App Route	Size Change	Total Size	Change (%)
/platform-redirect	-159 bytes	2.78MB	-0.01%
/[[...path]]	-161 bytes	3.36MB	-0.0%

view changes for bundle: sentry-docs-client-array-push

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`static/chunks/pages/_app-*.js`	-3 bytes	882.71kB	-0.0%
`static/chunks/8321-*.js`	-3 bytes	425.87kB	-0.0%
`server/app/api/ip-*.js`	-2.11kB	265.08kB	-0.79%
`server/app/_not-*.js`	-2.11kB	265.07kB	-0.79%
`server/app/[[...path]]/page_client-*.js`	-2.11kB	265.03kB	-0.79%
`server/app/platform-*.js`	-2.01kB	249.71kB	-0.8%
*`static/chunks/124-.js`** (New)	145.04kB	145.04kB	100.0% 🚀
`static/chunks/app/[[...path]]/page-*.js`	-81 bytes	94.48kB	-0.09%
`static/chunks/4145-*.js`	-12 bytes	50.75kB	-0.02%
`static/chunks/app/platform-*.js`	-81 bytes	13.3kB	-0.61%
`server/middleware-*.js`	-6.46kB	1.0kB	-86.59%
`server/middleware-*.js`	6.46kB	7.46kB	645.5% ⚠️
`app-*.json`	-2 bytes	4.59kB	-0.04%
`static/NTSIMsjV5gVmEuRdknkKH/_buildManifest.js` (New)	684 bytes	684 bytes	100.0% 🚀
`static/NTSIMsjV5gVmEuRdknkKH/_ssgManifest.js` (New)	77 bytes	77 bytes	100.0% 🚀
~~*`static/chunks/2229-.js`*~~ (Deleted)*	-145.36kB	0 bytes	-100.0% 🗑️
~~*`/static/media/langgraph..svg`*~~ (Deleted)*	-5.78kB	0 bytes	-100.0% 🗑️
~~*`/static/media/langgraph..svg`*~~ (Deleted)*	-5.77kB	0 bytes	-100.0% 🗑️
~~*`static/c-.js`*~~ (Deleted)*	-77 bytes	0 bytes	-100.0% 🗑️
~~*`static/c-.js`*~~ (Deleted)*	-684 bytes	0 bytes	-100.0% 🗑️

Files in static/chunks/4145-*.js:

./src/components/platformIcon.tsx → Total Size: 37.28kB

…s-examples * origin/master: (478 commits) docs(godot): Structured logging (#15287) fix(batch-processor): Don't enforce starting timer (#15309) feat(node): Add new options to nativeNodeFetchIntegration (#15282) Updated dotnet options to include all defaults (#15218) ref: add docs that logs channel is optional (#15172) docs(svelteKit): Update build-time options for source maps (#15283) fix(python): Fix paragraph order in Strawberry docs (#15301) Added docs explaining how to disable Sentry Native in the .NET SDK (#15293) Updated Unity options with missing defaults (#15219) docs(otlp): Update docs for client SDK w3c traceparent support (#15294) Adding defaults for Godot options (#15216) feat(crons): Document broken monitors feature (#15280) fix: Remove OTLP logs from EA list (#15288) Bump API schema to 06047b60 (#15276) ref(nextjs): Move manual instrumentation examples for ai into Edge section (#15284) docs(otlp): change status to open beta (#15285) Hono runtime and middleware doc updates (#14853) feat(logs): Clarify API for Hub/Scope and Client (#15281) docs(astro/nuxt): Remove `sourceMapsUploadOptions` option nesting (#14905) docs(profiling): Add docs for Profiling API (#15258) ...

- SnapTrace and NullFlix repositories were returning 404 errors - Updated to show 'Coming soon - sample repository in development' - Crash Commerce repository link remains working and active

- Both repositories are accessible and working - Reverting previous placeholder text changes

- LangGraph SVG icon was missing from platformicons package - Using LangChain icon as fallback since they're related technologies - Fixes compilation error and allows dev server to start successfully

- SnapTrace: github.com/getsentry/snaptrace-tracing-example - NullFlix: github.com/getsentry/nullflix-tracing-example - Both repositories are now accessible and contain comprehensive tracing examples

- Comprehensive example showing custom LLM integration with tool calls - Follows Sentry AI agent span conventions from developer docs - Demonstrates gen_ai.invoke_agent, gen_ai.chat, and gen_ai.execute_tool patterns - Includes frontend React component and backend Express API - Shows proper attribute usage for monitoring costs, performance, and business metrics - Matches existing example structure with Challenge/Solution/Frontend/Backend format

Critical fixes to align with Sentry AI agent span conventions: - Add missing SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN with 'manual.ai.custom-llm' value - Add gen_ai.response.model attributes to all agent and LLM spans - Import SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN from @sentry/core - Ensure all spans (invoke_agent, chat, execute_tool) have required attributes - Follow exact patterns from JavaScript SDK AI integrations - Matches developer docs AI agent conventions at develop.sentry.dev

- Removed 6 extra tools to focus on core instrumentation patterns - Kept only search_knowledge_base tool as representative example - Simplified monitoring metrics section to match other examples - Reduced verbosity while maintaining all essential tracing patterns - Test app remains comprehensive with all tools intact

…data fidelity - Removed verbose LLM API call implementation details - Simplified tool execution to essential patterns only - Removed complex final synthesis step - Kept all required AI agent span attributes and conventions - Reduced from ~100 lines to ~40 lines while maintaining all tracing patterns - Helper functions now show clean interface without implementation details

codyde · 2025-10-27T09:14:31Z

Closing this PR as it got polluted with unrelated changes. Clean version of just the span metrics examples changes created in #15320

codyde added 7 commits August 8, 2025 10:57

correcting region storage for symbol and source map metadata

dd149b7

Simplify examples to single-span patterns (no nested spans). Emphasiz…

7b1ffa0

…e auto-instrumentation; keep attributes minimal and business-focused for easier customization.

updating autcomplete search example

1e55f1d

Adding media upload example

0f34886

Adding callout on sample code

5d62466

vercel bot deployed to Preview – sentry-docs August 11, 2025 10:31 View deployment

Updating tracing examples with practical scenarios

ed7a4d5

vercel bot deployed to Preview – sentry-docs August 12, 2025 23:04 View deployment

codyde added 4 commits October 26, 2025 23:33

fix: replace broken repository links with placeholder text

2032714

- SnapTrace and NullFlix repositories were returning 404 errors - Updated to show 'Coming soon - sample repository in development' - Crash Commerce repository link remains working and active

fix: restore working repository links for SnapTrace and NullFlix

3e2f2e6

- Both repositories are accessible and working - Reverting previous placeholder text changes

fix: resolve missing langgraph.svg icon after master merge

2b21bf6

- LangGraph SVG icon was missing from platformicons package - Using LangChain icon as fallback since they're related technologies - Fixes compilation error and allows dev server to start successfully

vercel bot deployed to Preview – develop-docs October 27, 2025 06:54 View deployment

codyde added 3 commits October 27, 2025 00:00

fix: update repository links to correct tracing example URLs

13f9cd8

- SnapTrace: github.com/getsentry/snaptrace-tracing-example - NullFlix: github.com/getsentry/nullflix-tracing-example - Both repositories are now accessible and contain comprehensive tracing examples

vercel bot deployed to Preview – sentry-docs October 27, 2025 08:12 View deployment

codyde added 2 commits October 27, 2025 01:18

codyde marked this pull request as ready for review October 27, 2025 08:53

codyde changed the title ~~Updating Tracing and Span Examples~~ docs(js): Update span metrics instrumentation examples Oct 27, 2025

codyde closed this Oct 27, 2025

vercel bot deployed to Preview – sentry-docs October 27, 2025 09:21 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Uh oh!

docs(js): Update span metrics instrumentation examples #14610

docs(js): Update span metrics instrumentation examples #14610

Uh oh!

codyde commented Aug 11, 2025 •

edited

Loading

Uh oh!

vercel bot commented Aug 11, 2025 •

edited

Loading

Uh oh!

codecov bot commented Aug 11, 2025 •

edited

Loading

Assets Changed:

App Routes Affected:

Assets Changed:

Uh oh!

codyde commented Oct 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

docs(js): Update span metrics instrumentation examples #14610

docs(js): Update span metrics instrumentation examples #14610

Uh oh!

Conversation

codyde commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

What's New

Four Complete Examples with Sample Repositories

Key Improvements

Content Structure

Uh oh!

vercel bot commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Report

Affected Assets, Files, and Routes:

Assets Changed:

App Routes Affected:

Assets Changed:

Uh oh!

codyde commented Oct 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codyde commented Aug 11, 2025 •

edited

Loading

vercel bot commented Aug 11, 2025 •

edited

Loading

codecov bot commented Aug 11, 2025 •

edited

Loading