From 8805616010786d0652ee4bed1040f5de870a8847 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Fri, 10 Nov 2023 10:07:29 +0100 Subject: [PATCH 1/7] feat: Add custom distributed tracing docs for JS/Node --- .../custom-instrumentation/javascript.mdx | 76 +++++++++------ .../custom-instrumentation/node.mdx | 97 +++++++++++++++++++ .../how-to-use/javascript.mdx | 4 + .../distributed-tracing/how-to-use/node.mdx | 4 + .../custom-instrumentation.mdx | 7 ++ 5 files changed, 158 insertions(+), 30 deletions(-) create mode 100644 src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx index 36ef0611ee4fec..c7339349c9b341 100644 --- a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx +++ b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx @@ -1,53 +1,69 @@ -On this page you will learn how to manually propagate trace information into and out of your JavaScript application. Please note, that you do not need to do this manually, if you [use one of our supported frameworks](/platforms/javascript/usage/distributed-tracing/#how-to-use-distributed-tracing), or you have our performance monitoring feature turned on. +On this page you will learn how to manually propagate trace information into and out of your JavaScript application. -To set it up manually, all you have to do is to make sure your application extracts incoming headers and to set those headers again when making an outgoing request within your application. +In the following cases, distributed tracing will be set up automatically for you: -To enable distributed tracing, add the `BrowserTracing` integration to your `Sentry.init` options, as described in the Performance Automatic Instrumentation docs. The [Next.js](/platforms/javascript/guides/nextjs/) and [SvelteKit](/platforms/javascript/guides/sveltekit/) SDKs include this integration by default. +- You have our performance monitoring feature turned on. +- You are using one of the platforms that include distributed tracing out of the box: + - `@sentry/nextjs` + - `@sentry/sveltekit` + - `@sentry/remix` + - `@sentry/astro` -If you are using one of the frameworks listed above, see the Automatic Instrumentation. page on how to configure distributed tracing. +If you are using a different package, and have not enabled performance monitoring, you can manually set up your application for distributed tracing to work. -If you prefer to implement custom distributed tracing, you must: +## Enabling Distributed Tracing without Performance + +You can add the `BrowserTracing` integration in your `Sentry.init()` options, as described in the Performance Automatic Instrumentation docs. If you combine this with `tracesSampleRate: 0`, you will have distributed tracing without performance monitoring: + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [new Sentry.BrowserTracing()], + tracesSampleRate: 0, +}); +``` + +## Enabling Distributed Tracing without `BrowserTracing` + +If you do not want to use the `BrowserTracing` integration, you can manually extract and inject tracing information into your application. For this, you must: - Extract and store incoming tracing information from HTML `meta` tags when loading the page - Inject tracing information to the outgoing request when sending outgoing requests. -To learn more, see our Distributed Tracing docs. +To learn more, see our Distributed Tracing docs. -## Extract Tracing Information From HTML `meta` Tags +### Extract Tracing Information From HTML `meta` Tags Assuming the backend that renders the HTML has injected tracing information into the HTML as `meta` tags, you can extract that tracing information on `pageload` and use it to create new transactions connected to that incoming trace. -See the docs on how to [Inject Tracing Information Into Rendered HTML](/platforms/python/distributed-tracing/instrumentation/custom-instrumentation/#inject-tracing-information-into-rendered-html) to learn more about how to configure your backend to inject this information. +Some of our backend SDKs provide a built-in way to inject tracing information into rendered HTML. For example: -For example, on `pageload` you could do the following: +- [Python](/platforms/python/usage/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html) +- [Ruby](/platforms/ruby/usage/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html) +- [PHP](/platforms/php/usage/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html) + +Then, on `pageload` you can do the following: ```javascript // Read meta tag values -const sentryTraceMetaTagValue = getMetaContent("sentry-trace"); -const baggageMetaTagValue = getMetaContent("baggage"); - -// Extract Sentry trace information -const traceParentData = extractTraceparentData(sentryTraceMetaTagValue); - -// Create Dynamic Sampling Context -const dynamicSamplingContext = - baggageHeaderToDynamicSamplingContext(baggageMetaTagValue); - -// Create transaction context -const transactionContext = { - ...traceParentData, - metadata: { - dynamicSamplingContext: dynamicSamplingContext, - }, -}; - -// Start transaction with tracing information of meta tags -const pageLoadTransaction = startTransaction(hub, transactionContext); +const sentryTrace = getMetaContent("sentry-trace"); +const baggage = getMetaContent("baggage"); + +const pageLoadTransaction = Sentry.continueTrace( + { sentryTrace, baggage }, + (transactionContext) => { + return Sentry.startTransaction({ + ...transactionContext, + name: "my pageload", + op: "pageload", + }); + } +); ``` In this example, we create a new transaction that is attached to the trace specified in the `sentry-trace` and `baggage` HTML `meta` tags. -## Inject Tracing Information to Outgoing Requests +### Inject Tracing Information to Outgoing Requests For distributed tracing to work, the two headers that you extracted and stored in the `pageLoadTransaction`, `sentry-trace` and `baggage`, must be added to outgoing XHR/fetch requests. diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx new file mode 100644 index 00000000000000..fa8c6aef1900e0 --- /dev/null +++ b/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx @@ -0,0 +1,97 @@ +On this page you will learn how to manually propagate trace information into and out of your JavaScript application. + +In the following cases, distributed tracing will be set up automatically for you: + +- You have our performance monitoring feature turned on. +- You are using one of the platforms that include distributed tracing out of the box: + - `@sentry/nextjs` + - `@sentry/sveltekit` + - `@sentry/remix` + - `@sentry/astro` + +If you are using a different package, and have not enabled performance monitoring, you can manually set up your application for distributed tracing to work. + +## Enabling Distributed Tracing without Performance + +You can setup the `Http` integration in combination with `tracesSampleRate: 0` to enable distributed tracing without performance monitoring: + +```javascript +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [new Sentry.Integrations.Http({ tracing: true })], + tracesSampleRate: 0, +}); +``` + +## Enabling Distributed Tracing without `Http` Integration + +If you do not want to use the `Http` integration in conjuction with `tracing: true`, you can manually extract and inject tracing information into your application. For this, you must: + +- Extract and store incoming tracing information from incoming request headers or similar. +- Inject tracing information to the outgoing request when sending outgoing requests. + +To learn more, see our Distributed Tracing docs. + +### Extracting Incoming Tracing Information + +Incoming tracing information has to be extracted and stored in memory for later use. Sentry provides the `continueTrace()` function to help you with this. Incoming tracing information can come from different places: + +- In a web environment, it's sent with HTTP headers, for example, by another Sentry SDK used in your frontend project. +- In a job queue, it can be retrieved from meta or header variables. +- You also can pick up tracing information from environment variables. + +Here's an example of how to extract and store incoming tracing information using `continueTrace()`: + +```javascript +const sentryTrace = getRequestHeader("sentry-trace"); +const baggage = getRequestHeader("baggage"); + +const requestTransaction = Sentry.continueTrace( + { sentryTrace, baggage }, + (transactionContext) => { + return Sentry.startTransaction({ + ...transactionContext, + name: "my request", + op: "http.server", + }); + } +); +``` + +In this example, we create a new transaction that is attached to the trace specified in the `sentry-trace` and `baggage` headers. + +### Inject Tracing Information to Outgoing Requests + +For distributed tracing to work, the two headers that you extracted and stored in the `requestTransaction`, `sentry-trace` and `baggage`, must be added to outgoing http/fetch requests. + +Here's an example of how to collect and inject this tracing information to outgoing requests: + +```javascript +// Create `sentry-trace` header +const sentryTraceHeader = requestTransaction.toTraceparent(); + +// Create `baggage` header +const dynamicSamplingContext = requestTransaction.getDynamicSamplingContext(); +const sentryBaggageHeader = dynamicSamplingContextToSentryBaggageHeader( + dynamicSamplingContext +); + +// Make outgoing request +fetch("https://example.com", { + method: "GET", + headers: { + baggage: sentryBaggageHeader, + "sentry-trace": sentryTraceHeader, + }, +}).then((response) => { + // ... +}); +``` + +In this example, tracing information is propagated to the project running at `https://example.com`. If this project uses a Sentry SDK, it will extract and save the tracing information for later use. + +The two services are now connected with your custom distributed tracing implementation. + +## Verification + +If you make outgoing requests from your project to other services, check if the headers `sentry-trace` and `baggage` are present in the request. If so, distributed tracing is working. diff --git a/src/platform-includes/distributed-tracing/how-to-use/javascript.mdx b/src/platform-includes/distributed-tracing/how-to-use/javascript.mdx index 69358362c6addf..dd3864f93e64a6 100644 --- a/src/platform-includes/distributed-tracing/how-to-use/javascript.mdx +++ b/src/platform-includes/distributed-tracing/how-to-use/javascript.mdx @@ -8,4 +8,8 @@ Sentry.init({ }); ``` +### Custom Instrumentation + +If you do not want to use performance monitoring, you can instead set up Custom Instrumentation for distributed tracing. + If you're using version `7.57.x` or below, you'll need to have our performance monitoring feature enabled in order for distributed tracing to work. diff --git a/src/platform-includes/distributed-tracing/how-to-use/node.mdx b/src/platform-includes/distributed-tracing/how-to-use/node.mdx index 26c6694998e97c..f2d4e27689c305 100644 --- a/src/platform-includes/distributed-tracing/how-to-use/node.mdx +++ b/src/platform-includes/distributed-tracing/how-to-use/node.mdx @@ -21,4 +21,8 @@ app.use(Sentry.Handlers.requestHandler()); app.use(Sentry.Handlers.tracingHandler()); ``` +### Custom Instrumentation + +If you do not want to use performance monitoring, you can instead set up Custom Instrumentation for distributed tracing. + If you're using version `7.57.x` or below, you'll need to have our performance monitoring feature enabled in order for distributed tracing to work. diff --git a/src/platforms/common/usage/distributed-tracing/custom-instrumentation.mdx b/src/platforms/common/usage/distributed-tracing/custom-instrumentation.mdx index 675999e0af353c..7ba22597feffd5 100644 --- a/src/platforms/common/usage/distributed-tracing/custom-instrumentation.mdx +++ b/src/platforms/common/usage/distributed-tracing/custom-instrumentation.mdx @@ -9,6 +9,13 @@ supported: - android - ruby - dotnet + - javascript + - node +notSupported: + - javascript.nextjs + - javascript.remix + - javascript.sveltekit + - javascript.astro --- From 76dfcd9cc962d2abad48a05cac20bbac2a1fe0dd Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Fri, 10 Nov 2023 12:21:59 +0100 Subject: [PATCH 2/7] Apply suggestions from code review Co-authored-by: Luca Forstner --- .../custom-instrumentation/javascript.mdx | 29 +++++++++++-------- .../custom-instrumentation/node.mdx | 28 +++++++++++------- 2 files changed, 34 insertions(+), 23 deletions(-) diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx index c7339349c9b341..1e5a65ab2dd734 100644 --- a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx +++ b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx @@ -11,32 +11,37 @@ In the following cases, distributed tracing will be set up automatically for you If you are using a different package, and have not enabled performance monitoring, you can manually set up your application for distributed tracing to work. -## Enabling Distributed Tracing without Performance +## Enabling Distributed Tracing -You can add the `BrowserTracing` integration in your `Sentry.init()` options, as described in the Performance Automatic Instrumentation docs. If you combine this with `tracesSampleRate: 0`, you will have distributed tracing without performance monitoring: +To enable Distributed Tracing for your frontend, add the `BrowserTracing` integration to your `Sentry.init()` options as described in the Automatic Instrumentation docs. + +If you want to have Distributed Tracing functionality but at the same time want to disable performance monitoring, set the `tracesSampleRate` option to `0`. ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", integrations: [new Sentry.BrowserTracing()], - tracesSampleRate: 0, + + // Optionally disable performance monitoring: + // tracesSampleRate: 0, }); -``` ## Enabling Distributed Tracing without `BrowserTracing` If you do not want to use the `BrowserTracing` integration, you can manually extract and inject tracing information into your application. For this, you must: -- Extract and store incoming tracing information from HTML `meta` tags when loading the page -- Inject tracing information to the outgoing request when sending outgoing requests. +- Extract and store incoming tracing information from HTML `` tags when loading the page. +- Inject tracing information to any outgoing requests. To learn more, see our Distributed Tracing docs. ### Extract Tracing Information From HTML `meta` Tags -Assuming the backend that renders the HTML has injected tracing information into the HTML as `meta` tags, you can extract that tracing information on `pageload` and use it to create new transactions connected to that incoming trace. +If you have a server that renders your applications HTML (SSR) and is also running a Sentry SDK, you can connect your backend to your backend via tracing. + +To achieve this, have your server render HTML `` tags with the Sentry trace information. In your frontend, you can then extract that tracing information when the page is loading and use it to create new transactions connected to that incoming backend trace. -Some of our backend SDKs provide a built-in way to inject tracing information into rendered HTML. For example: +Some of our backend SDKs provide a built-in way to inject these `` tags into rendered HTML. For example: - [Python](/platforms/python/usage/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html) - [Ruby](/platforms/ruby/usage/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html) @@ -46,22 +51,22 @@ Then, on `pageload` you can do the following: ```javascript // Read meta tag values -const sentryTrace = getMetaContent("sentry-trace"); -const baggage = getMetaContent("baggage"); +const sentryTrace = document.querySelector('meta[name=sentry-trace]')?.content; +const baggage = document.querySelector('meta[name=baggage]')?.content; const pageLoadTransaction = Sentry.continueTrace( { sentryTrace, baggage }, (transactionContext) => { return Sentry.startTransaction({ ...transactionContext, - name: "my pageload", + name: `Pageload: ${window.location.pathname}`, op: "pageload", }); } ); ``` -In this example, we create a new transaction that is attached to the trace specified in the `sentry-trace` and `baggage` HTML `meta` tags. +In this example, we create a new transaction that is attached to the trace specified in the `sentry-trace` and `baggage` HTML `` tags. ### Inject Tracing Information to Outgoing Requests diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx index fa8c6aef1900e0..5f432122e1eb27 100644 --- a/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx +++ b/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx @@ -1,4 +1,4 @@ -On this page you will learn how to manually propagate trace information into and out of your JavaScript application. +On this page, you will learn how to manually propagate trace information into and out of your Node.js application. In the following cases, distributed tracing will be set up automatically for you: @@ -28,7 +28,7 @@ Sentry.init({ If you do not want to use the `Http` integration in conjuction with `tracing: true`, you can manually extract and inject tracing information into your application. For this, you must: - Extract and store incoming tracing information from incoming request headers or similar. -- Inject tracing information to the outgoing request when sending outgoing requests. +- Inject tracing information to any outgoing requests. To learn more, see our Distributed Tracing docs. @@ -43,19 +43,25 @@ Incoming tracing information has to be extracted and stored in memory for later Here's an example of how to extract and store incoming tracing information using `continueTrace()`: ```javascript -const sentryTrace = getRequestHeader("sentry-trace"); -const baggage = getRequestHeader("baggage"); +const http = require('http'); -const requestTransaction = Sentry.continueTrace( - { sentryTrace, baggage }, - (transactionContext) => { +http.createServer((request, response) => { + const sentryTraceHeaders = request.headers['sentry-trace']; + const sentryTrace = Array.isArray(sentryTraceHeaders) ? sentryTraceHeaders.join(',') : sentryTraceHeaders; + const baggage = request.headers['baggage']; + + const requestTransaction = Sentry.continueTrace({ sentryTrace, baggage }, (transactionContext) => { return Sentry.startTransaction({ ...transactionContext, - name: "my request", - op: "http.server", + name: 'my request', + op: 'http.server', }); - } -); + }); + + // Your API code... + + requestTransaction.finish(); +}); ``` In this example, we create a new transaction that is attached to the trace specified in the `sentry-trace` and `baggage` headers. From b56d6f381299dbde69e90057e438f97c1f68cfa0 Mon Sep 17 00:00:00 2001 From: "getsantry[bot]" <66042841+getsantry[bot]@users.noreply.github.com> Date: Fri, 10 Nov 2023 11:23:38 +0000 Subject: [PATCH 3/7] [getsentry/action-github-commit] Auto commit --- .../custom-instrumentation/javascript.mdx | 6 ++-- .../custom-instrumentation/node.mdx | 29 +++++++++++-------- 2 files changed, 20 insertions(+), 15 deletions(-) diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx index 1e5a65ab2dd734..9aa89f46f36e83 100644 --- a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx +++ b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx @@ -17,11 +17,11 @@ To enable Distributed Tracing for your frontend, add the `BrowserTracing` integr If you want to have Distributed Tracing functionality but at the same time want to disable performance monitoring, set the `tracesSampleRate` option to `0`. -```javascript +````javascript Sentry.init({ dsn: "___PUBLIC_DSN___", integrations: [new Sentry.BrowserTracing()], - + // Optionally disable performance monitoring: // tracesSampleRate: 0, }); @@ -64,7 +64,7 @@ const pageLoadTransaction = Sentry.continueTrace( }); } ); -``` +```` In this example, we create a new transaction that is attached to the trace specified in the `sentry-trace` and `baggage` HTML `` tags. diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx index 5f432122e1eb27..7c2edc4ca640c0 100644 --- a/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx +++ b/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx @@ -43,20 +43,25 @@ Incoming tracing information has to be extracted and stored in memory for later Here's an example of how to extract and store incoming tracing information using `continueTrace()`: ```javascript -const http = require('http'); +const http = require("http"); http.createServer((request, response) => { - const sentryTraceHeaders = request.headers['sentry-trace']; - const sentryTrace = Array.isArray(sentryTraceHeaders) ? sentryTraceHeaders.join(',') : sentryTraceHeaders; - const baggage = request.headers['baggage']; - - const requestTransaction = Sentry.continueTrace({ sentryTrace, baggage }, (transactionContext) => { - return Sentry.startTransaction({ - ...transactionContext, - name: 'my request', - op: 'http.server', - }); - }); + const sentryTraceHeaders = request.headers["sentry-trace"]; + const sentryTrace = Array.isArray(sentryTraceHeaders) + ? sentryTraceHeaders.join(",") + : sentryTraceHeaders; + const baggage = request.headers["baggage"]; + + const requestTransaction = Sentry.continueTrace( + { sentryTrace, baggage }, + (transactionContext) => { + return Sentry.startTransaction({ + ...transactionContext, + name: "my request", + op: "http.server", + }); + } + ); // Your API code... From a1b03bf6214454392d3a1068bd24aff285e44315 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Tue, 14 Nov 2023 08:52:22 +0100 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Shana Matthews --- .../custom-instrumentation/javascript.mdx | 20 +++++++++---------- .../custom-instrumentation/node.mdx | 12 +++++------ .../how-to-use/javascript.mdx | 2 +- .../distributed-tracing/how-to-use/node.mdx | 2 +- 4 files changed, 18 insertions(+), 18 deletions(-) diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx index 9aa89f46f36e83..deaeaaa8af6783 100644 --- a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx +++ b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx @@ -1,9 +1,9 @@ On this page you will learn how to manually propagate trace information into and out of your JavaScript application. -In the following cases, distributed tracing will be set up automatically for you: +Distributed tracing will be set up automatically if: -- You have our performance monitoring feature turned on. -- You are using one of the platforms that include distributed tracing out of the box: +- You've Set Up Performance in Sentry. +- You're using one of the platforms that include distributed tracing out of the box: - `@sentry/nextjs` - `@sentry/sveltekit` - `@sentry/remix` @@ -13,9 +13,9 @@ If you are using a different package, and have not enabled performance monitorin ## Enabling Distributed Tracing -To enable Distributed Tracing for your frontend, add the `BrowserTracing` integration to your `Sentry.init()` options as described in the Automatic Instrumentation docs. +To enable distributed tracing for your frontend, add the `BrowserTracing` integration to your `Sentry.init()` options as described in the Automatic Instrumentation docs. -If you want to have Distributed Tracing functionality but at the same time want to disable performance monitoring, set the `tracesSampleRate` option to `0`. +If you want to use distributed tracing but not performance monitoring, set the `tracesSampleRate` option to `0`. ````javascript Sentry.init({ @@ -28,20 +28,20 @@ Sentry.init({ ## Enabling Distributed Tracing without `BrowserTracing` -If you do not want to use the `BrowserTracing` integration, you can manually extract and inject tracing information into your application. For this, you must: +If you don't want to use the `BrowserTracing` integration, you can manually extract and inject tracing data in your application to connect multiple systems. For this, you must: - Extract and store incoming tracing information from HTML `` tags when loading the page. - Inject tracing information to any outgoing requests. -To learn more, see our Distributed Tracing docs. +To learn more about distributed tracing, see our Distributed Tracing docs. ### Extract Tracing Information From HTML `meta` Tags -If you have a server that renders your applications HTML (SSR) and is also running a Sentry SDK, you can connect your backend to your backend via tracing. +If you have a server that renders your application's HTML (SSR) and is also running a Sentry SDK, you can connect your backend to your backend via tracing. -To achieve this, have your server render HTML `` tags with the Sentry trace information. In your frontend, you can then extract that tracing information when the page is loading and use it to create new transactions connected to that incoming backend trace. +To do this, have your server render HTML `` tags with the Sentry trace information. In your frontend, extract that tracing information when the page is loading and use it to create new transactions connected to that incoming backend trace. -Some of our backend SDKs provide a built-in way to inject these `` tags into rendered HTML. For example: +Some Sentry backend SDKs provide a built-in way to inject these `` tags into rendered HTML. For example: - [Python](/platforms/python/usage/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html) - [Ruby](/platforms/ruby/usage/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html) diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx index 7c2edc4ca640c0..26e3245b7f9292 100644 --- a/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx +++ b/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx @@ -1,15 +1,15 @@ On this page, you will learn how to manually propagate trace information into and out of your Node.js application. -In the following cases, distributed tracing will be set up automatically for you: +Distributed tracing will be set up automatically if: -- You have our performance monitoring feature turned on. -- You are using one of the platforms that include distributed tracing out of the box: +- You've Set Up Performance in Sentry. +- You're using one of the platforms that include distributed tracing out of the box: - `@sentry/nextjs` - `@sentry/sveltekit` - `@sentry/remix` - `@sentry/astro` -If you are using a different package, and have not enabled performance monitoring, you can manually set up your application for distributed tracing to work. +If you're using a different package, and haven't enabled performance monitoring, you can manually set up distributed tracing in your application. ## Enabling Distributed Tracing without Performance @@ -30,11 +30,11 @@ If you do not want to use the `Http` integration in conjuction with `tracing: tr - Extract and store incoming tracing information from incoming request headers or similar. - Inject tracing information to any outgoing requests. -To learn more, see our Distributed Tracing docs. +To learn more about distributed tracing, see our Distributed Tracing docs. ### Extracting Incoming Tracing Information -Incoming tracing information has to be extracted and stored in memory for later use. Sentry provides the `continueTrace()` function to help you with this. Incoming tracing information can come from different places: +You must extract and store incoming tracing information in memory for later use. Sentry provides the `continueTrace()` function to help you with this. Incoming tracing information can come from different places: - In a web environment, it's sent with HTTP headers, for example, by another Sentry SDK used in your frontend project. - In a job queue, it can be retrieved from meta or header variables. diff --git a/src/platform-includes/distributed-tracing/how-to-use/javascript.mdx b/src/platform-includes/distributed-tracing/how-to-use/javascript.mdx index dd3864f93e64a6..23a7c842176353 100644 --- a/src/platform-includes/distributed-tracing/how-to-use/javascript.mdx +++ b/src/platform-includes/distributed-tracing/how-to-use/javascript.mdx @@ -10,6 +10,6 @@ Sentry.init({ ### Custom Instrumentation -If you do not want to use performance monitoring, you can instead set up Custom Instrumentation for distributed tracing. +If you don't want to use performance monitoring, you can set up Custom Instrumentation for distributed tracing. If you're using version `7.57.x` or below, you'll need to have our performance monitoring feature enabled in order for distributed tracing to work. diff --git a/src/platform-includes/distributed-tracing/how-to-use/node.mdx b/src/platform-includes/distributed-tracing/how-to-use/node.mdx index f2d4e27689c305..3d67ceade88e2e 100644 --- a/src/platform-includes/distributed-tracing/how-to-use/node.mdx +++ b/src/platform-includes/distributed-tracing/how-to-use/node.mdx @@ -23,6 +23,6 @@ app.use(Sentry.Handlers.tracingHandler()); ### Custom Instrumentation -If you do not want to use performance monitoring, you can instead set up Custom Instrumentation for distributed tracing. +If you don't want to use performance monitoring, you can set up Custom Instrumentation for distributed tracing. If you're using version `7.57.x` or below, you'll need to have our performance monitoring feature enabled in order for distributed tracing to work. From df1abe254179a6db03bdfee9cdde1faf47b72ac5 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Tue, 14 Nov 2023 08:58:18 +0100 Subject: [PATCH 5/7] PR feedback --- .../custom-instrumentation/javascript.mdx | 9 ++++---- .../custom-instrumentation/node.mdx | 23 ++++++++++++++----- 2 files changed, 22 insertions(+), 10 deletions(-) diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx index deaeaaa8af6783..3420d0cd504c45 100644 --- a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx +++ b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx @@ -17,7 +17,7 @@ To enable distributed tracing for your frontend, add the `BrowserTracing` integr If you want to use distributed tracing but not performance monitoring, set the `tracesSampleRate` option to `0`. -````javascript +```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", integrations: [new Sentry.BrowserTracing()], @@ -25,6 +25,7 @@ Sentry.init({ // Optionally disable performance monitoring: // tracesSampleRate: 0, }); +``` ## Enabling Distributed Tracing without `BrowserTracing` @@ -51,8 +52,8 @@ Then, on `pageload` you can do the following: ```javascript // Read meta tag values -const sentryTrace = document.querySelector('meta[name=sentry-trace]')?.content; -const baggage = document.querySelector('meta[name=baggage]')?.content; +const sentryTrace = document.querySelector("meta[name=sentry-trace]")?.content; +const baggage = document.querySelector("meta[name=baggage]")?.content; const pageLoadTransaction = Sentry.continueTrace( { sentryTrace, baggage }, @@ -64,7 +65,7 @@ const pageLoadTransaction = Sentry.continueTrace( }); } ); -```` +``` In this example, we create a new transaction that is attached to the trace specified in the `sentry-trace` and `baggage` HTML `` tags. diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx index 26e3245b7f9292..7c489f66e5cff1 100644 --- a/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx +++ b/src/platform-includes/distributed-tracing/custom-instrumentation/node.mdx @@ -9,23 +9,34 @@ Distributed tracing will be set up automatically if: - `@sentry/remix` - `@sentry/astro` -If you're using a different package, and haven't enabled performance monitoring, you can manually set up distributed tracing in your application. +If you're not using any of the packages above, take a look at the framework-specific Sentry integrations (like our [Express integration](/platforms/node/guides/express/)). These integrations will also enable distributed tracing automatically for your application. +If you can't find an integration for your framework, it is possible to set up distributed tracing for your application manually. -## Enabling Distributed Tracing without Performance +## Enabling Distributed Tracing You can setup the `Http` integration in combination with `tracesSampleRate: 0` to enable distributed tracing without performance monitoring: +To enable distributed tracing for your frontend, configure the `Http` or `Undici` integration in your `Sentry.init()` options as described in the Automatic Instrumentation docs. + +If you want to use distributed tracing but not performance monitoring, set the `tracesSampleRate` option to `0`. + ```javascript Sentry.init({ dsn: "___PUBLIC_DSN___", - integrations: [new Sentry.Integrations.Http({ tracing: true })], - tracesSampleRate: 0, + integrations: [ + new Sentry.Integrations.Http({ tracing: true }), + // The Undici integrations instruments fetch in Node 18+ + new Sentry.Integrations.Undici(), + ], + + // Optionally disable performance monitoring: + // tracesSampleRate: 0, }); ``` -## Enabling Distributed Tracing without `Http` Integration +## Enabling Distributed Tracing without `Http`/`Undici` Integration -If you do not want to use the `Http` integration in conjuction with `tracing: true`, you can manually extract and inject tracing information into your application. For this, you must: +If you do not want to use the `Http` or `Undici` integrations, you can manually extract and inject tracing data into your application. For this, you must: - Extract and store incoming tracing information from incoming request headers or similar. - Inject tracing information to any outgoing requests. From 025585f6ef478dcd9cbf6585f33b9bedd8ea1725 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Tue, 14 Nov 2023 10:24:01 +0100 Subject: [PATCH 6/7] fix not supported --- .../usage/distributed-tracing/custom-instrumentation.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/platforms/common/usage/distributed-tracing/custom-instrumentation.mdx b/src/platforms/common/usage/distributed-tracing/custom-instrumentation.mdx index 7ba22597feffd5..ff67e54509539c 100644 --- a/src/platforms/common/usage/distributed-tracing/custom-instrumentation.mdx +++ b/src/platforms/common/usage/distributed-tracing/custom-instrumentation.mdx @@ -12,10 +12,10 @@ supported: - javascript - node notSupported: - - javascript.nextjs - - javascript.remix - - javascript.sveltekit - - javascript.astro + - elixir + - javascript.cordova + - kotlin-multiplatform + - unreal --- From 0e2d36fb5a13157796b1f2f2a98c3a0e7a45d1de Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Tue, 14 Nov 2023 10:39:58 +0100 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: Lukas Stracke --- .../distributed-tracing/custom-instrumentation/javascript.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx index 3420d0cd504c45..e377361cafcf80 100644 --- a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx +++ b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx @@ -3,7 +3,7 @@ On this page you will learn how to manually propagate trace information into and Distributed tracing will be set up automatically if: - You've Set Up Performance in Sentry. -- You're using one of the platforms that include distributed tracing out of the box: +- You're using one of the SDKs that include distributed tracing out of the box: - `@sentry/nextjs` - `@sentry/sveltekit` - `@sentry/remix`