Skip to content

Commit 88da19d

Browse files
mydeacoolguyzoneLms24
authored
feat(js): Update custom trace propagation docs (#12475)
 --------- Co-authored-by: Alex Krawiec <[email protected]> Co-authored-by: Lukas Stracke <[email protected]>
1 parent f940420 commit 88da19d

File tree

7 files changed

+196
-229
lines changed

7 files changed

+196
-229
lines changed

‎docs/platforms/javascript/common/tracing/instrumentation/custom-instrumentation/index.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Custom Instrumentation
2+
title: Custom Span Instrumentation
33
description: "Learn how to capture performance data on any action in your app."
44
sidebar_order: 20
55
---

‎docs/platforms/javascript/common/tracing/trace-propagation/custom-instrumentation/index.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Custom Instrumentation
2+
title: Custom Trace Propagation
33
sidebar_order: 40
44
notSupported:
55
- javascript.cordova

‎docs/platforms/javascript/common/tracing/trace-propagation/index.mdx

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,7 @@ If the overall application landscape that you want to observe with Sentry consis
1010

1111
## What is Distributed Tracing?
1212

13-
In the context of tracing events across a distributed system, distributed tracing acts as a powerful debugging tool. Imagine your application as a vast network of interconnected parts. For example, your system might be spread across different servers or your application might split into different backend and frontend services, each potentially having their own technology stack.
14-
15-
When an error or performance issue occurs, it can be challenging to pinpoint the root cause due to the complexity of such a system. Distributed tracing helps you follow the path of an event as it travels through this intricate web, recording every step it takes. By examining these traces, you can reconstruct the sequence of events leading up to the event of interest, identify the specific components involved, and understand their interactions. This detailed visibility enables you to diagnose and resolve issues more effectively, ultimately improving the reliability and performance of your distributed system.
13+
<PlatformContent includePath="distributed-tracing/explanation" />
1614

1715
## Basic Example
1816

‎platform-includes/distributed-tracing/custom-instrumentation/browser/javascript.mdx

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
Distributed tracing will be set up automatically if you've <PlatformLink to="/tracing/">set up tracing</PlatformLink>.
2+
3+
<Expandable title="What is Distributed Tracing?">
4+
<PlatformContent includePath="distributed-tracing/explanation" />
5+
</Expandable>
6+
7+
When tracing is enabled, the Sentry SDK will not only create spans for pageloads and transactions but also propagate trace information to other systems. This allows you to connect multiple systems and see how they interact with each other.
8+
9+
By default, outgoing HTTP requests will automatically be instrumented for you. For other cases where you may want to continue traces (for example when working with websockets), you can manually extract and inject tracing information.
10+
11+
## Enabling Automatic Distributed Tracing
12+
13+
To enable distributed tracing for your frontend, add `browserTracingIntegration` to your `Sentry.init()` options as described in the <PlatformLink to="/tracing/instrumentation/automatic-instrumentation/">Automatic Instrumentation</PlatformLink> docs.
14+
15+
### Continuing a Trace Manually
16+
17+
By default, the `browserTracingIntegration` will automatically continue a trace found in a `<meta>` tag - see <PlatformLink to="/tracing/trace-propagation/#automatic-trace-propagation">Automatic Trace Propagation</PlatformLink> for details.
18+
If you want to continue a different trace, for example because you cannot propagate the trace through meta tags but through some different mechanism, you can do this:
19+
20+
```javascript
21+
const client = Sentry.init({
22+
dsn: "___PUBLIC_DSN___",
23+
integrations: [
24+
Sentry.browserTracingIntegration({
25+
// Disable default pageload instrumentation
26+
instrumentPageLoad: false,
27+
}),
28+
],
29+
});
30+
31+
// Start the pageload span manually
32+
const sentryTrace = getSentryTraceStringFromSomewhere();
33+
const baggage = getBaggageStringFromSomewhere();
34+
35+
Sentry.startBrowserTracingPageLoadSpan(
36+
client,
37+
{
38+
name: window.location.pathname,
39+
},
40+
{ sentryTrace, baggage }
41+
);
42+
```
43+
44+
## Configuring Distributed Tracing Without `browserTracingIntegration`
45+
46+
If you don't want to use the `browserTracingIntegration` integration, or you want to propagate traces in other places than HTTP requests (for example, with websockets), you can manually extract and inject tracing data in your application to connect multiple systems. For this, you must:
47+
48+
- Extract and store incoming tracing information from HTML `<meta>` tags when loading the page.
49+
- Inject tracing information to any outgoing requests.
50+
51+
To learn more about distributed tracing, see our <PlatformLink to="/tracing/trace-propagation/">Distributed Tracing</PlatformLink> docs.
52+
53+
### Extract Tracing Information From HTML `meta` Tags
54+
55+
If you have a server that renders your application's HTML (server-side rendering) and is also running a Sentry SDK, you can connect your backend to your backend via tracing.
56+
57+
To do this, have your server render HTML `<meta>` 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.
58+
59+
Some Sentry backend SDKs provide a built-in way to inject these `<meta>` tags into rendered HTML. For example:
60+
61+
- [Node](/platforms/javascript/guides/node/tracing/trace-propagation/custom-instrumentation/#injecting-tracing-information-into-html)
62+
- [Python](/platforms/python/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html)
63+
- [Ruby](/platforms/ruby/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html)
64+
- [PHP](/platforms/php/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html)
65+
66+
Then, on `pageload` you can do the following:
67+
68+
```javascript
69+
import { propagationContextFromHeaders } from "@sentry/core"; // Before version 8.40.0, import from "@sentry/utils"
70+
import * as Sentry from "@sentry/browser";
71+
72+
// Read meta tag values
73+
const sentryTrace = document.querySelector("meta[name=sentry-trace]")?.content;
74+
const baggage = document.querySelector("meta[name=baggage]")?.content;
75+
76+
// Generate a propagation context from the meta tags
77+
const propagationContext = propagationContextFromHeaders(sentryTrace, baggage);
78+
Sentry.getCurrentScope().setPropagationContext(propagationContext);
79+
80+
Sentry.startSpan(
81+
{
82+
name: `Pageload: ${window.location.pathname}`,
83+
op: "pageload",
84+
},
85+
() => {
86+
// do something
87+
}
88+
);
89+
```
90+
91+
In this example, we create a new root span that is attached to the trace specified in the `sentry-trace` and `baggage` HTML `<meta>` tags.

‎platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx

Lines changed: 10 additions & 224 deletions
Original file line numberDiff line numberDiff line change
@@ -1,174 +1,14 @@
11
On this page you will learn how to manually propagate trace information into and out of your JavaScript application.
22

3-
Distributed tracing will be set up automatically if:
4-
5-
- You've <PlatformLink to="/tracing/">Set Up Tracing</PlatformLink>, or
6-
- You're using one of the SDKs that include tracing propagation out of the box:
7-
- `@sentry/astro`
8-
- `@sentry/nextjs`
9-
- `@sentry/nuxt`
10-
- `@sentry/remix`
11-
- `@sentry/solidstart`
12-
- `@sentry/sveltekit`
13-
14-
If you are using a different package, and have not enabled tracing, you can manually set up your application for distributed tracing to work.
15-
16-
## Enabling Distributed Tracing
17-
18-
<PlatformCategorySection supported={['browser']}>
19-
20-
To enable distributed tracing for your frontend, add `browserTracingIntegration` to your `Sentry.init()` options as described in the <PlatformLink to="/tracing/instrumentation/automatic-instrumentation/">Automatic Instrumentation</PlatformLink> docs.
21-
22-
If you want to use distributed tracing but not tracing, set the `tracesSampleRate` option to `0`.
23-
24-
```javascript
25-
Sentry.init({
26-
dsn: "___PUBLIC_DSN___",
27-
integrations: [Sentry.browserTracingIntegration()],
28-
29-
// If this is 0, tracing is disabled
30-
// but distributed tracing is not
31-
tracesSampleRate: 0,
32-
});
33-
```
34-
35-
### Continuing a Trace Manually
36-
37-
By default, the `browserTracingIntegration` will automatically continue a trace found in a `<meta>` tags - see <PlatformLink to="/tracing/trace-propagation/#automatic-trace-propagation">Automatic Trace Propagation</PlatformLink> for details.
38-
If you want to continue a different trace, for example because you cannot propagate the trace through meta tags but through some different mechanism, you can do this as follows:
39-
40-
```javascript
41-
const client = Sentry.init({
42-
dsn: "___PUBLIC_DSN___",
43-
integrations: [
44-
Sentry.browserTracingIntegration({
45-
// Disable default pageload instrumentation
46-
instrumentPageLoad: false,
47-
}),
48-
],
49-
});
50-
51-
// Start the pageload span manually
52-
const sentryTrace = getSentryTraceStringFromSomewhere();
53-
const baggage = getBaggageStringFromSomewhere();
54-
55-
Sentry.startBrowserTracingPageLoadSpan(
56-
client,
57-
{
58-
name: window.location.pathname,
59-
},
60-
{ sentryTrace, baggage }
61-
);
62-
```
63-
64-
## Enabling Distributed Tracing without `browserTracingIntegration`
65-
66-
If you don't want to use the `browserTracingIntegration` integration, you can manually extract and inject tracing data in your application to connect multiple systems. For this, you must:
67-
68-
- Extract and store incoming tracing information from HTML `<meta>` tags when loading the page.
69-
- Inject tracing information to any outgoing requests.
70-
71-
To learn more about distributed tracing, see our <PlatformLink to="/tracing/trace-propagation/">Distributed Tracing</PlatformLink> docs.
72-
73-
### Extract Tracing Information From HTML `meta` Tags
74-
75-
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.
76-
77-
To do this, have your server render HTML `<meta>` 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.
78-
79-
Some Sentry backend SDKs provide a built-in way to inject these `<meta>` tags into rendered HTML. For example:
80-
81-
- [Python](/platforms/python/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html)
82-
- [Ruby](/platforms/ruby/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html)
83-
- [PHP](/platforms/php/distributed-tracing/custom-instrumentation/#inject-tracing-information-into-rendered-html)
84-
85-
Then, on `pageload` you can do the following:
86-
87-
```javascript
88-
import { propagationContextFromHeaders } from "@sentry/core"; // Before version 8.40.0, import from "@sentry/utils"
89-
import * as Sentry from "@sentry/browser";
90-
91-
// Read meta tag values
92-
const sentryTrace = document.querySelector("meta[name=sentry-trace]")?.content;
93-
const baggage = document.querySelector("meta[name=baggage]")?.content;
94-
95-
// Generate a propagation context from the meta tags
96-
const propagationContext = propagationContextFromHeaders(sentryTrace, baggage);
97-
Sentry.getCurrentScope().setPropagationContext(propagationContext);
98-
99-
Sentry.startSpan(
100-
{
101-
name: `Pageload: ${window.location.pathname}`,
102-
op: "pageload",
103-
},
104-
() => {
105-
// do something
106-
}
107-
);
108-
```
109-
110-
In this example, we create a new root span that is attached to the trace specified in the `sentry-trace` and `baggage` HTML `<meta>` tags.
111-
3+
<PlatformCategorySection
4+
supported={["browser"]}
5+
notSupported={["server", "serverless"]}
6+
>
7+
<PlatformContent includePath="distributed-tracing/custom-instrumentation/browser" />
1128
</PlatformCategorySection>
1139

114-
<PlatformCategorySection supported={['server', 'serverless']}>
115-
If you want to use distributed tracing but not tracing, set the `tracesSampleRate` option to `0`.
116-
117-
```javascript
118-
Sentry.init({
119-
dsn: "___PUBLIC_DSN___",
120-
121-
// If this is 0, tracing is disabled
122-
// but distributed tracing is not
123-
tracesSampleRate: 0,
124-
});
125-
```
126-
127-
## Manually Extracting and Injecting Distributed Tracing Information
128-
129-
You can also manually extract and inject tracing data into your application. For this, you must:
130-
131-
- Extract and store incoming tracing information from incoming request headers or similar.
132-
- Inject tracing information to any outgoing requests.
133-
134-
To learn more about distributed tracing, see our <PlatformLink to="/tracing/trace-propagation/">Distributed Tracing</PlatformLink> docs.
135-
136-
### Extracting Incoming Tracing Information
137-
138-
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:
139-
140-
- In a web environment, it's sent with HTTP headers, for example, by another Sentry SDK used in your frontend project.
141-
- In a job queue, it can be retrieved from meta or header variables.
142-
- You also can pick up tracing information from environment variables.
143-
144-
Here's an example of how to extract and store incoming tracing information using `continueTrace()`:
145-
146-
```javascript
147-
const http = require("http");
148-
149-
http.createServer((request, response) => {
150-
const sentryTraceHeaders = request.headers["sentry-trace"];
151-
const sentryTrace = Array.isArray(sentryTraceHeaders)
152-
? sentryTraceHeaders.join(",")
153-
: sentryTraceHeaders;
154-
const baggage = request.headers["baggage"];
155-
156-
Sentry.continueTrace({ sentryTrace, baggage }, () => {
157-
Sentry.startSpan(
158-
{,
159-
name: "my request",
160-
op: "http.server",
161-
},
162-
() => {
163-
// Your API code...
164-
}
165-
);
166-
});
167-
});
168-
```
169-
170-
In this example, we create a new transaction that is attached to the trace specified in the `sentry-trace` and `baggage` headers.
171-
10+
<PlatformCategorySection supported={["server", "serverless"]}>
11+
<PlatformContent includePath="distributed-tracing/custom-instrumentation/server" />
17212
</PlatformCategorySection>
17313

17414
### Inject Tracing Information into Outgoing Requests
@@ -178,18 +18,9 @@ For distributed tracing to work, the two headers that you extracted and stored i
17818
Here's an example of how to collect and inject this tracing information to outgoing requests:
17919

18020
```javascript
181-
const activeSpan = Sentry.getActiveSpan();
182-
const rootSpan = activeSpan ? Sentry.getRootSpan(activeSpan) : undefined;
183-
184-
// Create `sentry-trace` header
185-
const sentryTraceHeader = rootSpan
186-
? Sentry.spanToTraceHeader(rootSpan)
187-
: undefined;
188-
189-
// Create `baggage` header
190-
const sentryBaggageHeader = rootSpan
191-
? Sentry.spanToBaggageHeader(rootSpan)
192-
: undefined;
21+
const traceData = Sentry.getTraceData();
22+
const sentryTraceHeader = traceData["sentry-trace"];
23+
const sentryBaggageHeader = traceData["baggage"];
19324

19425
// Make outgoing request
19526
fetch("https://example.com", {
@@ -207,51 +38,6 @@ In this example, tracing information is propagated to the project running at `ht
20738

20839
The two services are now connected with your custom distributed tracing implementation.
20940

210-
<PlatformCategorySection notSupported={['browser']}>
211-
212-
### Injecting Tracing Information into HTML
213-
214-
If you're server-side rendering HTML and you use a Sentry SDK in your browser application, you can connect the backend and frontend traces by injecting your server's tracing information as `<meta>` tags into the HTML that's initially served to the browser. When the frontend SDK is initialized, it will automatically pick up the tracing information from the `<meta>` tags and continue the trace. Note, that your browser SDK needs to register `browserTracingIntegration` for this to work.
215-
216-
The easiest and recommended way to do this is to use the `Sentry.getTraceMetaTags()`:
217-
218-
```javascript {5} {filename:index.js}
219-
function renderHtml() {
220-
return `
221-
<html>
222-
<head>
223-
${Sentry.getTraceMetaTags()}
224-
</head>
225-
<body>
226-
<!-- Your HTML content -->
227-
</body>
228-
</html>
229-
`;
230-
}
231-
```
232-
233-
Alternatively, if you need more control over how meta tags are generated, you can use `Sentry.getTraceData()` to get only the meta tag values and generate the meta tags yourself:
234-
235-
```javascript {2, 7-8} {filename:index.js}
236-
function renderHtml() {
237-
const metaTagValues = Sentry.getTraceData();
238-
239-
return `
240-
<html>
241-
<head>
242-
<meta name="sentry-trace" content="${metaTagValues["sentry-trace"]}">
243-
<meta name="baggage" content="${metaTagValues.baggage}">
244-
</head>
245-
<body>
246-
<!-- Your HTML content -->
247-
</body>
248-
</html>
249-
`;
250-
}
251-
```
252-
253-
</PlatformCategorySection>
254-
25541
### Starting a New Trace
25642

25743
Available since SDK version `8.5.0`.

0 commit comments

Comments
 (0)