QueueHawk.Agent 1.1.0

QueueHawk.Agent

The Hangfire dashboard you already have doesn't survive a restart, doesn't cover more than one app, and doesn't tell anyone when a job silently stops running. QueueHawk does.

QueueHawk.Agent is a lightweight NuGet package that plugs into your existing Hangfire setup and streams job history, failures, and worker heartbeats to QueueHawk — a hosted dashboard built for teams and agencies running Hangfire across multiple apps, clients, and environments.

• 📊 One dashboard for every app — stop tab-hopping between a dozen /hangfire dashboards for a dozen client projects.
• 🕓 Persistent history — job history survives redeploys and restarts, unlike Hangfire's own dashboard.
• 🔔 Real alerting — get a Slack, Teams, or email alert when error rates spike or a server stops sending heartbeats, instead of finding out when a client calls.
• 💓 Heartbeat monitoring — catches the scary case a pure job-event feed can't: a worker that's alive but has quietly stopped picking up jobs at all.
• 🔒 Privacy by design — job arguments/payloads are never sent unless you explicitly opt in; only metadata (job type, queue, timing, state, exception details) leaves your infrastructure, and exception content itself can be redacted or dropped before it ever leaves the process via OnBeforeSend.
• 📤 Push-only, one outbound hostname — the agent only ever makes outbound HTTPS calls; nothing needs to be opened inbound in your firewall.
• 🪶 Negligible overhead — job state changes are captured via Hangfire's own filter pipeline and dropped onto an in-memory channel; a background service batches and ships them, so nothing in your job execution path waits on a network call.
• 🛡️ Fails safe — the agent can never throw into your job pipeline. Every internal operation is exception-guarded; if QueueHawk is unreachable, jobs keep running and events buffer locally (oldest dropped first past 5,000 events) until it recovers.

Install

dotnet add package QueueHawk.Agent

Quick start

Get an API key by creating a free account and an application at queuehawk.com, then register the agent alongside your existing Hangfire setup:

builder.Services.AddHangfire(config => config.UseSqlServerStorage(connectionString));
builder.Services.AddHangfireServer();

// QueueHawk integration — one line, no changes to existing job code
builder.Services.AddQueueHawk(options =>
{
    options.ApiKey = builder.Configuration["QueueHawk:ApiKey"];
    options.Environment = "Production"; // free-text label, e.g. also useful as a client/tenant name
});

That's it — no Hangfire storage access required, no extra process to run. Job events and heartbeats start showing up in your QueueHawk dashboard within seconds.

Configuration

All options are optional except ApiKey:

Redacting sensitive exception content

Exception messages and stack traces are sent as-is by default (only truncated to MaxStackTraceLength) — job payloads are the thing that's off by default (IncludeJobPayloads), not exception text. If an exception message itself can contain PII (e.g. a validation error that echoes a customer's email address), use OnBeforeSend to redact or drop the event before it's ever buffered in memory:

builder.Services.AddQueueHawk(options =>
{
    options.ApiKey = builder.Configuration["QueueHawk:ApiKey"];
    options.Environment = "Production";

    options.OnBeforeSend = jobEvent =>
    {
        if (jobEvent.ExceptionMessage is null)
        {
            return jobEvent;
        }

        return jobEvent with
        {
            ExceptionMessage = Regex.Replace(
                jobEvent.ExceptionMessage,
                @"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}",
                "[REDACTED-EMAIL]"),
        };
    };
});

The callback runs for every state-change event (not just failures), can return a rewritten JobEventDto, and returning null drops that event entirely — nothing is buffered or sent. Like every other agent operation, an exception thrown from your callback never propagates into your Hangfire job pipeline; that one event is simply dropped. Full option reference: queuehawk.com/docs/agent-configuration.

How it works

QueueHawk.Agent hooks into Hangfire's own IElectStateFilter/IApplyStateFilter extension points — the same mechanism Hangfire itself uses — so it sees every job state transition (Enqueued → Processing → Succeeded/Failed, including retries) without touching your job code or your Hangfire storage. Each event is written to a non-blocking in-memory channel; a background service batches and ships them over HTTPS. A second background service reports a periodic heartbeat per Hangfire server, which is how QueueHawk detects the failure mode a job-event stream alone can't: a server that's still running but has stopped processing anything at all.

Compatibility

• .NET: 8, 9, and 10
• Hangfire: works against any Hangfire storage backend (SQL Server, PostgreSQL, Redis, ...) — the agent only uses Hangfire's filter API, never talks to storage directly

Learn more

• queuehawk.com — sign up, pricing, and full product overview