diff --git a/src/docs/contributing/approach/sdk-docs/write-performance.mdx b/src/docs/contributing/approach/sdk-docs/write-performance.mdx index 13a24656af5f2..87fcae3d3fd39 100644 --- a/src/docs/contributing/approach/sdk-docs/write-performance.mdx +++ b/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 ``, 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 `` 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. diff --git a/src/platform-includes/distributed-tracing/TODO-INTEGRATE-instrumentation/automatic-instrumentation-configuration/javascript.mdx b/src/platform-includes/distributed-tracing/TODO-INTEGRATE-instrumentation/automatic-instrumentation-configuration/javascript.mdx new file mode 100644 index 0000000000000..ceef6c2cd435e --- /dev/null +++ b/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 Tracing Options docs for more information about the `trace_propagation_targets` option. diff --git a/src/platform-includes/distributed-tracing/TODO-INTEGRATE-instrumentation/automatic-instrumentation-configuration/python.mdx b/src/platform-includes/distributed-tracing/TODO-INTEGRATE-instrumentation/automatic-instrumentation-configuration/python.mdx new file mode 100644 index 0000000000000..98a5559bf7260 --- /dev/null +++ b/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 Tracing Options docs for more information about the `trace_propagation_targets` option. diff --git a/src/platform-includes/distributed-tracing/TODO-INTEGRATE-instrumentation/automatic-instrumentation-intro/_default.mdx b/src/platform-includes/distributed-tracing/TODO-INTEGRATE-instrumentation/automatic-instrumentation-intro/_default.mdx new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/src/platform-includes/distributed-tracing/TODO-INTEGRATE-instrumentation/automatic-instrumentation-intro/javascript.mdx b/src/platform-includes/distributed-tracing/TODO-INTEGRATE-instrumentation/automatic-instrumentation-intro/javascript.mdx new file mode 100644 index 0000000000000..f926753b078f8 --- /dev/null +++ b/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 Automatic Instrumentation 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. diff --git a/src/platform-includes/distributed-tracing/TODO-INTEGRATE-set-up-distributed-tracing-configuration/javascript.mdx b/src/platform-includes/distributed-tracing/TODO-INTEGRATE-set-up-distributed-tracing-configuration/javascript.mdx new file mode 100644 index 0000000000000..2d5c91cbd9694 --- /dev/null +++ b/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 Automatic Instrumentation 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 Set Up Performance for more information on how to configure tracing. + +Additionally, if your backend is hosted on a different domain, you may need to Configure Backend CORS Headers to ensure requests aren't blocked. diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/javascript.mdx new file mode 100644 index 0000000000000..36ef0611ee4fe --- /dev/null +++ b/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 performance monitoring feature 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 Automatic Instrumentation 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 Automatic Instrumentation. 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 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. + +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. diff --git a/src/platform-includes/distributed-tracing/custom-instrumentation/python.mdx b/src/platform-includes/distributed-tracing/custom-instrumentation/python.mdx new file mode 100644 index 0000000000000..c62574157a0ea --- /dev/null +++ b/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 performance monitoring feature 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 += '' % sentry_sdk.get_traceparent() +meta += '' % sentry_sdk.get_baggage() + +html = """ + + + + + {additional_meta} + + +

This is a website.

+ + +""".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. diff --git a/src/platform-includes/distributed-tracing/how-to-use/_default.mdx b/src/platform-includes/distributed-tracing/how-to-use/_default.mdx new file mode 100644 index 0000000000000..90cfad426f4ab --- /dev/null +++ b/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 activate performance monitoring. diff --git a/src/platform-includes/distributed-tracing/how-to-use/python.bottle.mdx b/src/platform-includes/distributed-tracing/how-to-use/python.bottle.mdx new file mode 100644 index 0000000000000..22488c7e4f9b9 --- /dev/null +++ b/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 performance monitoring feature enabled for distributed tracing to work. diff --git a/src/platform-includes/distributed-tracing/how-to-use/python.django.mdx b/src/platform-includes/distributed-tracing/how-to-use/python.django.mdx new file mode 100644 index 0000000000000..22488c7e4f9b9 --- /dev/null +++ b/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 performance monitoring feature enabled for distributed tracing to work. diff --git a/src/platform-includes/distributed-tracing/how-to-use/python.falcon.mdx b/src/platform-includes/distributed-tracing/how-to-use/python.falcon.mdx new file mode 100644 index 0000000000000..22488c7e4f9b9 --- /dev/null +++ b/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 performance monitoring feature enabled for distributed tracing to work. diff --git a/src/platform-includes/distributed-tracing/how-to-use/python.fastapi.mdx b/src/platform-includes/distributed-tracing/how-to-use/python.fastapi.mdx new file mode 100644 index 0000000000000..22488c7e4f9b9 --- /dev/null +++ b/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 performance monitoring feature enabled for distributed tracing to work. diff --git a/src/platform-includes/distributed-tracing/how-to-use/python.flask.mdx b/src/platform-includes/distributed-tracing/how-to-use/python.flask.mdx new file mode 100644 index 0000000000000..22488c7e4f9b9 --- /dev/null +++ b/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 performance monitoring feature enabled for distributed tracing to work. diff --git a/src/platform-includes/distributed-tracing/how-to-use/python.mdx b/src/platform-includes/distributed-tracing/how-to-use/python.mdx new file mode 100644 index 0000000000000..c1b8c12eb653d --- /dev/null +++ b/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 performance monitoring feature enabled for distributed tracing to work. However, if you do not want to activate performance monitoring, you can also setup a custom instrumentation. diff --git a/src/platform-includes/distributed-tracing/how-to-use/python.pyramid.mdx b/src/platform-includes/distributed-tracing/how-to-use/python.pyramid.mdx new file mode 100644 index 0000000000000..22488c7e4f9b9 --- /dev/null +++ b/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 performance monitoring feature enabled for distributed tracing to work. diff --git a/src/platform-includes/distributed-tracing/how-to-use/python.quart.mdx b/src/platform-includes/distributed-tracing/how-to-use/python.quart.mdx new file mode 100644 index 0000000000000..22488c7e4f9b9 --- /dev/null +++ b/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 performance monitoring feature enabled for distributed tracing to work. diff --git a/src/platform-includes/distributed-tracing/how-to-use/python.starlette.mdx b/src/platform-includes/distributed-tracing/how-to-use/python.starlette.mdx new file mode 100644 index 0000000000000..22488c7e4f9b9 --- /dev/null +++ b/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 performance monitoring feature enabled for distributed tracing to work. diff --git a/src/platform-includes/distributed-tracing/how-to-use/python.tornado.mdx b/src/platform-includes/distributed-tracing/how-to-use/python.tornado.mdx new file mode 100644 index 0000000000000..22488c7e4f9b9 --- /dev/null +++ b/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 performance monitoring feature enabled for distributed tracing to work. diff --git a/src/platform-includes/distributed-tracing/limiting-traces/python.mdx b/src/platform-includes/distributed-tracing/limiting-traces/python.mdx new file mode 100644 index 0000000000000..63e189d10cd0e --- /dev/null +++ b/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/.*", + ], + # ... +) +``` diff --git a/src/platform-includes/enriching-events/breadcrumbs/automatic-breadcrumbs/_default.mdx b/src/platform-includes/enriching-events/breadcrumbs/automatic-breadcrumbs/_default.mdx index 5229f673ae58f..9987ddb874f89 100644 --- a/src/platform-includes/enriching-events/breadcrumbs/automatic-breadcrumbs/_default.mdx +++ b/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. diff --git a/src/platform-includes/getting-started-primer/python.flask.mdx b/src/platform-includes/getting-started-primer/python.flask.mdx index 356444610e2fb..30ef372a0bd42 100644 --- a/src/platform-includes/getting-started-primer/python.flask.mdx +++ b/src/platform-includes/getting-started-primer/python.flask.mdx @@ -1,7 +1,5 @@ -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. diff --git a/src/platform-includes/performance/connect-services/javascript.mdx b/src/platform-includes/performance/connect-services/javascript.mdx index eefc93ca7e398..2b40b0a37000d 100644 --- a/src/platform-includes/performance/connect-services/javascript.mdx +++ b/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 -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 BrowserTracing 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 tracePropagationTargets list. `tracePropagationTargets` was previously called `tracingOrigins`. diff --git a/src/platforms/apple/common/configuration/swizzling.mdx b/src/platforms/apple/common/configuration/swizzling.mdx index 3dba02bb11afd..a465c38cf777b 100644 --- a/src/platforms/apple/common/configuration/swizzling.mdx +++ b/src/platforms/apple/common/configuration/swizzling.mdx @@ -20,7 +20,7 @@ The Cocoa SDK uses [swizzling](https://nshipster.com/method-swizzling/) to provi - Auto instrumentation for Core Data operations -- +- Automatically added sentry-trace header to HTTP requests for distributed tracing @@ -47,7 +47,7 @@ The Cocoa SDK uses [swizzling](https://nshipster.com/method-swizzling/) to provi - Auto instrumentation for Core Data operations -- +- Automatically added sentry-trace header to HTTP requests for distributed tracing diff --git a/src/platforms/common/configuration/sampling.mdx b/src/platforms/common/configuration/sampling.mdx index abf82b268cee9..11ea131701628 100644 --- a/src/platforms/common/configuration/sampling.mdx +++ b/src/platforms/common/configuration/sampling.mdx @@ -111,13 +111,13 @@ Whatever a transaction's sampling decision, that decision will be passed to its -(See Connecting Services for more about how that propagation is done.) +(See Distributed Tracing for more about how that propagation is done.) -(See [Connecting Services](/platforms/php/guides/laravel/performance/connect-services/) for more about how that propagation is done.) +(See Distributed Tracing for more about how that propagation is done.) diff --git a/src/platforms/common/performance/connect-services.mdx b/src/platforms/common/performance/connect-services.mdx deleted file mode 100644 index 1df6f7f0127df..0000000000000 --- a/src/platforms/common/performance/connect-services.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Connect Services -sidebar_order: 40 -description: "Learn how to connect backend and frontend transactions." -notSupported: - - php ---- - -When tracing is enabled, the SDK will attach an outgoing header called `sentry-trace` to requests. This depends on the out of the box integrations we provide, but you can expect the header `sentry-trace` to be present. If it's not, you can manually add `sentry-trace` headers to any requests by learning more about [its structure](https://develop.sentry.dev/sdk/performance/#header-sentry-trace). - -SDKs with performance monitoring support listen to incoming requests and typically automatically pick up the incoming `sentry-trace` header to continue the trace (with the same `trace-id`) from there, connecting backend and frontend transactions into a single coherent trace using the `trace_id` value. Depending on the circumstance, this ID is transmitted either in a request header or in an HTML `` tag. - -All your transactions that have the same `trace-id` are connected. Linking transactions in this way makes it possible to navigate among them in [sentry.io](https://sentry.io) to better understand how the different parts of your system are affecting one another. You can learn more about this model in our [Distributed Tracing](/product/sentry-basics/tracing/distributed-tracing/) docs. - - - -If the instrumentation you're using doesn't automatically pick up the `sentry-trace` header, you can also continue a trace manually by using the `continueFromHeaders` function on a `Transaction`. Learn more about this in our [Transaction Interface](https://develop.sentry.dev/sdk/performance/#new-span-and-transaction-classes) documentation. - - - - - - - - diff --git a/src/platforms/common/performance/index.mdx b/src/platforms/common/performance/index.mdx index cca81dc4a6fec..7cdaca8a6b59a 100644 --- a/src/platforms/common/performance/index.mdx +++ b/src/platforms/common/performance/index.mdx @@ -102,21 +102,6 @@ If you leave your sample rate at `1.0`, a transaction will be sent every time a - - - - -## Connecting Services - -If you are also using Performance Monitoring for [JavaScript](/platforms/javascript/performance/), depending on where your request originates, you can connect traces: - -1. For requests that start in your backend, by [adding a meta tag](/platforms/javascript/performance/connect-services/#pageload) in your HTML template that contains tracing information. -2. For requests that start in JavaScript, by the SDK [setting a header](/platforms/javascript/performance/connect-services/#navigation-and-other-xhr-requests) on requests to your backend. - -Otherwise, backend services with Performance Monitoring connect automatically. - - - `@sentry/react` exports a `withProfiler` higher order component that can be used to capture React related spans for specific React components. diff --git a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx index 7a1c6c42564a4..335f78d6b0c46 100644 --- a/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx +++ b/src/platforms/common/performance/instrumentation/custom-instrumentation.mdx @@ -76,13 +76,3 @@ To instrument certain regions of your code, you can create transactions to captu - - - -## Distributed Tracing - -Traces can bridge across multiple software services. Each span in a trace can be represented as a `sentry-trace` header, containing the trace id, span id, and sampling details. This `sentry-trace` header can be passed to downstream services so that they can create spans that are a continuation of the trace started in the originating service. - - - - diff --git a/src/platforms/common/usage/distributed-tracing/custom-instrumentation.mdx b/src/platforms/common/usage/distributed-tracing/custom-instrumentation.mdx new file mode 100644 index 0000000000000..9c436537f8bec --- /dev/null +++ b/src/platforms/common/usage/distributed-tracing/custom-instrumentation.mdx @@ -0,0 +1,9 @@ +--- +title: Custom Instrumentation +sidebar_order: 40 +description: "" +supported: + - python +--- + + diff --git a/src/platforms/common/usage/distributed-tracing/dealing-with-cors-issues.mdx b/src/platforms/common/usage/distributed-tracing/dealing-with-cors-issues.mdx new file mode 100644 index 0000000000000..42748ffe2b150 --- /dev/null +++ b/src/platforms/common/usage/distributed-tracing/dealing-with-cors-issues.mdx @@ -0,0 +1,11 @@ +--- +title: Dealing with CORS Issues +sidebar_order: 80 +description: "" +--- + +If your backend is hosted on a different domain than your frontend, for example, your frontend on is `https://example.com` and your backend is on `https://api.example.com`, and the frontend does XHR/fetch requests to your backend, you'll need to configure your backend [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) headers to ensure requests aren't blocked. + +Configure your backend CORS to allow the `sentry-trace` and `baggage` headers. + +Your server's response header configuration might look like: `"Access-Control-Allow-Headers: sentry-trace, baggage"`. Your configuration will be specific to your setup. diff --git a/src/platforms/common/usage/distributed-tracing/distributed-trace-in-sentry.png b/src/platforms/common/usage/distributed-tracing/distributed-trace-in-sentry.png new file mode 100644 index 0000000000000..e46ea6d5c0d46 Binary files /dev/null and b/src/platforms/common/usage/distributed-tracing/distributed-trace-in-sentry.png differ diff --git a/src/platforms/common/usage/distributed-tracing/index.mdx b/src/platforms/common/usage/distributed-tracing/index.mdx new file mode 100644 index 0000000000000..b0427abcc4fb0 --- /dev/null +++ b/src/platforms/common/usage/distributed-tracing/index.mdx @@ -0,0 +1,39 @@ +--- +title: Distributed Tracing +sidebar_order: 40 +description: "Learn how to connect events across applications/services." +notSupported: + - elixir + - javascript.cordova + - kotlin-multiplatform + - unreal +--- + +If the overall application landscape that want to observe with Sentry consists of more than just a single service or application, you might be interested in distributed tracing and what it can do for you. + +## What is Distributed Tracing? + +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. This can mean a lot of things, for example that your system is spread across different servers, or simply that your application is split into different backend and frontend services, each potentially having their own technology stack. + +When an error or performance issue occurs, it can be challenging to pinpoint the root cause due to the complexity of 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. + +## Basic Example + +Here's an example showing a distributed trace in Sentry: + +![A full distributed trace in Sentry](distributed-trace-in-sentry.png) + +This distributed trace shows a Vue app's `pageload` making a request to a Python backend, which then calls the `/api` endpoint of a Ruby microservice. + +What happens in the background is that Sentry uses reads and further propagates two HTTP headers between your applications: + +- `sentry-trace` +- `baggage` + +When you also run JavaScript applications in your distributed system, you have to make sure that those two headers are added to your CORS allowlist and won't be blocked or stripped by your proxy servers, gateways, or firewalls. + +## How to Use Distributed Tracing? + + + +But remember, in order to propagate trace information through your whole distributed system, you have to use Sentry in all of the involved services and applications. Take a look at the respective SDK documentation, to find out how distributed tracing can be enabled for each of them. diff --git a/src/platforms/common/usage/distributed-tracing/limiting-trace-propagation.mdx b/src/platforms/common/usage/distributed-tracing/limiting-trace-propagation.mdx new file mode 100644 index 0000000000000..8705bd17b5d3a --- /dev/null +++ b/src/platforms/common/usage/distributed-tracing/limiting-trace-propagation.mdx @@ -0,0 +1,15 @@ +--- +title: Limiting Trace Propagation +sidebar_order: 100 +description: "" +supported: + - python +--- + +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: + + + +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 our config options documentation for more information about the `trace_propagation_targets` option. diff --git a/src/platforms/node/guides/express/performance/index.mdx b/src/platforms/node/guides/express/performance/index.mdx index 875865aee4f58..0472c02b297f8 100644 --- a/src/platforms/node/guides/express/performance/index.mdx +++ b/src/platforms/node/guides/express/performance/index.mdx @@ -128,12 +128,3 @@ app.get("/success", function successHandler(req, res) { res.status(200).end(); }); ``` - -## Connecting Services - -If you are also using Performance Monitoring for [JavaScript](/platforms/javascript/performance/), depending on where your request originates, you can connect traces: - -1. For requests that start in your backend, by [adding a meta tag](/platforms/javascript/performance/connect-services/#pageload) in your HTML template that contains tracing information. -2. For requests that start in JavaScript, by the SDK [setting a header](/platforms/javascript/performance/connect-services/#navigation-and-other-xhr-requests) on requests to your backend. - -Otherwise, backend services with Performance Monitoring connect automatically. diff --git a/src/platforms/php/guides/laravel/performance/connect-services.mdx b/src/platforms/php/guides/laravel/performance/distributed-tracing.mdx similarity index 81% rename from src/platforms/php/guides/laravel/performance/connect-services.mdx rename to src/platforms/php/guides/laravel/performance/distributed-tracing.mdx index eb120128ff482..dbfc0b00756ff 100644 --- a/src/platforms/php/guides/laravel/performance/connect-services.mdx +++ b/src/platforms/php/guides/laravel/performance/distributed-tracing.mdx @@ -1,10 +1,10 @@ --- -title: Connect Services +title: Distributed Tracing sidebar_order: 40 description: "Learn how to connect backend and frontend transactions." --- -If you're also using Performance Monitoring for [JavaScript](/platforms/javascript/performance/), you can use a helper function to continue the trace and propagate the trace context started from your backend in order to [connect services](/platforms/javascript/performance/connect-services/#navigation-and-other-xhr-requests). (The trace context contains additional trace-related data that is used for trace-based sampling.) +If you're also using Performance Monitoring for [JavaScript](/platforms/javascript/performance/), you can use a helper function to continue the trace and propagate the trace context started from your backend in order to enable [Distributed Tracing](/platforms/javascript/usage/distributed-tracing/). (The trace context contains additional trace-related data that is used for trace-based sampling.) Add the following line to your blade template rendering the `` of your page: ```php {filename:app.blade.php} diff --git a/src/platforms/php/guides/symfony/profiling/index.mdx b/src/platforms/php/guides/symfony/profiling/index.mdx index d48884cd8a45e..c58b59dbc22ce 100644 --- a/src/platforms/php/guides/symfony/profiling/index.mdx +++ b/src/platforms/php/guides/symfony/profiling/index.mdx @@ -100,4 +100,4 @@ If you don't see any profiling data in [sentry.io](https://sentry.io), you can t - Ensure that performance monitoring is enabled. - Ensure that the automatic instrumentation is sending performance data to Sentry by going to the **Performance** page in [sentry.io](https://sentry.io). -- If the automatic instrumentation is not sending performance data, try using custom instrumentation. +- If the automatic instrumentation is not sending performance data, try using custom instrumentation. diff --git a/vercel.json b/vercel.json index 30fb6295137e9..721e2b8e334a0 100644 --- a/vercel.json +++ b/vercel.json @@ -495,6 +495,14 @@ { "source": "/platforms/([^/]*)/guides/([^/]*)/crons/troubleshooting-crons/", "destination": "/platforms/$1/guides/$2/crons/troubleshooting/" + }, + { + "source": "/platforms/([^/]*)/performance/connect-services/", + "destination": "/platforms/$1/usage/distributed-tracing/" + }, + { + "source": "/platforms/([^/]*)/guides/([^/]*)/performance/connect-services/", + "destination": "/platforms/$1/guides/$2/usage/distributed-tracing/" } ] }