HTTP and gRPC Transport Channels
CritterWatch publishes telemetry to (and accepts control commands from) the Wolverine applications it monitors over a Wolverine transport endpoint. The default story — and the one Message Flow walks through — is the broker route: the monitored app and CritterWatch both attach to a common RabbitMQ / SQS / Azure Service Bus queue.
This page covers the broker-less alternative: the console and the monitored app exchange Wolverine envelopes directly over Wolverine's HTTP transport (Wolverine.Http's /_wolverine routes) or its gRPC transport (Wolverine.Grpc). Nothing about the conversation changes, only the carrier, and both directions are one-way envelopes:
- The service publishes its telemetry to its
critterWatchUri— which here is the console's HTTP or gRPC ingress. - The console sends each operator command or query, fire-and-forget, to the
systemControlUrithe service advertised when it registered — the service's HTTP or gRPC ingress. - The service answers a command or query by publishing a separate message back to
critterWatchUri, exactly as it publishes telemetry.
So each side needs an ingress the other can reach. There is no request/reply call in either direction, and no reply rides an HTTP or gRPC response.
This is the communication channel, not the node registry.
The transport channel is what carries CritterWatch's wire messages between the console and a monitored Wolverine service. It does not replace a clustered app's persistence-backed node registry or leader election — those still rely on the monitored app's Postgres / SQL Server / EF Core durability table. See Clustering for the durability side.
Tested end to end
Both broker-less channels are exercised by CritterWatch's test suite: a console and a monitored service talk over real HTTP and over gRPC, the service registers from its telemetry, and a query the console relays to it is answered over the same channel.
At a glance — what changes for operators
| Broker route (default) | HTTP / gRPC route | |
|---|---|---|
| What you stand up | RabbitMQ / SQS / Azure Service Bus queue | None — uses existing HTTP or gRPC ingress on both sides |
| Where commands go | The service's control queue | A direct send to the service's advertised systemControlUri |
| Console-side ingress | A listener on the critterwatch queue | The console's own HTTP routes or gRPC port, which the services publish to |
| Console outage | Telemetry waits in the broker. Routine batches older than ten minutes are discarded, and the console rebuilds current state from the next snapshot | The sender's retry policy only; telemetry published while the console is unreachable is lost |
| Failure shape | Queue depth grows, then alerts | HTTP/gRPC errors on the sending side's log |
| Best for | Heavy telemetry, multi-consumer fan-out | A small fleet with no broker, on the same secured ingress as the application |
The two routes are not mutually exclusive. A service can publish telemetry to a broker and still accept commands over HTTP: the console sends commands to whatever systemControlUri the service advertises, and Wolverine routes telemetry to whatever critterWatchUri names.
When to reach for this
Choose HTTP or gRPC over a broker for:
- Services that already expose HTTP or gRPC and don't run a broker. No need to stand up RabbitMQ just to give CritterWatch a channel.
- A topology where a broker is operationally inconvenient — a small number of services, an environment that doesn't ship a broker by default (e.g. internal SaaS tooling running in containers without the broker sidecar), or a regulated environment that wants to keep the monitoring traffic on the same secured ingress as the application traffic.
Choose a broker over HTTP / gRPC for:
- Heavy telemetry fan-out — broadcasting a single
ServiceUpdatessnapshot to multiple consumers (e.g. a CritterWatch cluster + an independent metrics pipeline). The broker fans out for free; the direct channel is point-to-point. - Riding out console outages — the broker holds telemetry while the console is down. Routine telemetry still expires after ten minutes, so nothing older is replayed; the console rebuilds current state from the next snapshot. A direct HTTP / gRPC send fails fast and relies on the sender's retry policy.
- Existing broker investment — if the monitored app already publishes durable messages over RabbitMQ / SQS, attaching CritterWatch to the same broker is the cheapest path.
Topology
Over HTTP
Each side maps Wolverine's HTTP transport routes under the /_wolverine group prefix, and the other side posts batches of envelopes to POST /_wolverine/batch/{queue}, which delivers them into the local queue of that name:
- The console's ingress is
/_wolverine/batch/critterwatch. The console declares thecritterwatchqueue itself, with CritterWatch's wire serializer and the same per-service ordering its broker listeners get. - The service's ingress is
/_wolverine/batch/{a queue you name}, for examplecritterwatch-control.AddCritterWatchMonitoringdeclares that queue on the service.
Not /_wolverine/invoke
Wolverine's other HTTP route, /_wolverine/invoke, cannot carry CritterWatch traffic: it picks a deserializer by content type alone, so it reads CritterWatch's compressed wire format as plain JSON and fails, and it runs each message inline, outside the console's per-service ordering. AddCritterWatchMonitoring refuses an http(s) URI that does not name a /batch/{queue} route, at startup, and says why.
Over gRPC
The same shape, with each side listening on an embedded gRPC port.
Monitored-app configuration
HTTP
Register Wolverine.Http's services and add its HTTP transport endpoint group to your ASP.NET Core routing tree:
using Wolverine.Http.Transport;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddWolverineHttp();
builder.Host.UseWolverine(opts =>
{
// Your normal Wolverine config + AddCritterWatchMonitoring (below).
});
var app = builder.Build();
// Add the routes the HTTP transport needs, including POST /_wolverine/batch/{queue}.
// The default group prefix is "/_wolverine": pass a different prefix if your
// ingress carves out a different path, and use the same prefix in the URIs below.
app.MapWolverineHttpTransportEndpoints();
app.Run();Then register Wolverine's HTTP transport and point AddCritterWatchMonitoring at the two ingresses:
// On the monitored service. Register Wolverine's HTTP transport before naming
// http(s) URIs (otherwise only ToHttpEndpoint(...) registers it).
opts.UseHttpTransport();
opts.AddCritterWatchMonitoring(
// Where this service publishes its telemetry and its answers to commands:
// the CONSOLE's batch route, into its "critterwatch" ingress queue.
critterWatchUri: new Uri("https://critterwatch.internal/_wolverine/batch/critterwatch"),
// Where the console sends commands and queries for this service: this
// service's batch route, into a local queue CritterWatch declares for it.
// The service advertises it to the console, so it must be reachable FROM the console.
systemControlUri: new Uri("https://trip-service.internal/_wolverine/batch/critterwatch-control"));The UseHttpTransport() line (Wolverine 6.56 and later) is needed because Wolverine otherwise registers its HTTP transport only when something calls ToHttpEndpoint(...). Without it, AddCritterWatchMonitoring stops at startup with a message naming that line.
Telemetry runs buffered, as it does over a broker: the service sends one POST per batch, off your application's own threads.
Commands on a clustered service
A broker control queue is consumed only on the service's leader node. An HTTP control URI is wherever your ingress routes the POST, so behind a load balancer a command is handled by whichever node receives it.
gRPC
The gRPC transport hosts its own embedded gRPC server — no MapGrpcService call is needed at the ASP.NET Core layer:
using Wolverine.Grpc;
var builder = Host.CreateDefaultBuilder();
builder.UseWolverine(opts =>
{
// Listen for inbound Wolverine envelopes on this gRPC port. The transport
// maps WolverineGrpcTransportService against an embedded Kestrel host.
opts.ListenAtGrpcPort(5188);
// Your normal Wolverine config + AddCritterWatchMonitoring.
});The transport's WolverineGrpcTransportService is the inbound surface. Point AddCritterWatchMonitoring at grpc:// URIs the same way as the HTTP sample above: critterWatchUri at the console's gRPC port, and systemControlUri at this service's port under a host name the console can reach, such as grpc://trip-service.internal:5188.
Database queues (PostgreSQL / SQL Server)
When the monitored app already runs on PostgreSQL or SQL Server, a database-backed Wolverine queue can be the CritterWatch control + telemetry channel — no broker, no HTTP/gRPC endpoint. Three things matter:
The app's own event store stays the
Mainmessage store; the queue transport is registered asMessageStoreRole.Ancillaryso it doesn't collide for theMainrole (a database transport otherwise registers a secondMainand Wolverine throws at startup).CritterWatch automatically pins these DB-queue routes to
BufferedInMemory— a database queue can't runInline, andDurablewould couple delivery to the ancillary store. No configuration is needed for this.The transport schema is a fleet-wide rendezvous. The queue tables that carry
postgresql://critterwatch(and each service's own control queue) must live in one schema that the console and every monitored service agree on — otherwise each half auto-provisions its own copy of a same-named queue table, services write telemetry into one and the console drains the other,/api/critterwatch/servicesreturns[], and nothing logs anything. The simplest way to agree is to pass notransportSchemaanywhere and let both halves take Wolverine'swolverine_queuesdefault, which is what the sample below does. If you do set it, set the same value on the console and on every service.Upgrading from 1.0.0 / 1.0.1
Those releases pinned the console's queue tables to
critterwatch_wolverineand marked the setting explicit, so atransportSchemapassed on the console was silently overridden and DB-queue fleets could only work if every service also passedcritterwatch_wolverine. From 1.0.2 the console leaves the transport schema alone. If your fleet worked by settingcritterwatch_wolverineeverywhere it keeps working — that value is still honoured, it is simply no longer forced. Otherwise drop the argument on both halves. Anycritterwatch_wolverine.wolverine_queue_*tables left behind hold at most a few seconds of already-expired telemetry and can be dropped.
The queue name is the URI host: postgresql://critterwatch is a queue named critterwatch (likewise sqlserver://...).
builder.Host.UseWolverine(opts =>
{
opts.ServiceName = "my-service";
// The monitored app's own Marten event store stays the Main message store.
opts.Services.AddMarten(connectionString).IntegrateWithWolverine();
// Use a PostgreSQL queue as the CritterWatch control channel. Mark the transport's store
// Ancillary so it does not collide with the app's event store for the 'Main' role — a DB
// transport otherwise registers a second Main and Wolverine throws at startup.
// (Use UseSqlServerPersistenceAndTransport for SQL Server queues; same role argument.)
//
// NOTE the two schema arguments are not the same kind of thing:
// schema: this transport's OWN envelope storage. Private to this app; name it
// whatever you like.
// transportSchema: where the QUEUE TABLES live. This is a rendezvous — the console and
// every monitored service must agree, or each provisions its own copy of
// a same-named queue and nothing is ever delivered. It is left unset
// here so both halves take Wolverine's "wolverine_queues" default, which
// is the simplest way to agree. If you set it, set the SAME value on the
// console and on every service in the fleet.
opts.UsePostgresqlPersistenceAndTransport(
connectionString, schema: "myapp",
role: MessageStoreRole.Ancillary)
.AutoProvision();
// The queue name is the URI host: postgresql://critterwatch is a queue named "critterwatch".
// CritterWatch automatically pins these DB-queue routes to BufferedInMemory — a database
// queue cannot run Inline, and Durable would couple delivery to the ancillary store.
opts.AddCritterWatchMonitoring(
critterWatchUri: new Uri("postgresql://critterwatch"),
systemControlUri: new Uri("postgresql://my-service-control"));
});CritterWatch-side configuration
The console needs no per-service routing. It sends each command to the systemControlUri the service advertised when it registered, so a service that joins the fleet needs no change on the console. Do not add a PublishAllMessages() rule pointing at one service: the console routes per service.
What the console needs is its own ingress for the services' critterWatchUri. Your normal console configuration (CritterWatch, CritterWatch.SqlServer or CritterWatch.Sqlite) stays as it is, plus:
HTTP
using Wolverine.Http.Transport;
var app = builder.Build();
app.UseCritterWatch();
// The routes the services post telemetry and answers to. Their critterWatchUri is
// this console's https://.../_wolverine/batch/critterwatch.
app.MapWolverineHttpTransportEndpoints();Nothing else is needed on the console. It registers Wolverine's HTTP transport, which it needs to send commands to each service's http(s) control URI, and it declares the critterwatch ingress queue. Mapping the routes is left to you, because it exposes them.
One console node per service's telemetry
The console keeps one service's telemetry in order per node. If a load balancer spreads one service's POSTs across several console nodes, each node orders only what it receives, as with an unsharded broker queue that is not pinned to one node. Run a single console node for the HTTP channel, or route each service to one node.
gRPC
using Wolverine.Grpc;
builder.AddCritterWatch(connectionString, opts =>
{
// The port the services publish telemetry and answers to. Their
// critterWatchUri is grpc://{this console's host}:5199.
opts.ListenAtGrpcPort(5199);
});How answers get back
Because the console only ever sends, a command or query and its answer are two separate envelopes. The service handles the command and publishes the outcome — a ProjectionCommandAck, a DlqOperationCompleted, a page of DeadLetterDetails and so on — to critterWatchUri, the same destination as its telemetry. The console matches the answer to the request by the ids it carries (RequestId and the like), as it does over a broker. See Outbound Events.
A command the console refuses never leaves it: it answers the browser with CommandRejected — for example ServiceUnreachable when the service advertised no control endpoint.
Troubleshooting the broker-less path
| What you see | Likely cause | What to check |
|---|---|---|
| Console shows the service as silent | The direct channel doesn't buffer while the console is unreachable; telemetry published then is lost. Or the console has no ingress at the service's critterWatchUri. | Confirm the console maps MapWolverineHttpTransportEndpoints() (or listens on the gRPC port) at the URI the service publishes to. If you need telemetry to survive console outages, run it over a broker even when commands use the direct channel. |
| Startup fails: "uses Wolverine's HTTP transport, which is not registered yet" | The service did not register the HTTP transport. | Add opts.UseHttpTransport() before AddCritterWatchMonitoring. |
| Startup fails: "must name Wolverine's batch route" | A URI points at /_wolverine/invoke or another path. | Use …/_wolverine/batch/critterwatch for the console and …/_wolverine/batch/{queue} for the service. |
404 on every send | The receiving side has not mapped the routes, or maps them under a different prefix. | app.MapWolverineHttpTransportEndpoints() on that side, and the prefix in the URI. |
Commands rejected as ServiceUnreachable | The service advertised no control endpoint. | The systemControlUri passed to AddCritterWatchMonitoring. |
| Commands never reach the service | The advertised systemControlUri is not reachable from the console — localhost, an internal name, or an ingress rule blocking the /_wolverine group. | Curl the URI from the console's network namespace (or grpcurl the host:port). |
| Commands work, telemetry doesn't arrive | The two flows are configured independently. Telemetry may still be published to a broker the console isn't listening on. | Check the service's critterWatchUri — it's the publish destination, separate from the command ingress. |
What this channel does not do
- It is not a node registry. A clustered monitored app's leader election + per-node assignments still live in its durability table (
wolverine_nodes). HTTP / gRPC are how CritterWatch talks to a service; they don't tell CritterWatch which node owns which agent. - It is not a substitute for a broker on heavy telemetry fan-out. The direct channel is point-to-point — well-suited to a small fleet, less well-suited to broadcasting
ServiceUpdatesto multiple independent consumers. - It does not buffer when the console is down. The sender's retry policy handles transient failures; permanent ones fail fast. If telemetry must survive a console outage, run a broker or a hybrid — broker for telemetry, direct channel for commands.
See also
- Message Flow — the broker route this page is the broker-less complement to.
- Registration — the monitored-side
AddCritterWatchMonitoringcall that hangs off the configured Wolverine transport.
