Skip to content

Latest commit

 

History

History
214 lines (159 loc) · 11 KB

README.md

File metadata and controls

214 lines (159 loc) · 11 KB
Raw


.NET SDK for Sentry

Travis AppVeyor Tests codecov

Integrations Downloads NuGet Stable NuGet Preview
Sentry Downloads NuGet NuGet
Sentry.Extensions.Logging Downloads NuGet NuGet
Sentry.AspNetCore Downloads NuGet NuGet
Sentry.Serilog Downloads NuGet NuGet
Sentry.Log4Net Downloads NuGet NuGet
Sentry.NLog Downloads NuGet NuGet

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 mesages 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
  • 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.7.2 on Windows
  • Mono 5.12 macOS and Linux (Travis-CI)
  • .NET Core 2.1 Windows, macOS and Linux

Sentry Protocol

Looking for the types used by this SDK to send data to Sentry like SentryEvent and SentryException? They are released as a separate NuGet Package called Sentry.Protocol and sources are on this GitHub repository.

Legacy frameworks

Sentry's Raven SDK, battle tested with over 1.000.000 downloads on NuGet has support to .NET Framework 3.5+.

Resources