From 23694b8a779e437db923eeaa0f7df1952519cfc0 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Fri, 4 Apr 2025 11:12:51 +0200 Subject: [PATCH 1/2] feat(js): Update JS tracing instrumentation docs --- .../javascript/common/tracing/index.mdx | 14 ++- .../common/tracing/instrumentation/index.mdx | 101 +++--------------- 2 files changed, 26 insertions(+), 89 deletions(-) diff --git a/docs/platforms/javascript/common/tracing/index.mdx b/docs/platforms/javascript/common/tracing/index.mdx index e00ca9d24d31f6..7bfa6560c3eb66 100644 --- a/docs/platforms/javascript/common/tracing/index.mdx +++ b/docs/platforms/javascript/common/tracing/index.mdx @@ -30,8 +30,8 @@ With [tracing](/product/insights/overview/), Sentry automatically tracks your so ## Configure - Enable tracing by configuring the sampling rate for transactions. Set - the sample rate for your transactions by either: + Enable tracing by configuring the sampling rate for transactions. Set the + sample rate for your transactions by either: @@ -66,14 +66,20 @@ If you leave your sample rate at `1.0`, a transaction will be sent every time a ## Automatic Instrumentation - See Automatic Instrumentation to learn about all the things that the SDK automatically instruments for you. +See Automatic Instrumentation to learn about all the things that the SDK automatically instruments for you. + ## Custom Instrumentation You can also manually start spans to instrument specific parts of your code. This is useful when you want to measure the performance of a specific operation or function. -See Sending Span Metrics to learn how to manually start spans. +- Tracing APIs: + Find information about APIs for custom tracing instrumentation +- Instrumentation: + Find information about manual instrumentation with the Sentry SDK +- Sending Span Metrics: + Learn how to capture metrics on your spans ## Next Steps diff --git a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx index f67319f7eae424..76ec79ed07eaa9 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx @@ -12,6 +12,8 @@ To capture transactions and spans customized to your organization's needs, you m To add custom performance data to your application, you need to add custom instrumentation in the form of spans. Spans are a way to measure the time it takes for a specific action to occur. For example, you can create a span to measure the time it takes for a function to execute. +You can find a list of all tracing APIs in the Tracing API section. + To get started, import the SDK. @@ -106,7 +108,7 @@ To add spans that aren't active, you can create independent spans. This is usefu By default, any span that is started will be the child of the currently active span. If you want to have a different behavior, you can force spans to be the children of a specific span with the `parentSpan` option: -```js +```javascript const parentSpan = Sentry.startInactiveSpan({ name: "Parent Span" }); const childSpan = Sentry.startInactiveSpan({ name: "Child Span", parentSpan }); @@ -119,74 +121,12 @@ This option is also available for `startSpan` and `startSpanManual`. ## Utilities To Work With Spans We expose some helpful utilities that can help you with custom instrumentation. - -### `getActiveSpan` - -Returns the currently active span. - -```javascript -const activeSpan = Sentry.getActiveSpan(); -``` - -### `getRootSpan` - -Returns the root span of a given span. If the span is already the root span, it will return the span itself. - -```javascript -const activeSpan = Sentry.getActiveSpan(); -const rootSpan = activeSpan ? Sentry.getRootSpan(activeSpan) : undefined; -``` - -### `withActiveSpan` - -This method allows you to make a span active for the duration of a callback. You can use this in combination with `startInactiveSpan` to manually associate child spans with the correct parent span: - -```javascript -const span = Sentry.startInactiveSpan({ name: "Parent Span" }); - -Sentry.withActiveSpan(span, () => { - // `span` is now active, any other spans will be children of it - Sentry.startSpan({ name: "Child Span" }, () => { - // Do something - }); -}); -``` - -You can also pass `null` to `withActiveSpan` to ensure a span will not have any parent: - -```javascript -Sentry.withActiveSpan(null, () => { - // This will not have a parent span, no matter what - Sentry.startSpan({ name: "Parent Span" }, () => { - // Do something - }); -}); -``` - -Alternatively you can also use the `parentSpan` option to achieve the same: - -```javascript -const span = Sentry.startInactiveSpan({ name: "Parent Span" }); -const childSpan = Sentry.startInactiveSpan({ - name: "Child Span", - parentSpan: span, -}); -``` - -### `suppressTracing` - -Suppresses the creation of sampled spans for the duration of the callback. This is useful when you want to prevent certain spans from being captured. For example, if you do not want to create spans for a given fetch request, you can do: - -```javascript -Sentry.suppressTracing(() => { - fetch("https://example.com"); -}); -``` +See Tracing Utility APIs for more information. -### Distributed Tracing +## Distributed Tracing -See Distributed Tracing for details on how to manually set up distributed tracing. +See Custom Trace Propagation for details on how to manually set up distributed tracing. @@ -227,32 +167,23 @@ if (span) { ### Adding attributes to all spans -To add an attribute to all spans, use the `beforeSendTransaction` callback: +To add an attribute to all spans, use the `beforeSendSpan` callback: ```javascript Sentry.init({ // dsn, ... - beforeSendTransaction(event) { - - // set the attribute on the root span - event.contexts.trace.data = { - ...event.contexts.trace.data, - myAttribute: "myValue", - } - - // and on all child spans - event.spans.forEach(span => { - span.data = { - ...span.data, - myAttribute: "myValue", - } - }); - } + beforeSendSpan(span) { + span.data = { + ...span.data, + "app.version": "1.2.3", + "environment.region": "us-west-2", + }; + + return span; + }, }); ``` - - ### Adding Span Operations ("op") Spans can have an operation associated with them, which help Sentry identify additional context about the span. For example, database related spans have the `db` span operation associated with them. The Sentry product offers additional controls, visualizations, and filters for spans with known operations. From 9929e8d49f0a751b60f2ac075f20f84a69cc177e Mon Sep 17 00:00:00 2001 From: Francesco Gringl-Novy Date: Fri, 4 Apr 2025 11:26:06 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Lukas Stracke --- .../javascript/common/tracing/instrumentation/index.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx index 76ec79ed07eaa9..3beec9c98ecb99 100644 --- a/docs/platforms/javascript/common/tracing/instrumentation/index.mdx +++ b/docs/platforms/javascript/common/tracing/instrumentation/index.mdx @@ -175,7 +175,6 @@ Sentry.init({ beforeSendSpan(span) { span.data = { ...span.data, - "app.version": "1.2.3", "environment.region": "us-west-2", };