/sentry-dotnet-sdk

Profiling — Sentry .NET SDK

Alpha feature — Sentry.Profiling NuGet package
Minimum SDK: Sentry.Profiling ≥ 4.0.0 · .NET 8.0+ required
Not supported: .NET Framework, Android, Blazor WASM, Native AOT (except iOS/Mac Catalyst)

Overview

The Sentry .NET SDK captures CPU profiles using the .NET EventPipe (System.Diagnostics.DiagnosticSource) sampling infrastructure. Profiles attach to transactions — they are not standalone events.

How Profiling Attaches to Traces

Profiles are always tied to a transaction — you must have tracing enabled first:

TracesSampleRate × ProfilesSampleRate = net profiling rate

Example:
  TracesSampleRate   = 0.5  →  50% of requests create transactions
  ProfilesSampleRate = 0.4  →  40% of those transactions get profiled
  Net profiling rate        =  20% of all requests

When a transaction starts:

1. ProfilingIntegration checks whether this transaction should be profiled (per ProfilesSampleRate)
2. If yes, an EventPipe session starts collecting CPU samples (~100 Hz)
3. When transaction.Finish() is called, the profiler stops and attaches the profile data to the transaction envelope
4. Both the transaction and the profile are sent to Sentry together — you can drill from a slow span directly into a flame graph

One profiler at a time: Only one profile can be active per process. Nested transactions will not each receive their own profile.

Installation

dotnet add package Sentry.Profiling

Do NOT install Sentry.Profiling for iOS or Mac Catalyst. Those platforms use the native Mono AOT profiler bundled inside Sentry.Maui — installing this package on those targets has no effect.

Basic Setup

Profiling requires three additions to your SentrySdk.Init call:

SentrySdk.Init(options =>
{
    options.Dsn = "https://examplePublicKey@o0.ingest.sentry.io/0";

    // Step 1: Enable tracing (REQUIRED — profiling won't work without it)
    options.TracesSampleRate = 1.0;

    // Step 2: Set what fraction of sampled transactions get profiled
    options.ProfilesSampleRate = 1.0;  // 1.0 = 100% for development; lower in production

    // Step 3: Register the profiling integration
    options.AddProfilingIntegration();
});

ASP.NET Core

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseSentry(options =>
{
    options.Dsn = "https://examplePublicKey@o0.ingest.sentry.io/0";
    options.TracesSampleRate = 1.0;
    options.ProfilesSampleRate = 0.1;   // Profile 10% of sampled transactions in production
    options.AddProfilingIntegration();
});

var app = builder.Build();
app.UseSentry();  // Must appear before other middleware
app.MapControllers();
app.Run();

Synchronous Startup (Recommended for Most Apps)

AddProfilingIntegration() initializes the EventPipe session asynchronously on a background thread. Transactions that start immediately after SentrySdk.Init() may not get a profile because the profiler isn't ready yet.

// ❌ Problem: profiler may not be ready when first transaction starts
SentrySdk.Init(options => {
    options.AddProfilingIntegration();  // async startup
});
var tx = SentrySdk.StartTransaction("startup", "init");  // profiler might miss this

// ✅ Fix: provide a timeout to block until profiler is ready
SentrySdk.Init(options => {
    options.AddProfilingIntegration(TimeSpan.FromMilliseconds(500));
});
var tx = SentrySdk.StartTransaction("startup", "init");  // profiler guaranteed ready

iOS/Mac Catalyst note: The native Mono profiler always starts synchronously. The TimeSpan parameter is accepted but has no effect on those platforms.

Configuration Options

Recommended Production Settings

SentrySdk.Init(options =>
{
    options.Dsn = "...";

    // Sample 20% of transactions
    options.TracesSampleRate = 0.2;

    // Profile 50% of those — net 10% of all requests get profiled
    options.ProfilesSampleRate = 0.5;

    // Block up to 500ms so early-startup transactions are captured
    options.AddProfilingIntegration(TimeSpan.FromMilliseconds(500));
});

Platform-Specific Notes

Linux

⚠️ Known issue (open as of Feb 2026, #4815): AddProfilingIntegration() can throw a ReflectionTypeLoadException on startup in Linux containers. This is caused by Dia2Lib.dll and TraceReloggerLib.dll — Windows-only PDB resolver DLLs that are referenced by the profiler's tracing stack.

Mitigation: Wrap AddProfilingIntegration() in a try/catch and log the failure gracefully:

try
{
    options.AddProfilingIntegration();
}
catch (Exception ex)
{
    Console.Error.WriteLine($"[Sentry] Profiling unavailable on this platform: {ex.Message}");
}

Test profiling thoroughly on your specific Linux image before enabling in production.

iOS / Mac Catalyst

Use the native Mono AOT profiler. No installation needed — it's built into Sentry.Maui.

// iOS: same configuration, but do NOT install Sentry.Profiling
SentrySdk.Init(options =>
{
    options.Dsn = "...";
    options.TracesSampleRate = 1.0;
    options.ProfilesSampleRate = 1.0;
    options.AddProfilingIntegration();  // delegates to native profiler on iOS/Mac Catalyst
});

Windows

Fully supported. Dia2Lib.dll is a Windows-native dependency and loads correctly. No extra steps required.

Limitations and Known Issues

Complete Setup Example

// Program.cs — ASP.NET Core with tracing + profiling

using Sentry;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseSentry(options =>
{
    options.Dsn = "https://examplePublicKey@o0.ingest.sentry.io/0";
    options.Environment = builder.Environment.EnvironmentName;
    options.Release = "my-app@1.2.3";

    // Tracing: sample 10% of requests in production
    options.TracesSampleRate = builder.Environment.IsProduction() ? 0.1 : 1.0;

    // Profiling: profile 50% of sampled transactions
    // Net result: 5% of all production requests are profiled
    options.ProfilesSampleRate = 0.5;

    // Block up to 500ms so early-startup transactions aren't missed
    options.AddProfilingIntegration(TimeSpan.FromMilliseconds(500));
});

var app = builder.Build();
app.UseSentry();
app.MapControllers();
app.Run();

Console / Worker Service

using Sentry;

SentrySdk.Init(options =>
{
    options.Dsn = "https://examplePublicKey@o0.ingest.sentry.io/0";
    options.TracesSampleRate = 1.0;
    options.ProfilesSampleRate = 1.0;
    options.AddProfilingIntegration(TimeSpan.FromMilliseconds(500));
});

// The profiler is ready — this transaction will be profiled
var transaction = SentrySdk.StartTransaction("data-import", "task");
SentrySdk.ConfigureScope(s => s.Transaction = transaction);

// ... your work here ...

transaction.Finish(SpanStatus.Ok);
// Profile is bundled with the transaction and sent to Sentry

Troubleshooting