UsageWatch.Client 1.0.0

UsageWatch.Client

ASP.NET Core middleware and client SDK for reporting API usage to UsageWatch — an API analytics and observability platform. Drop it into your API to see who's calling it, which endpoints they use, latency percentiles (P50–P99), error rates, and whether clients are retrying or putting your API under pressure.

Delivery is fully non-blocking: every request is recorded to an in-memory queue and shipped to UsageWatch by a background service, so a slow or unreachable UsageWatch instance can never add latency to your API.

Install

dotnet add package UsageWatch.Client

Quick start

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddUsageWatch(options =>
{
    options.ApiKey = builder.Configuration["UsageWatch:ApiKey"]!;
    options.IngestBaseUrl = "https://your-usagewatch-deployment.example.com";
    options.Environment = "production";
});

var app = builder.Build();

app.UseRouting();
app.UseUsageWatch();   // after UseRouting, before endpoints
app.MapControllers();

app.Run();

That's it — every request is now automatically tracked: route template (normalized, so /orders/123 and /orders/456 aggregate as /orders/{id}), method, status code, response time, and response size.

Manual tracking

Inject IUsageWatchClient anywhere you want to record a usage event outside the normal HTTP pipeline — background jobs, gRPC calls, or an endpoint you want tracked under a specific client identifier:

public class OrderJob(IUsageWatchClient usageWatch)
{
    public async Task RunAsync()
    {
        var sw = Stopwatch.StartNew();
        // ... do work ...
        usageWatch.Track(
            endpoint: "/jobs/process-orders",
            method: "JOB",
            statusCode: 200,
            responseTimeMs: sw.ElapsedMilliseconds,
            clientIdentifier: "acme-corp");
    }
}

Identifying clients

UsageWatch breaks usage down per calling client, but there's no universal way to know who's calling your API — it depends entirely on how your app identifies callers. Nothing is guessed or auto-detected; configure one (or more, in priority order) of the following:

builder.Services.AddUsageWatch(options =>
{
    options.ApiKey = "...";
    options.IngestBaseUrl = "...";

    // 1. Highest priority — full control over resolution.
    options.ClientIdentifierResolver = ctx => ctx.Items["TenantId"]?.ToString();

    // 2. Request header (default: "X-Client-Id").
    options.ClientIdHeaderName = "X-Client-Id";

    // 3. Query string parameter, e.g. ?client_id=acme-corp (off by default).
    options.ClientIdQueryParamName = "client_id";

    // 4. Claim on the authenticated user (off by default).
    options.ClientIdClaimType = "client_id";
});

If none of the configured strategies resolve a value for a given request, the call is still tracked and counted toward quota — just not attributed to a specific client.

Configuration reference

All options are set via AddUsageWatch(options => { ... }).

How delivery works

• Every tracked request is written to a bounded in-memory channel — never blocking the request thread.
• A background hosted service (UsageWatchDispatcher) drains the channel and POSTs each event to {IngestBaseUrl}/api/ingest/usage.
• If the queue is full, new events are dropped rather than slowing down your API.
• Failed deliveries retry with exponential backoff up to MaxRetryAttempts. A 429 response (project quota exceeded) is treated as delivered — no retry.
• On graceful shutdown, the dispatcher keeps draining the queue for up to ShutdownFlushTimeout so in-flight events aren't lost on deploy/restart.

Requirements

• .NET 8
• An ASP.NET Core application (the package references Microsoft.AspNetCore.App)
• A UsageWatch instance and project API key — see usagewatch.onrender.com

License

MIT