From cec649c20957b8dcda00d87ca715e0bddf675370 Mon Sep 17 00:00:00 2001 From: James Crosswell Date: Thu, 2 Jul 2026 11:43:03 +1200 Subject: [PATCH 1/6] fix(dotnet): clarify ASP.NET trace propagation vs. transactions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The trace-propagation how-to for .NET told ASP.NET (System.Web) users to call `Context.StartOrContinueTrace()` in `Application_BeginRequest`, but that method only continues/propagates the trace and never starts a transaction. Users following this page in place of the getting-started config lost their transactions (getsentry/sentry-dotnet#3888). Document both options: `StartSentryTransaction`/`FinishSentryTransaction` (recommended — continues the trace and creates transactions) and `StartOrContinueTrace` (propagation only), and warn against using both. Co-Authored-By: Claude Opus 4.8 --- .../distributed-tracing/how-to-use/dotnet.mdx | 28 ++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/platform-includes/distributed-tracing/how-to-use/dotnet.mdx b/platform-includes/distributed-tracing/how-to-use/dotnet.mdx index 5837058926b3d..dea70a8a4757e 100644 --- a/platform-includes/distributed-tracing/how-to-use/dotnet.mdx +++ b/platform-includes/distributed-tracing/how-to-use/dotnet.mdx @@ -3,7 +3,27 @@ If you use the current version of our .NET SDK, distributed tracing works automa - ASP.NET Core - Azure Functions Worker -When using ASP.NET you will need to update your `Application_BeginRequest` method: +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. + +### Create transactions and continue the trace (recommended) + +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, so you don't need to call `StartOrContinueTrace` as well. + +```csharp +protected void Application_BeginRequest() +{ + Context.StartSentryTransaction(); +} + +protected void Application_EndRequest() +{ + Context.FinishSentryTransaction(); +} +``` + +### Continue the trace without creating transactions + +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: ```csharp protected void Application_BeginRequest() @@ -11,3 +31,9 @@ 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 it on its own. + + From c95288a6f41e3529f4ddb57aa01bc1aa88c92f1d Mon Sep 17 00:00:00 2001 From: James Crosswell Date: Thu, 2 Jul 2026 11:52:18 +1200 Subject: [PATCH 2/6] Apply suggestion from @jamescrosswell --- platform-includes/distributed-tracing/how-to-use/dotnet.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/distributed-tracing/how-to-use/dotnet.mdx b/platform-includes/distributed-tracing/how-to-use/dotnet.mdx index dea70a8a4757e..1ca0fdd278f44 100644 --- a/platform-includes/distributed-tracing/how-to-use/dotnet.mdx +++ b/platform-includes/distributed-tracing/how-to-use/dotnet.mdx @@ -7,7 +7,7 @@ When using ASP.NET (not ASP.NET Core), you have to hook into the request lifecyc ### Create transactions and continue the trace (recommended) -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, so you don't need to call `StartOrContinueTrace` as well. +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. ```csharp protected void Application_BeginRequest() From e614404064c2f5ae48560e12752419a56ffd6101 Mon Sep 17 00:00:00 2001 From: James Crosswell Date: Thu, 9 Jul 2026 11:31:11 +1200 Subject: [PATCH 3/6] Update platform-includes/distributed-tracing/how-to-use/dotnet.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Stefan Pölz <38893694+Flash0ver@users.noreply.github.com> --- platform-includes/distributed-tracing/how-to-use/dotnet.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/distributed-tracing/how-to-use/dotnet.mdx b/platform-includes/distributed-tracing/how-to-use/dotnet.mdx index 1ca0fdd278f44..74a823e550717 100644 --- a/platform-includes/distributed-tracing/how-to-use/dotnet.mdx +++ b/platform-includes/distributed-tracing/how-to-use/dotnet.mdx @@ -34,6 +34,6 @@ protected void Application_BeginRequest() -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 it on its own. +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. From eb59fcfa229a46ba2ebfbd4b83a2f00d31411354 Mon Sep 17 00:00:00 2001 From: James Crosswell Date: Thu, 9 Jul 2026 11:31:26 +1200 Subject: [PATCH 4/6] Update platform-includes/distributed-tracing/how-to-use/dotnet.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Stefan Pölz <38893694+Flash0ver@users.noreply.github.com> --- platform-includes/distributed-tracing/how-to-use/dotnet.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/distributed-tracing/how-to-use/dotnet.mdx b/platform-includes/distributed-tracing/how-to-use/dotnet.mdx index 74a823e550717..d31c9692fe665 100644 --- a/platform-includes/distributed-tracing/how-to-use/dotnet.mdx +++ b/platform-includes/distributed-tracing/how-to-use/dotnet.mdx @@ -5,7 +5,7 @@ If you use the current version of our .NET SDK, distributed tracing works automa 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. -### Create transactions and continue the trace (recommended) +### Create Transactions and Continue the Trace (Recommended) 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. From 26feee1fc16d7f9d5cab773f17a44561facbbe55 Mon Sep 17 00:00:00 2001 From: James Crosswell Date: Thu, 9 Jul 2026 11:32:31 +1200 Subject: [PATCH 5/6] Apply suggestion from @Flash0ver MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Stefan Pölz <38893694+Flash0ver@users.noreply.github.com> --- platform-includes/distributed-tracing/how-to-use/dotnet.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/distributed-tracing/how-to-use/dotnet.mdx b/platform-includes/distributed-tracing/how-to-use/dotnet.mdx index d31c9692fe665..ab721a260e2e3 100644 --- a/platform-includes/distributed-tracing/how-to-use/dotnet.mdx +++ b/platform-includes/distributed-tracing/how-to-use/dotnet.mdx @@ -21,7 +21,7 @@ protected void Application_EndRequest() } ``` -### Continue the trace without creating transactions +### Continue the Trace Without Creating Transactions 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: From 198b9c379d1fda61d27b66a6342de444c44782e3 Mon Sep 17 00:00:00 2001 From: James Crosswell Date: Thu, 9 Jul 2026 13:00:53 +1200 Subject: [PATCH 6/6] fix(dotnet): scope ASP.NET trace propagation to dotnet.aspnet The Global.asax.cs instructions only apply to ASP.NET (System.Web), but the generic dotnet include rendered them for every dotnet guide (ASP.NET Core, MAUI, etc.). Wrap them in a PlatformSection so they only show on the ASP.NET guide, while keeping the "works automatically" intro general. Co-Authored-By: Claude Opus 4.8 --- platform-includes/distributed-tracing/how-to-use/dotnet.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/platform-includes/distributed-tracing/how-to-use/dotnet.mdx b/platform-includes/distributed-tracing/how-to-use/dotnet.mdx index ab721a260e2e3..f361ae4cfa93f 100644 --- a/platform-includes/distributed-tracing/how-to-use/dotnet.mdx +++ b/platform-includes/distributed-tracing/how-to-use/dotnet.mdx @@ -3,6 +3,8 @@ If you use the current version of our .NET SDK, distributed tracing works automa - 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. ### Create Transactions and Continue the Trace (Recommended) @@ -37,3 +39,5 @@ protected void Application_BeginRequest() 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. + +