Trace Propagation
Learn how to connect events across applications/services.
If the overall application landscape that you want to observe with Sentry consists of more than just a single service or application, distributed tracing can add a lot of value.
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.
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.
Here's an example showing a distributed trace in Sentry:
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-tracebaggage
If you run any JavaScript applications in your distributed system, 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.
If you use the current version of our .NET SDK, distributed tracing works automatically with the following frameworks:
- ASP.NET Core
- Azure Functions Worker
When using ASP.NET (not ASP.NET Core), you have to hook into the request lifecycle in Global.asax.cs to propagate traces. There are two options, depending on whether you want this application to create its own transactions and spans.
In most cases you'll want your ASP.NET application to show up in your distributed traces with its own transactions and spans. Use StartSentryTransaction in Application_BeginRequest and FinishSentryTransaction in Application_EndRequest. StartSentryTransaction continues any incoming trace and creates a transaction for the request.
protected void Application_BeginRequest()
{
Context.StartSentryTransaction();
}
protected void Application_EndRequest()
{
Context.FinishSentryTransaction();
}
protected void Application_BeginRequest()
{
Context.StartSentryTransaction();
}
protected void Application_EndRequest()
{
Context.FinishSentryTransaction();
}
If you only want to propagate an incoming trace to downstream services (for example, a database or another API) without your ASP.NET application creating any transactions or spans of its own, use StartOrContinueTrace instead:
protected void Application_BeginRequest()
{
Context.StartOrContinueTrace();
}
protected void Application_BeginRequest()
{
Context.StartOrContinueTrace();
}
Use either StartSentryTransaction or StartOrContinueTrace, not both. StartOrContinueTrace only propagates the trace and does not create a transaction, so if you replace StartSentryTransaction with it, your ASP.NET application will stop sending transactions to Sentry. Since StartSentryTransaction already continues the incoming trace, most applications should use that method.
Remember that 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 learn how distributed tracing can be enabled for each platform.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").