Tracing without performance documentation (#7176)

Add documentation for the built-in distributed tracing support (without the need to turn on performance monitoring). Merge docs with existing docs on "Performance Monitoring > Connecting Services".

Author: stephanie-anderson

src/docs/contributing/approach/sdk-docs/write-performance.mdx

@@ -66,8 +66,6 @@ If any of the above files are not applicable to your platform, find the `<Platfo
 
 Then, determine whether to provide a code sample illustrating how to connect errors and spans. If so, add the SDK to the `Supported` list in the appropriate `<PlatformSection>`, then add a code sample `/src/platform-includes/performance/connect-errors-spans/`.
 
-If the platform supports distributed tracing using custom instrumentation, add the SDK to the appropriate `<PlatformSection>` and create an appropriate file at `src/platform-includes/performance/distributed-tracing`.
-
 ### Automatic Instrumentation
 
 This page does not use common content. It covers what instrumentation is automatic when tracing is enabled for this SDK.
@@ -82,10 +80,6 @@ This file is `troubleshooting-performance.mdx`. It explains corner cases and how
 
 2. Add an example to `src/platform-includes/performance/control-data-truncation/`
 
-### Connecting Services
-
-This page does not currently use common content. It covers an example of how to connect frontend and backend services. In future, we may determine that it's useful to expand the content beyond the JS-specific focus.
-
 ### Sampling
 
 Guidelines TBD.

src/platform-includes/distributed-tracing/TODO-INTEGRATE-instrumentation/automatic-instrumentation-configuration/javascript.mdx

@@ -0,0 +1,20 @@
+## Configuration
+
+By default, trace information (`sentry-trace` and `baggage` headers) will be added to outgoing XHR/fetch requests that contain `localhost` in their URL and requests where the URL starts with `'/'`, for example, `/api/v1/users`.
+
+To configure which URLs have trace information added, set the `tracePropagationTargets` option:
+
+```javascript
+Sentry.init({
+  // ...
+  integrations: [
+    new Sentry.BrowserTracing({
+      tracePropagationTargets: ["localhost", /^https:\/\/api\.example\.com/],
+    }),
+  ],
+});
+```
+
+In this example, trace information will be added to outgoing XHR/fetch requests to `localhost` and URLs starting with `https://api.example.com`.
+
+See <PlatformLink to="/configuration/options/#trace-propagation-targets">Tracing Options</PlatformLink> docs for more information about the `trace_propagation_targets` option.

src/platform-includes/distributed-tracing/TODO-INTEGRATE-instrumentation/automatic-instrumentation-configuration/python.mdx

@@ -0,0 +1,20 @@
+## Configuration
+
+By default, trace information (`sentry-trace` and `baggage` headers) will be added to all outgoing HTTP requests. If you want to limit to the URLs where trace information is added, you can specify a `trace_propagation_targets` option:
+
+```python
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn="___PUBLIC_DSN___",
+    trace_propagation_targets=[
+        "https://myproject.org",
+        r"https://.*\.otherservice.org/.*",
+    ],
+    # ...
+)
+```
+
+In the example above, trace information will be added to all requests to URLs that contain `"https://myproject.org"` and to all URLs of all sub domains of `otherservice.org` like `https://api.otherservice.org/something/` or `https://payment.otherservice.org/something/`.
+
+See <PlatformLink to="/configuration/options/#trace-propagation-targets">Tracing Options</PlatformLink> docs for more information about the `trace_propagation_targets` option.

src/platform-includes/distributed-tracing/TODO-INTEGRATE-instrumentation/automatic-instrumentation-intro/_default.mdx

@@ -0,0 +1,5 @@
+To enable distributed tracing, add the `BrowserTracing` integration to your `Sentry.init` options, as described in the Performance <PlatformLink to="/performance/instrumentation/automatic-instrumentation/"> Automatic Instrumentation</PlatformLink> docs. The [Next.js](/platforms/javascript/guides/nextjs/) and [SvelteKit](/platforms/javascript/guides/sveltekit/) SDKs include this integration by default.
+
+Tracing information sent from the backend via the `sentry-tracing` and `baggage` HTML `meta` tags will be extracted and stored in a transaction that is created at page load.
+
+The `sentry-trace` and `baggage` headers will be added to all your outgoing XHR/fetch requests.

src/platform-includes/distributed-tracing/TODO-INTEGRATE-instrumentation/automatic-instrumentation-intro/javascript.mdx

@@ -0,0 +1,7 @@
+## Configuration
+
+To enable distributed tracing, add the `BrowserTracing` integration to your `Sentry.init` options, as described in the Performance <PlatformLink to="/performance/instrumentation/automatic-instrumentation/">Automatic Instrumentation</PlatformLink> docs. Sentry's [Next.js](/platforms/javascript/guides/nextjs/) and [SvelteKit](/platforms/javascript/guides/sveltekit/) SDKs include this integration by default.
+
+See the instructions at <PlatformLink to="/platforms/javascript/performance/">Set Up Performance</PlatformLink> for more information on how to configure tracing.
+
+Additionally, if your backend is hosted on a different domain, you may need to <PlatformLink to="/distributed-tracing/instrumentation/automatic-instrumentation/#configure-backend-cors-headers">Configure Backend CORS Headers</PlatformLink> to ensure requests aren't blocked.

src/platform-includes/distributed-tracing/TODO-INTEGRATE-set-up-distributed-tracing-configuration/javascript.mdx

@@ -0,0 +1,84 @@
+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 <PlatformLink to="/performance/">performance monitoring feature</PlatformLink> turned on.
+
+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.
+
+To enable distributed tracing, add the `BrowserTracing` integration to your `Sentry.init` options, as described in the Performance <PlatformLink to="/performance/instrumentation/automatic-instrumentation/"> Automatic Instrumentation</PlatformLink> docs. The [Next.js](/platforms/javascript/guides/nextjs/) and [SvelteKit](/platforms/javascript/guides/sveltekit/) SDKs include this integration by default.
+
+If you are using one of the frameworks listed above, see the <PlatformLink to="/distributed-tracing/instrumentation/automatic-instrumentation/">Automatic Instrumentation</PlatformLink>. page on how to configure distributed tracing.
+
+If you prefer to implement custom distributed tracing, 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 <PlatformLink to="/distributed-tracing/">Distributed Tracing</PlatformLink> 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.
+
+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.
+
+For example, on `pageload` you could 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);
+```
+
+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
+
+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.
+
+Here's an example of how to collect and inject this tracing information to outgoing requests:
+
+```javascript
+// Create `sentry-trace` header
+const sentryTraceHeader = pageLoadTransaction.toTraceparent();
+
+// Create `baggage` header
+const dynamicSamplingContext = pageLoadTransaction.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.

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

@@ -0,0 +1,84 @@
+On this page you will learn how to manually propagate trace information into and out of your Python application. Please note, that you do not need to do this manually, if you [use one of our supported frameworks](/platforms/python/usage/distributed-tracing/#how-to-use-distributed-tracing), or you have our <PlatformLink to="/performance/">performance monitoring feature</PlatformLink> turned on.
+
+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.
+
+## Step 1) Extract Incoming Tracing Information
+
+Incoming tracing information has to be extracted and stored in memory for later use. Sentry provides the `continue_trace()` function to help you with this. Incoming tracing information can come from different places:
+
+- In a web environment it will be sent with HTTP headers, for example, by another Sentry SDK used in your frontend project.
+- In a job queue, like Celery, 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 `continue_trace()`:
+
+```python
+import sentry_sdk
+from my_project import get_incoming_headers_as_dict
+
+headers = get_incoming_headers_as_dict()
+
+sentry_sdk.continue_trace(headers)
+```
+
+In this example, `get_incoming_headers_as_dict()` returns a dictionary that contains tracing information from HTTP headers, environment variables, or any other mechanism your project uses to communicate with the outside world.
+
+Sentry's `continue_trace()` function will extract the given headers, try to find the `sentry-trace` and `baggage` headers, and store them in memory for later use.
+
+## Step 2) Inject Tracing Information to Outgoing Requests
+
+For distributed tracing to work, the two headers `sentry-trace` and `baggage`, must now also be added to outgoing requests. If you pregenerate HTML on the server-side, you might want to take a look at option 2 as well, which describes how to pass on tracing information through HTML meta tags.
+
+### Inject Tracing Information Into HTTP Requests
+
+If you are sending outgoing HTTP requests with [Requests](https://requests.readthedocs.io/en/latest/), [AIOHTTP](https://docs.aiohttp.org/en/stable/), the low level [http.client](https://docs.python.org/3/library/http.client.html), or [httplib](https://docs.python.org/2/library/httplib.html) on Python 2, this tracing information is automatically added to outgoing requests.
+
+If your using none of the above, you can generate this tracing information with the Sentry SDK's `get_traceparent()` and `get_baggage()` functions. Here's an example:
+
+```python
+import sentry_sdk
+from my_project import make_an_outgoing_request
+
+headers = {}
+headers["sentry-trace"] = sentry_sdk.get_traceparent()
+headers["baggage"] = sentry_sdk.get_baggage()
+
+make_an_outgoing_request(to="https://example.com", headers=headers)
+```
+
+In this example, tracing information is propagated to the project running at `https://example.com`. If this project uses the Sentry Python SDK, it will extract and save the tracing information for later use.
+
+The two services are now connected with your custom distributed tracing implementation.
+
+### Inject Tracing Information Into Rendered HTML
+
+To propagate tracing information into JavaScript running in rendered HTML you have to inject HTML `meta` tags for `sentry-trace` and `baggage` data into your rendered HTML. Here's an example:
+
+```python
+import sentry_sdk
+from my_project import render
+
+meta = ""
+meta += '<meta name="sentry-trace" content="%s">' % sentry_sdk.get_traceparent()
+meta += '<meta name="baggage" content="%s">' % sentry_sdk.get_baggage()
+
+html = """
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="UTF-8">
+        {additional_meta}
+    </head>
+    <body>
+        <p>This is a website.</p>
+    </body>
+</html>
+""".format(additional_meta=meta)
+
+render(html)
+
+```
+
+## 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.

src/platform-includes/distributed-tracing/custom-instrumentation/python.mdx

@@ -0,0 +1 @@
+In order to use distributed tracing with this SDK, you have to <PlatformLink to="/performance/">activate performance monitoring</PlatformLink>.

src/platform-includes/distributed-tracing/how-to-use/_default.mdx

@@ -0,0 +1,3 @@
+If you use the current version of our Python SDK, distributed tracing just works out of the box. No additional configuration is required.
+
+If you however use version `1.25.x` or below, you need to have our <PlatformLink to="/performance/">performance monitoring feature enabled</PlatformLink> for distributed tracing to work.