ErrorDock.AspNetCore 0.1.0-rc.1

ErrorDock.AspNetCore

The ErrorDock SDK for ASP.NET Core. Unhandled exceptions, log events, feature usage and request context, sent to ErrorDock.

dotnet add package ErrorDock.AspNetCore

Targets net8.0, so it installs into ASP.NET Core 8, 9 and 10. It brings ErrorDock.Extensions.Logging and ErrorDock.Core with it — install this one and you have everything.

Getting started

builder.Services.AddErrorDock(options =>
{
    options.ApiKey = "ed_live_…";
    options.Endpoint = "https://api.errordock.com";
    options.Environment = builder.Environment.EnvironmentName;
    options.Release = typeof(Program).Assembly.GetName().Version?.ToString();
});

var app = builder.Build();

app.UseErrorDock();

UseErrorDock goes early in the pipeline — it has to see an exception before anything else turns it into a 500.

Configuration can come from appsettings.json instead, under the ErrorDock section:

{
  "ErrorDock": {
    "ApiKey": "ed_live_…",
    "Endpoint": "https://api.errordock.com",
    "Environment": "Production",
    "MinimumLogLevel": "Warning"
  }
}

Use a server key (ed_live_). The browser key (ed_pub_) is published by definition and cannot hold a sending scope.

Reporting by hand

public sealed class CheckoutService(IErrorDockClient errorDock)
{
    public async Task<Receipt> PayAsync(Order order)
    {
        try
        {
            return await _payments.ChargeAsync(order);
        }
        catch (PaymentException ex)
        {
            errorDock.CaptureException(ex, $"Order {order.Id} could not be paid");
            throw;
        }
    }
}

CaptureMessage reports without an exception, and FlushAsync drains the queue before a process exits — worth calling in a worker or a CLI, never needed in a long-running web app.

A batch that cannot be delivered is written to disk and replayed on a later run rather than dropped, so a redeploy during a network blip no longer costs the events that were in flight. See ErrorDock.Core for the knobs.

Features, and why the scope matters

// A bare count of uses: how popular is this?
errorDock.TrackFeature("checkout", new Dictionary<string, object?> { ["tier"] = "pro" });

// A timed execution with an outcome: how often does it fail?
var receipt = errorDock.RunFeature("checkout", () => _payments.Charge(order));

RunFeature records the execution, marks it failed if the work throws, and rethrows. That produces the denominator as well as the numerator, which is what makes a feature error rate a number rather than a guess. TrackFeatureScope is the manual form when the work is not a delegate.

Context

using (ErrorDockScope.SetUser(user.Id))
using (ErrorDockScope.SetTag("tenant", tenant.Slug))
{
    // Everything reported in here carries the user and the tag.
}

User identifiers are not sent unless SendUserIdentifier is turned on. Without it the server sees a hash, which is enough to count affected people and not enough to name them.

Logs

builder.Logging.AddErrorDock();

Log events at or above MinimumLogLevel (Warning by default) become ErrorDock events, with the same feature, user and tags as an exception raised in the same scope — and, when they are raised during a request that passed through UseErrorDock(), the request's path and its id (HttpContext.TraceIdentifier, as properties.requestId), so a warning lands beside the exception from the same request. The full request description — method, URL, status and headers — is attached to unhandled exceptions and 404s only.

What leaves the process about a request

The method, the path without its query string, the status code, and a short allowlist of headers: User-Agent, Accept, Accept-Language, Accept-Encoding, Content-Type, Content-Length, Host and Referer with its query string removed. Nothing else, because a header nobody has judged safe is a header that holds a tenant id or a session token somewhere. Name the ones your application needs:

builder.Services.AddErrorDock(options =>
{
    options.CaptureRequestHeaders.Add("X-Tenant");
    options.CaptureRequestHeaders.Add("X-Request-Source");
});

Credential-bearing headers — Authorization, Cookie, X-Api-Key and their relatives — are sent as [redacted] even when named there. The body is never read. CaptureRequestContext = false turns the whole description off.

What it guarantees

• It never throws. Every entry point swallows its own failures; a monitoring SDK that breaks a customer's request is worse than no SDK at all. OnInternalError is there if you want to see what it swallowed.
• It never blocks. Events go on a bounded queue and are sent in batches by a background sender. A full queue drops the oldest event rather than waiting.
• It gives up on purpose. A circuit breaker opens after repeated failures, so an ErrorDock outage costs you nothing but the telemetry from it.
• It brings almost no dependencies. Everything web-facing comes from the ASP.NET Core shared framework. The two packages underneath it take Microsoft.Extensions.* abstractions and nothing else, so it cannot drag a conflicting implementation into your application.
• It follows the dashboard. With RemoteConfiguration on, toggling data collection in your project settings changes what this SDK sends within five minutes and without a deploy.

Licence

MIT. The ErrorDock service itself is proprietary; this SDK is not.