From e0d24637a2e5d2f06b6d919bee98f091c68d152f Mon Sep 17 00:00:00 2001 From: Cody De Arkland Date: Sun, 30 Mar 2025 23:19:42 -0700 Subject: [PATCH 1/9] removing queues example --- .../common/tracing/span-metrics/examples.mdx | 96 ------------------- 1 file changed, 96 deletions(-) diff --git a/docs/platforms/javascript/common/tracing/span-metrics/examples.mdx b/docs/platforms/javascript/common/tracing/span-metrics/examples.mdx index 0ff0f16004ce2..ddbc956dcaf38 100644 --- a/docs/platforms/javascript/common/tracing/span-metrics/examples.mdx +++ b/docs/platforms/javascript/common/tracing/span-metrics/examples.mdx @@ -330,99 +330,3 @@ The frontend span tracks the user's checkout experience, while the backend span - Monitor inventory availability impact on conversions - Measure end-to-end order completion times - Identify friction points in the user experience - -## Job Scheduling and Processing Pipeline - -**Challenge:** Understanding performance and reliability of distributed job processing systems, from job creation through completion. - -**Solution:** Comprehensive tracking of job lifecycle across scheduling, queueing, and processing stages. - -**Frontend Instrumentation:** -```javascript -// Client-side job submission and monitoring -Sentry.startSpan( - { - name: 'Job Submission Flow', - op: 'job.client', - attributes: { - // Job configuration - 'job.type': 'video_transcoding', - 'job.priority': 'high', - 'job.estimated_duration_ms': 300000, - - // Input metrics - 'input.size_bytes': 52428800, // 50MB - 'input.format': 'mp4', - 'input.segments': 5, - - // Client-side scheduling - 'schedule.requested_start': '2024-03-15T10:00:00Z', - 'schedule.deadline': '2024-03-15T11:00:00Z', - - // Progress monitoring - 'monitor.polling_interval_ms': 5000, - 'monitor.status_updates_received': 12, - 'monitor.last_progress_percent': 45 - } - }, - async () => { - // Job submission and progress tracking implementation - } -); -``` - -**Backend Instrumentation:** -```javascript -// Server-side job processing -Sentry.startSpan( - { - name: 'Job Processing Pipeline', - op: 'job.server', - attributes: { - // Queue metrics - 'queue.name': 'video-processing', - 'queue.provider': 'redis', - 'queue.length_at_enqueue': 23, - 'queue.wait_time_ms': 45000, - - // Worker metrics - 'worker.id': 'worker-pod-123', - 'worker.current_load': 0.75, - 'worker.memory_usage_mb': 1024, - - // Processing stages - 'processing.stages_completed': ['download', 'transcode', 'thumbnail'], - 'processing.stage_durations_ms': { - 'download': 12000, - 'transcode': 180000, - 'thumbnail': 5000 - }, - - // Resource utilization - 'resource.cpu_percent': 85, - 'resource.gpu_utilization': 0.92, - 'resource.memory_peak_mb': 2048, - - // Job outcome - 'outcome.status': 'completed', - 'outcome.retry_count': 0, - 'outcome.output_size_bytes': 31457280 // 30MB - } - }, - async () => { - // Job processing implementation - } - ) -); -``` - -**How the Trace Works Together:** -The frontend span tracks job submission and monitoring, while the backend span captures queue management and processing details. The distributed trace provides visibility into the entire job lifecycle, enabling you to: - -- Monitor end-to-end job processing times and success rates -- Track queue health and worker resource utilization -- Identify bottlenecks in specific processing stages -- Analyze job scheduling efficiency and queue wait times -- Optimize resource allocation based on job characteristics - -For more information about implementing these examples effectively, see our Span Metrics guide which includes detailed best practices and implementation guidelines. From d78510f64b25d0ed18951cfeddd255ec19d0c2f4 Mon Sep 17 00:00:00 2001 From: Cody De Arkland Date: Sun, 30 Mar 2025 23:20:15 -0700 Subject: [PATCH 2/9] Sampling clarity updates --- .../tracing/configure-sampling/index.mdx | 121 +++++------------- 1 file changed, 31 insertions(+), 90 deletions(-) diff --git a/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx b/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx index 80eacce971700..07d5f81a6b9e6 100644 --- a/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx +++ b/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx @@ -11,15 +11,15 @@ Sentry's tracing functionality helps you monitor application performance by capt The JavaScript SDK provides two main options for controlling the sampling rate: 1. Uniform Sample Rate (`tracesSampleRate`) -This option sets a fixed percentage of transactions to be captured: +`tracesSampleRate` is floating point value 0.0 and 1.0, which controls the probability that a transaction will be sampled. -With `tracesSampleRate` set to `0.25`, approximately 25% of transactions will be recorded and sent to Sentry. This provides an even cross-section of transactions regardless of where in your app they occur. +With `tracesSampleRate` set to `0.25`, each transaction in your application is randomly sampled with a probability of `0.25`, so you can expect that one in every four transactions will be sent to Sentry. 2. Sampling Function (`tracesSampler`) -For more granular control, you can use the `tracesSampler` function. This approach allows you to: +For more granular control, you provide a `tracesSampler` function. This approach allows you to: - Apply different sampling rates to different types of transactions - Filter out specific transactions entirely @@ -28,6 +28,29 @@ For more granular control, you can use the `tracesSampler` function. This approa +### The Sampling Context Object + +When the `tracesSampler` function is called, it receives a `samplingContext` object with valuable information to help make sampling decisions: + +```typescript +typescriptCopyinterface SamplingContext { + // Name of the span/transaction + name: string; + + // Initial attributes of the span/transaction + attributes: SpanAttributes | undefined; + + // Whether the parent span was sampled (undefined if no incoming trace) + parentSampled: boolean | undefined; + + // Sample rate from incoming trace (undefined if no incoming trace) + parentSampleRate: number | undefined; + + // Utility function to inherit parent decision or fallback + inheritOrSampleWith: (fallbackRate: number) => number; +} +``` + ### Trace Sampler Examples 1. Prioritizing Critical User Flows @@ -96,98 +119,16 @@ tracesSampler: (samplingContext) => { } ``` -## The Sampling Context Object - -When the `tracesSampler` function is called, it receives a `samplingContext` object with valuable information to help make sampling decisions: - -```typescript -typescriptCopyinterface SamplingContext { - // Name of the span/transaction - name: string; - - // Initial attributes of the span/transaction - attributes: SpanAttributes | undefined; - - // Whether the parent span was sampled (undefined if no incoming trace) - parentSampled: boolean | undefined; - - // Sample rate from incoming trace (undefined if no incoming trace) - parentSampleRate: number | undefined; - - // Utility function to inherit parent decision or fallback - inheritOrSampleWith: (fallbackRate: number) => number; -} -``` - -The sampling context contains: - -- `name`: The name of the transaction/span -- `attributes`: Initial tags and attributes set on the transaction -- `parentSampled`: Whether the parent transaction was sampled (for distributed tracing) -- `parentSampleRate`: The sample rate used in the parent transaction -- `inheritOrSampleWith`: A utility function to handle inheritance logic (recommended) - -## Inheritance in Distributed Tracing - -In distributed systems, trace information is propagated between services. The inheritOrSampleWith function simplifies handling parent sampling decisions: - -```javascript -tracesSampler: (samplingContext) => { - const { name, inheritOrSampleWith } = samplingContext; - - // Apply specific rules first - if (name.includes('critical-path')) { - return 1.0; // Always sample - } - - // Otherwise inherit parent sampling decision or fall back to 0.1 - return inheritOrSampleWith(0.1); -} -``` -This approach ensures consistent sampling decisions across your entire distributed trace. All transactions in a given trace will share the same sampling decision, preventing broken or incomplete traces. - -**Note:** The `inheritOrSampleWith` helper was introduced in version 9 of the SDK. For earlier versions, you can implement similar logic manually using the `parentSampled` property. - ## Sampling Decision Precedence When multiple sampling mechanisms could apply, Sentry follows this order of precedence: -- If `tracesSampler` is defined, its decision is used (can consider parent sampling) -- If no `tracesSampler` but parent sampling is available, parent decision is used +- If a sampling decision is passed to `startSpan`, that decision is used +- If `tracesSampler` is defined, its decision is used. Although the `tracesSampler` can override the parent sampling decision, most users will want to ensure their `tracesSampler` respects the parent sampling decision. +- If no `tracesSampler` is defined, but there is a parent sampling decision from an incoming distributed trace, we use the parent sampling decision - If neither of the above, `tracesSampleRate` is used -- If none of the above are set, no transactions are sampled (0%) - -## How Sampling Propagates in Distributed Traces - -Sentry uses a "head-based" sampling approach: - -- A sampling decision is made in the originating service (the "head") -- This decision is propagated to all downstream services via HTTP headers - -The two key headers are: -- `sentry-trace`: Contains trace ID, span ID, and sampling decision -- `baggage`: Contains additional trace metadata including sample rate - -Sentry automatically attaches these headers to outgoing HTTP requests when using the `browserTracingIntegration`. For other communication channels like WebSockets, you can manually propagate trace information: - -```javascript -// Extract trace data from the current scope -const traceData = Sentry.getTraceData(); -const sentryTraceHeader = traceData["sentry-trace"]; -const sentryBaggageHeader = traceData["baggage"]; - -// Add to your custom request (example using WebSocket) -webSocket.send(JSON.stringify({ - message: "Your data here", - metadata: { - sentryTrace: sentryTraceHeader, - baggage: sentryBaggageHeader - } -})); -``` +- If none of the above are set, no transactions are sampled. This is equivalent to setting `tracesSampleRate` to `0.0`. ## Conclusion -Effective sampling is key to getting the most value from Sentry's performance monitoring while minimizing overhead. The `tracesSampler` function gives you precise control over which transactions to record, allowing you to focus on the most important parts of your application. - -By implementing a thoughtful sampling strategy, you'll get the performance insights you need without overwhelming your systems or your Sentry quota. \ No newline at end of file +Effective sampling is key to getting the most value from Sentry's performance monitoring while minimizing overhead. The `tracesSampler` function gives you precise control over which transactions to record, allowing you to focus on the most important parts of your application. \ No newline at end of file From 24ec67a21f1759450a1e402ac60c28b7893da20c Mon Sep 17 00:00:00 2001 From: Cody De Arkland Date: Sun, 30 Mar 2025 23:20:32 -0700 Subject: [PATCH 3/9] minor corrections to span metric details --- .../javascript/common/tracing/span-metrics/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/javascript/common/tracing/span-metrics/index.mdx b/docs/platforms/javascript/common/tracing/span-metrics/index.mdx index bc2c011b5f609..f877c710eaaef 100644 --- a/docs/platforms/javascript/common/tracing/span-metrics/index.mdx +++ b/docs/platforms/javascript/common/tracing/span-metrics/index.mdx @@ -41,11 +41,11 @@ When adding metrics as span attributes: - Use consistent naming conventions (for example, `category.metric_name`) - Keep attribute names concise but descriptive -- Use appropriate data types (string, number, boolean, or (non-mixed) arrays of these types) +- Use appropriate data types (string, number, boolean, or an array containing only one of these types) ## Creating Dedicated Metric Spans -For more detailed operations, task, 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 appear to create more noise in your trace waterfall. +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. ```javascript Sentry.startSpan( From 71925c0ee04bbe72c54f91262a9f983954069e04 Mon Sep 17 00:00:00 2001 From: Cody De Arkland Date: Sun, 30 Mar 2025 23:20:53 -0700 Subject: [PATCH 4/9] Adding detail for sampling propagation in distributed traces --- .../tracing/distributed-tracing/index.mdx | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/platforms/javascript/common/tracing/distributed-tracing/index.mdx b/docs/platforms/javascript/common/tracing/distributed-tracing/index.mdx index 82094819b28b1..6e5d727febc5f 100644 --- a/docs/platforms/javascript/common/tracing/distributed-tracing/index.mdx +++ b/docs/platforms/javascript/common/tracing/distributed-tracing/index.mdx @@ -60,3 +60,32 @@ Server-side SDKs handle traces automatically on a per-request basis. This means If necessary, you can override the default trace duration by [manually starting a new trace](./custom-instrumentation#starting-a-new-trace). + +## How Sampling Propagates in Distributed Traces + +Sentry uses a "head-based" sampling approach: + +- A sampling decision is made in the originating service (the "head") +- This decision is propagated to all downstream services + +The two key headers are: +- `sentry-trace`: Contains trace ID, span ID, and sampling decision +- `baggage`: Contains additional trace metadata including sample rate + +Sentry automatically attaches these headers to outgoing HTTP requests when using the `browserTracingIntegration`. For other communication channels like WebSockets, you can manually propagate trace information: + +```javascript +// Extract trace data from the current scope +const traceData = Sentry.getTraceData(); +const sentryTraceHeader = traceData["sentry-trace"]; +const sentryBaggageHeader = traceData["baggage"]; + +// Add to your custom request (example using WebSocket) +webSocket.send(JSON.stringify({ + message: "Your data here", + metadata: { + sentryTrace: sentryTraceHeader, + baggage: sentryBaggageHeader + } +})); +``` From a953fcbed87b7c1e140acdc530639625d6b55c77 Mon Sep 17 00:00:00 2001 From: Cody De Arkland Date: Sun, 30 Mar 2025 23:21:19 -0700 Subject: [PATCH 5/9] Updating descripotion to replace performance with trace --- .../javascript/common/tracing/instrumentation/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx index a519703b57b4b..f67319f7eae42 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx @@ -1,6 +1,6 @@ --- title: Instrumentation -description: "Learn how to configure spans to capture performance data on any action in your app." +description: "Learn how to configure spans to capture trace data on any action in your app." sidebar_order: 40 --- From ea2c55221fe207b53db3b91d5ed7c745ee5a70a3 Mon Sep 17 00:00:00 2001 From: Cody De Arkland Date: Tue, 1 Apr 2025 07:27:47 -0700 Subject: [PATCH 6/9] Update docs/platforms/javascript/common/tracing/configure-sampling/index.mdx Co-authored-by: Francesco Gringl-Novy --- .../javascript/common/tracing/configure-sampling/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx b/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx index 07d5f81a6b9e6..d804675d0bfe1 100644 --- a/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx +++ b/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx @@ -33,7 +33,7 @@ For more granular control, you provide a `tracesSampler` function. This approach When the `tracesSampler` function is called, it receives a `samplingContext` object with valuable information to help make sampling decisions: ```typescript -typescriptCopyinterface SamplingContext { +interface SamplingContext { // Name of the span/transaction name: string; From d12a72fc5634f8fc050b44f65eb8aca46b3ab797 Mon Sep 17 00:00:00 2001 From: Cody De Arkland Date: Tue, 1 Apr 2025 07:27:58 -0700 Subject: [PATCH 7/9] Update docs/platforms/javascript/common/tracing/configure-sampling/index.mdx Co-authored-by: Francesco Gringl-Novy --- .../javascript/common/tracing/configure-sampling/index.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx b/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx index d804675d0bfe1..9eb2b81ff2227 100644 --- a/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx +++ b/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx @@ -123,7 +123,6 @@ tracesSampler: (samplingContext) => { When multiple sampling mechanisms could apply, Sentry follows this order of precedence: -- If a sampling decision is passed to `startSpan`, that decision is used - If `tracesSampler` is defined, its decision is used. Although the `tracesSampler` can override the parent sampling decision, most users will want to ensure their `tracesSampler` respects the parent sampling decision. - If no `tracesSampler` is defined, but there is a parent sampling decision from an incoming distributed trace, we use the parent sampling decision - If neither of the above, `tracesSampleRate` is used From b5789094ff7ec547191c952e6ee9c5b84cd200a8 Mon Sep 17 00:00:00 2001 From: Cody De Arkland Date: Tue, 1 Apr 2025 07:49:17 -0700 Subject: [PATCH 8/9] Correcting span sampling language --- .../javascript/common/tracing/configure-sampling/index.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx b/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx index 9eb2b81ff2227..49c5aecf50831 100644 --- a/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx +++ b/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx @@ -126,7 +126,8 @@ When multiple sampling mechanisms could apply, Sentry follows this order of prec - If `tracesSampler` is defined, its decision is used. Although the `tracesSampler` can override the parent sampling decision, most users will want to ensure their `tracesSampler` respects the parent sampling decision. - If no `tracesSampler` is defined, but there is a parent sampling decision from an incoming distributed trace, we use the parent sampling decision - If neither of the above, `tracesSampleRate` is used -- If none of the above are set, no transactions are sampled. This is equivalent to setting `tracesSampleRate` to `0.0`. +- If `tracesSampleRate` is set to 0, no spans will be sampled, and no downstream spans will be sampled either since they inherit the parent sampling decision +- If none of the above are set, no transactions are sampled and tracing will be disabled ## Conclusion From 93442888e0e6d27c052f09133c343554f0bbec53 Mon Sep 17 00:00:00 2001 From: Cody De Arkland Date: Tue, 1 Apr 2025 08:35:41 -0700 Subject: [PATCH 9/9] Update docs/platforms/javascript/common/tracing/configure-sampling/index.mdx Co-authored-by: Francesco Gringl-Novy --- .../javascript/common/tracing/configure-sampling/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx b/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx index 49c5aecf50831..5d4cf3c95d1e7 100644 --- a/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx +++ b/docs/platforms/javascript/common/tracing/configure-sampling/index.mdx @@ -15,7 +15,7 @@ The JavaScript SDK provides two main options for controlling the sampling rate: -With `tracesSampleRate` set to `0.25`, each transaction in your application is randomly sampled with a probability of `0.25`, so you can expect that one in every four transactions will be sent to Sentry. +With `tracesSampleRate` set to `0.25`, each transaction in your application is randomly sampled with a probability of 25%, so you can expect that one in every four transactions will be sent to Sentry. 2. Sampling Function (`tracesSampler`)