Tracing without performance documentation

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/javascript.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-set-up-distributed-tracing-configuration/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/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 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/python.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/how-to-use/_default.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/python.bottle.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.

src/platform-includes/distributed-tracing/how-to-use/python.django.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.

src/platform-includes/distributed-tracing/how-to-use/python.falcon.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.

src/platform-includes/distributed-tracing/how-to-use/python.fastapi.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.

src/platform-includes/distributed-tracing/how-to-use/python.flask.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.

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

@@ -0,0 +1,13 @@
+If you use the current version of our Python SDK, distributed tracing just works out of the box for the following frameworks:
+
+- [Django](/platforms/python/guides/django/usage/distributed-tracing/#how-to-use-distributed-tracing)
+- [FastAPI](/platforms/python/guides/fastapi/usage/distributed-tracing/#how-to-use-distributed-tracing)
+- [Flask](/platforms/python/guides/flask/usage/distributed-tracing/#how-to-use-distributed-tracing)
+- [Bottle](/platforms/python/guides/bottle/usage/distributed-tracing/#how-to-use-distributed-tracing)
+- [Falcon](/platforms/python/guides/falcon/usage/distributed-tracing/#how-to-use-distributed-tracing)
+- [Pyramid](/platforms/python/guides/pyramid/usage/distributed-tracing/#how-to-use-distributed-tracing)
+- [Quart](/platforms/python/guides/quart/usage/distributed-tracing/#how-to-use-distributed-tracing)
+- [Starlette](/platforms/python/guides/starlette/usage/distributed-tracing/#how-to-use-distributed-tracing)
+- [Tornado](/platforms/python/guides/tornado/usage/distributed-tracing/#how-to-use-distributed-tracing)
+
+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. However, if you do not want to activate performance monitoring, you can also setup a <PlatformLink to="/usage/distributed-tracing/custom-instrumentation/">custom instrumentation</PlatformLink>.

src/platform-includes/distributed-tracing/how-to-use/python.pyramid.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.

src/platform-includes/distributed-tracing/how-to-use/python.quart.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.

src/platform-includes/distributed-tracing/how-to-use/python.starlette.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.

src/platform-includes/distributed-tracing/how-to-use/python.tornado.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.

src/platform-includes/distributed-tracing/limiting-traces/python.mdx

@@ -0,0 +1,12 @@
+```python
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn="___PUBLIC_DSN___",
+    trace_propagation_targets=[
+        "https://myproject.org",
+        "https://.*\.otherservice.org/.*",
+    ],
+    # ...
+)
+```

src/platform-includes/enriching-events/breadcrumbs/automatic-breadcrumbs/_default.mdx

@@ -1 +1 @@
-SDKs and their associated integrations will automatically record many types of breadcrumbs. For example, the browser JavaScript SDK will automatically record clicks and key presses on DOM elements, fetch/XHR requests, console API calls, and all location changes.
+SDKs and their associated integrations will automatically record many types of breadcrumbs. For example, the browser JavaScript SDK will automatically record clicks and key presses on DOM elements, XHR/fetch requests, console API calls, and all location changes.

src/platform-includes/getting-started-primer/python.flask.mdx

@@ -1,7 +1,5 @@
 <Note>
 
-Sentry's Flask integration enables automatic reporting of errors and exceptions.
-
 Our Python SDK will install the Flask integration for all of your apps. It hooks into Flask’s signals, not anything on the app object. Each request has a separate scope. Changes to the scope within a view, for example setting a tag, will only apply to events sent as part of the request being handled.
 
 </Note>

src/platform-includes/performance/connect-services/javascript.mdx

@@ -8,7 +8,7 @@ The `baggage` header was added with version 7 of the Sentry Javascript SDK and i
 
 </Note>
 
-All of Sentry's tracing-related integrations (`BrowserTracing`, `Http`, and `Express`), as well as the Next.JS SDK, either generate or pick up and propagate the trace headers automatically, as appropriate, for all transactions and spans that they generate.
+All Sentry JavaScript SDKs support distributed tracing once you add the <PlatformLink to="/performance/instrumentation/automatic-instrumentation/">BrowserTracing</PlatformLink> integration to your `Sentry.init` option. The [Next.js](/platforms/javascript/guides/nextjs/) and [SvelteKit](/platforms/javascript/guides/sveltekit/) SDKs already include this integration by default.
 
 The JavaScript SDK will only attach the trace headers to outgoing HTTP requests for which the destination is a substring or regex match to the <PlatformLink to="/performance/instrumentation/automatic-instrumentation/#tracePropagationTargets">tracePropagationTargets</PlatformLink> list. `tracePropagationTargets` was previously called `tracingOrigins`.