PrestigeXP.Sentinel 1.1.0

Sentinel

A .NET Standard Client for Sentry

Built using these great libraries:

• Polly v5.3.1
• Newtonsoft.Json v10.0.3

With inspiration from:

• Raven-CSharp
• .NET Microservices Architecture eBook

Installation

Option 1:

Install the PrestigeXP.Sentinel NuGet package.

Option 2:

You can download the Sentinel client by cloning this repository and adding it as a project reference to your application.

Key

Usage

Sentinel offers two ways for capturing events.

Middleware

The first is to capture all unhandled exceptions via middleware. Add the line app.UseSentinel() to the top of your startup configuration process, typically this is the Configure method in the Startup.cs file.

public void Configure(IApplicationBuilder app)
{
    app.UseSentinel();

    ...
}

After you've added that line you can continue by adding services.AddSentinel() to your startup services process typically this is the ConfigureServices method in the Startup.cs file.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSentinel(new SentinelSettings()
    {
        Dsn = this._configuration["SentryDsn"],
        Environment = "Production",
        Extra = new
        {
            SampleProperty = "This extra data will be sent with every captured event."
        },
        IgnoreTypes = new List<Type> { typeof(DivideByZeroException) },
        IncludeCookies = false,
        IncludeLocalLogging = Convert.ToBoolean(this._configuration["IncludeLocalLogging"]),
        IncludeRequestData = true,
        Release = this._configuration["Release"],
        SampleRate = 0.26,
        ServerName = "foo.example.com"
        
    }, new CustomSentinelClientFactory());
    
    ...
}

The first argument in the services.AddSentinel() method is an instantiated SentinelSettings, this POCO offers various settings that will affect which and how events are sent to Sentry. We recommend setting an environment variable for each setting you would like to set, passing the resulting object as the first argument.

The second argument in the services.AddSentinel() method is an implementation of ISentinelClientFactory. This allows you to define how Sentinel clients should be instantiated and with what contexts e.g. Http, User. The SentinelSettings that are defined as the first parameter will be passed into ISentinelClientFactory.CreateClient() which is the method called by the middleware to instantiate a client.

An example implementation of a ISentinelClientFactory, which sets the user using ASP.NET Core Identity, is below:

public class CustomSentinelClientFactory : ISentinelClientFactory
{
    /// <summary>
    /// Creates a <see cref="ISentryClient" /> using the specified parameters.
    /// </summary>
    /// <param name="sentinelSettings">
    /// An object that allows user to encapsulate all their settings. This is particularly
    /// useful for custom middleware implementations.
    /// </param>
    /// <param name="httpContext">The HTTP context of the current request/response lifecycle.</param>
    /// <returns>A sentry client for use with Sentinel.</returns>
    public ISentryClient CreateClient(SentinelSettings sentinelSettings, HttpContext httpContext)
    {
        var client = new SentryClient(sentinelSettings);

        client.Contexts.Add(ContextTypes.Http, new HttpSentryContext(httpContext));

        if (httpContext.User.Identity is User user)
        {
            client.Contexts.Add(ContextTypes.User, new UserSentryContext(httpContext)
            {
                Email = user.Email,
                Id = user.Id.ToString(),
                Username = user.UserName
            });
        }

        return client;
    }
}

There is a default client factory provided known as SentinelClientFactory and it will be used if the second argument in services.AddSentinel() is null or not provided.

Manual Capturing

You can manually capture an error or message by simply instantiating a SentryClient and passing either a string, for messages, or an exception to the Capture method.

new SentryClient("DSN_HERE").Capture("MESSAGE_HERE");

or

try
{
    var x = 0;

    var y = 1 / x;
}
catch (Exception ex)
{
    new SentryClient("DSN_HERE").Capture(ex);
}

Both of these methods simply convert the argument, exception or message, into a SentryEvent. If you want to modify the SentryEvent created, you can instantiate a SentryEvent passing in your message or exception and modify as necessary before passing the SentryEvent into the Capture method.

Async/Await

Sentinel has support for asynchronous programming via the CaptureAsync method.

var client = new SentryClient("DSN_HERE");

await client.CaptureAsync("MESSAGE_HERE");

Pre/Post Capture and OnException Hooks

Sentinel has the ability for users to specify an action to perform before and after sending the event to Sentry including a exception handling hook. The interface ISentryClientHooks is defined to allow you to create a class that will be consumed by the SentryClient when sending events. Once you create your own implementation, you only have to assign it to the SentinelSettings object passed into the services.AddSentinel() method.

Sanitization

Sentry offers a server-side sanitization but recommends that all SDKs include a means of sanitization. Sentinel has one built in that sanitizes Credit Cards, Social Security Numbers, and Phone Numbers. However, should you want to create your own scrubber you will need to create a class that implements ISentryScrubber and, similarly to the hooks, assign it to the SentinelSettings object passed into the services.AddSentinel() method.

Opt-in Local Logging/Cookies/Request Data

Sentinel offers a way to toggle on the capturing of Local Events (localhost), Cookies, and Request Data for events sent to Sentry. Simply set the IncludeLocalLogging, IncludeCookies, or IncludeRequestData properties on the SentinelSettings object passed into the services.AddSentinel() method to true and they will be captured respectively.

Event Sampling

Sentinel allows you to specify the sampling percentage of exceptions to capture. This means you can set the SampleRate on the SentinelSettings object passed into the services.AddSentinel() method and Sentinel will capture events using that percentage.

Problems?

Feel free to open a GitHub issue and we'll get started on figuring out a solution that works for you and the community.