Sentry SDK for .NET
Integrations | Downloads | NuGet Stable | NuGet Preview |
---|---|---|---|
Sentry | |||
Sentry.Extensions.Logging | |||
Sentry.AspNetCore | |||
Sentry.Serilog | |||
Sentry.Log4Net | |||
Sentry.NLog | |||
Sentry.Protocol |
Documentation
Below you will find a basic introduction to the SDK and its API.
For more details, please: refer to the SDK or API Documentation. Looking for samples using the NuGet packages? Check out sentry-dotnet-samples repository.
Usage
Consider taking a look at the samples directory for different types of apps and example usages of the SDK.
This SDK provides integrations which can hook into your app and automatically capture errors and context.
Basic usage without framework integration
You can still use the SDK directly to send events to Sentry.
The integrations are just wrappers around the main SDK Sentry
.
There's a basic sample and a one demonstrating more customization.
Install the main SDK:
dotnet add package Sentry
Initialize the SDK:
void Main()
{
using (SentrySdk.Init("dsn"))
{
// App code
}
}
The SDK by default will watch for unhandled exceptions in your app.
If the DSN is not explicitly passed by parameter to Init
, the SDK will try to locate it via environment variable SENTRY_DSN
.
To configure advanced settings, for example a proxy server:
void Main()
{
using (SentrySdk.Init(o =>
{
o.Dsn = new Dsn("dsn");
o.Proxy = new WebProxy("https://localhost:3128");
}))
{
// App code
}
}
Capture an exception:
try
{
throw null;
}
catch (Exception e)
{
SentrySdk.CaptureException(e);
}
ASP.NET Core integration
To use Sentry with your ASP.NET Core project, simply install the NuGet package:
dotnet add package Sentry.AspNetCore
Change your Program.cs
by adding UseSentry
:
public static IWebHost BuildWebHost(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>()
// Integration
.UseSentry()
.Build();
Logging integration
This will also automatically include the integration to Microsoft.Extensions.Logging
. That means that any LogError
or LogCritical
by default will send an event to Sentry.
Log messages of level Information
will be kept as breadcrumbs and if an event is sent, all breadcrumbs from that transaction are included.
These levels can be configured so that the level you define tracks breadcrumbs or sends events or completely disable it.
That means that log messages logged by you or the framework, related to the failed transaction, will be added to the event!
DSN
The SDK needs to know which project within Sentry your errors should go to. That's defined via the DSN. You can provide it directly as an argument to UseSentry
, defined via configuration like appsettings.json
or set via environment variable SENTRY_DSN
.
This sample demonstrates defining the DSN via appsettings.json
.
Configuration
The SDK is configurable, many of the settings are demonstrated through the samples but here are some options:
- HTTP Proxy
- Event sampling
- Filter exception by type
- Enable request body extraction
- Send PII data (Personal Identifiable Information, requires opt-in)
- Read diagnostics activity data
- BeforeSend: Callback to modify/reject event before sending
- BeforeBreadcrumb: Callback to modify/reject a breadcrumb
- LogEventFilter: Filter events by inspecting log data
- Maximum number of breadcrumbs to store
- Event queue depth
- Shutdown timeout: If there are events to send, how long to wait until shutdown
- Accept compressed response
- Compress request body
- Breadcrumb level: Minimum log level to store as a breadcrumb
- Event level: Minimum log level to send an event to Sentry
- Disable duplicate event detection
- Disable capture of global unhandled exceptions
- Add event processor
- Add exception processor
- Enable SDK debug mode
- Attach stack trace for captured messages (opt-in)
and more...
Microsoft.Extensions.Logging
If you want only the logging integration:
dotnet add package Sentry.Extensions.Logging
See the logging integration only sample
Internals/Testability
It's often the case we don't want to couple our code with static class like SentrySdk
, especially to allow our code to be testable.
If that's your case, you can use 2 abstractions:
- ISentryClient
- IHub
The ISentryClient
is responsible to queueing the event to be sent to Sentry and abstracting away the internal transport.
The IHub
on the other hand, holds a client and the current scope. It in fact also implements ISentryClient
and is able to dispatch calls to the right client depending on the current scope.
In order to allow different events hold different contextual data, you need to know in which scope you are in.
That's the job of the Hub
. It holds the scope management as well as a client.
If all you are doing is sending events, without modification/access to the current scope, then you depend on ISentryClient
. If on the other hand you would like to have access to the current scope by configuring it or binding a different client to it, etc. You'd depend on IHub
.
An example using IHub
for testability is SentryLogger and its unit tests SentryLoggerTests.
SentryLogger
depends on IHub
because it does modify the scope (through AddBreadcrumb
). In case it only sent events, it should instead depend on ISentryClient
Compatibility
The packages target .NET Standard 2.0 and .NET Framework 4.6.1. That means it is compatible with the following versions or newer:
- .NET Framework 4.6.1
- .NET Core 2.0
- Mono 5.4
- Xamarin.Android 8.0
- Xamarin.Mac 3.8
- Xamarin.iOS 10.14
- Universal Windows Platform 10.0.16299
Of those, we've tested (we run our unit/integration tests) against:
- .NET Framework 4.8 on Windows
- Mono 6.6 on macOS and Linux
- .NET Core 2.1 on Windows, macOS and Linux
- .NET Core 3.1 on Windows, macOS and Linux
Sentry Protocol
For more details, please: refer to the documentation
Legacy frameworks
Sentry's Raven SDK, battle tested with over 1.000.000 downloads on NuGet has support to .NET Framework 3.5+.