Installation

Requirements

• .NET 9.0 or later
• Wolverine 6+ — CritterWatch observes the Wolverine runtime, so every monitored service (and the console itself) runs on Wolverine 6 or later
• Durability.Mode = Balanced on every monitored service — even when you run a single node (see note below)
• PostgreSQL 14+ with Marten 9+ — the CritterWatch server stores its own service state as a Marten event store
• A Wolverine transport, or the broker-less HTTP / gRPC channel, for service-to-CritterWatch communication — see Transport Requirements

Run monitored services in Balanced durability mode

CritterWatch's projection/subscription Pause and Restart actions are leader-owned agent-assignment changes. Under DurabilityMode.Solo there is no leader and no agent distribution, so those commands silently no-op — the projection keeps running. Set opts.Durability.Mode = DurabilityMode.Balanced on every monitored service; a single Balanced node simply elects itself leader and runs every agent locally, so this costs nothing for single-node deployments. Read-only monitoring, Rebuild, and Rewind work in any mode — only Pause/Restart require Balanced.

SQL Server persistence is coming

Today the CritterWatch server persists to PostgreSQL via Marten. An option to use SQL Server (via Polecat) for CritterWatch's own persistence is arriving shortly — so the PostgreSQL + Marten requirement will become "PostgreSQL/Marten or SQL Server/Polecat."

Fits your existing observability stack

CritterWatch complements the tools you already run rather than replacing them. It links out to distributed traces in Jaeger, and fits alongside metrics tooling like Prometheus and Grafana.

How CritterWatch is hosted

CritterWatch runs as a standalone ASP.NET Core application — a dedicated console you host yourself, separate from the services it monitors. A single CritterWatch instance can monitor many Wolverine applications at once: every service that installs the client package and points at the console shows up in the same dashboard.

Because it is a drop-in ASP.NET Core app, you secure it with any authentication scheme ASP.NET Core supports (cookies, OIDC, Microsoft Entra ID, and so on) and deploy it like any other web application.

No SaaS offering yet

CritterWatch is self-hosted today — you run the console inside your own infrastructure. There is no hosted / SaaS offering at this time.

Clustering CritterWatch

For high availability you can run multiple CritterWatch instances behind a load balancer. The only piece that needs cross-instance coordination is SignalR — the real-time channel that pushes live updates to connected browsers. Everything else (the Marten event store, the Wolverine listeners) already coordinates through shared infrastructure.

Give SignalR a backplane and CritterWatch clusters cleanly. Any SignalR-scale-out option works; the common choices are:

• Redis backplane — a Redis instance fans SignalR messages out across CritterWatch nodes.
• Azure SignalR Service — a managed backplane that offloads connection scale to Azure.

The constraint is only SignalR — anything that lets SignalR scale out will let CritterWatch scale out. See Clustering for the full deployment guide.

NuGet Packages

CritterWatch ships as two NuGet packages:

Wolverine.CritterWatch

Install this in each monitored service — the applications you want CritterWatch to observe.

dotnet add package Wolverine.CritterWatch

This package contains:

• CritterWatchObserver — hooks into the Wolverine runtime and publishes telemetry
• All inbound command message types (pause listener, replay messages, etc.)
• All outbound event message types (service updates, health reports, etc.)

CritterWatch

Install this in your CritterWatch server — the dedicated application that runs the monitoring console.

dotnet add package CritterWatch

This package contains:

• Hosting extensions (AddCritterWatch, UseCritterWatch)
• Marten event store projections for service state
• Alert system, SignalR hub, HTTP API
• Embedded Vue SPA (served as embedded assembly resources)

Version Compatibility

CritterWatch	Wolverine	.NET	Marten	Polecat	JasperFx
0.9.x (pre-1.0)	6.8.0	9.0+	9.7.6	4.4.4	2.10.0

CritterWatch is built on the same JasperFx ecosystem it monitors. Pins are coordinated across JasperFx / Marten / Polecat / WolverineFx — mixing versions across the family breaks on shared internal contracts, so the CritterWatch server in this repo at each version targets one coherent JasperFx stack.

The client package monitored services install — Wolverine.CritterWatch — carries no transitive Marten dependency, so monitored services running RavenDB, EF Core, or no event store at all can install CritterWatch monitoring without pulling Marten onto their build closure. The version table above describes what the CritterWatch server is built against; client-side, the only event-store pin that matters is the JasperFx.Events abstractions package, which both Marten and Polecat implement against.

CritterWatch is currently pre-1.0; minor version bumps may carry breaking wire-format or API changes until 1.0 ships. The version table above reflects what's in this repo's Directory.Packages.props today — see Releases for the published version history.

Transport Requirements

CritterWatch communicates with monitored services over a dedicated Wolverine channel. That channel runs in parallel with your application's existing messaging — it does not replace it, and you do not have to adopt Wolverine as your message bus, or convert any existing messaging, just to use CritterWatch. The channel carries only CritterWatch telemetry and control messages, on its own queue.

You can use any Wolverine-supported transport — see the full list in the Wolverine transport docs:

Transport	Package	Documentation
RabbitMQ	WolverineFx.RabbitMQ	RabbitMQ transport ↗
Amazon SQS	WolverineFx.AmazonSqs	Amazon SQS transport ↗
Azure Service Bus	WolverineFx.AzureServiceBus	Azure Service Bus transport ↗
SQL Server	WolverineFx.SqlServer	SQL Server transport ↗
HTTP / gRPC (broker-less)	(built-in)	Wolverine HTTP ↗

On Amazon SQS, watch for the 1 MiB message-body limit — the CritterWatch wire format applies brotli compression + lazy-fetch on that transport to stay under it.

No message broker? Use HTTP or gRPC

Not every system worth monitoring is message-driven. Plain web services — an ASP.NET Core API that uses Wolverine only for its HTTP endpoints, with no RabbitMQ / SQS / Azure Service Bus anywhere — can still be monitored. CritterWatch's broker-less channels let the console reach the service over HTTP (a /_wolverine/invoke endpoint) or a Wolverine gRPC port, with no messaging infrastructure to stand up.

If you don't run a broker — or don't want to add one just for monitoring — this is the path. See Transport Options for when it fits and how to wire it up.

The CritterWatch server listens on a dedicated queue (conventionally named "critterwatch"). A single CritterWatch instance can communicate through any number of queues, transport types, or even multiple brokers of the same transport at once — say, two separate RabbitMQ clusters plus an SQS-based service, all in one dashboard (see Wolverine's multiple brokers support). The in-tree dev stack does exactly this. Monitored services pick whichever transport they're already using.

PostgreSQL Setup

CritterWatch uses Marten to store service state as events. You need a PostgreSQL database accessible to the CritterWatch server. The Marten schema is automatically created on first run.

-- Create the database (CritterWatch will create the schema)
CREATE DATABASE critterwatch;

The recommended docker-compose.yml fragment:

postgres:
  image: postgres:16
  environment:
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: postgres
    POSTGRES_DB: critterwatch
  ports:
    - "5432:5432"

rabbitmq:
  image: rabbitmq:3-management
  ports:
    - "5672:5672"
    - "15672:15672"

Next Step

See the Quick Start Guide to connect your first service.