Skip to content

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 systemControlUri the 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 upRabbitMQ / SQS / Azure Service Bus queueNone — uses existing HTTP or gRPC ingress on both sides
Where commands goThe service's control queueA direct send to the service's advertised systemControlUri
Console-side ingressA listener on the critterwatch queueThe console's own HTTP routes or gRPC port, which the services publish to
Console outageTelemetry waits in the broker. Routine batches older than ten minutes are discarded, and the console rebuilds current state from the next snapshotThe sender's retry policy only; telemetry published while the console is unreachable is lost
Failure shapeQueue depth grows, then alertsHTTP/gRPC errors on the sending side's log
Best forHeavy telemetry, multi-consumer fan-outA 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 ServiceUpdates snapshot 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 the critterwatch queue 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 example critterwatch-control. AddCritterWatchMonitoring declares 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:

csharp
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:

cs
// 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:

csharp
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:

  1. The app's own event store stays the Main message store; the queue transport is registered as MessageStoreRole.Ancillary so it doesn't collide for the Main role (a database transport otherwise registers a second Main and Wolverine throws at startup).

  2. CritterWatch automatically pins these DB-queue routes to BufferedInMemory — a database queue can't run Inline, and Durable would couple delivery to the ancillary store. No configuration is needed for this.

  3. 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/services returns [], and nothing logs anything. The simplest way to agree is to pass no transportSchema anywhere and let both halves take Wolverine's wolverine_queues default, 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_wolverine and marked the setting explicit, so a transportSchema passed on the console was silently overridden and DB-queue fleets could only work if every service also passed critterwatch_wolverine. From 1.0.2 the console leaves the transport schema alone. If your fleet worked by setting critterwatch_wolverine everywhere it keeps working — that value is still honoured, it is simply no longer forced. Otherwise drop the argument on both halves. Any critterwatch_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://...).

cs
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 ​

csharp
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 ​

csharp
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 seeLikely causeWhat to check
Console shows the service as silentThe 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 sendThe 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 ServiceUnreachableThe service advertised no control endpoint.The systemControlUri passed to AddCritterWatchMonitoring.
Commands never reach the serviceThe 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 arriveThe 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 ServiceUpdates to 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 AddCritterWatchMonitoring call that hangs off the configured Wolverine transport.