Skip to content

Add IAgent.Description for monitoring-tool tooltips#2645

Merged
jeremydmiller merged 1 commit intomainfrom
agent-description-property
May 1, 2026
Merged

Add IAgent.Description for monitoring-tool tooltips#2645
jeremydmiller merged 1 commit intomainfrom
agent-description-property

Conversation

@jeremydmiller
Copy link
Copy Markdown
Member

External monitoring tools (e.g. CritterWatch) want to render a human-readable explanation of what each running agent does on a given node. Today the only metadata available is the agent's URI, which means tooltips collapse to "you have to know what `wolverinedb://default` means."

This PR adds a default-implemented `Description` property on `IAgent`. The default returns `"{scheme} agent: {uri}"` so existing third-party `IAgent` implementations stay source-compatible with no code change. Built-in agent types override the property with text describing what they actually do:

Agent Description
`DurabilityAgent` (RDBMS) "Wolverine durability agent for {uri} — recovers persisted inbox/outbox messages, runs scheduled jobs, and emits persistence metrics."
`RavenDbDurabilityAgent` Same shape, RavenDB-flavoured.
`CosmosDbDurabilityAgent` Same shape, Cosmos-DB-flavoured.
`ExclusiveListenerAgent` "Exclusive listener for {endpoint} — only one node at a time holds the listening role for this endpoint, so the cluster avoids competing consumers."
`LeaderPinnedListenerAgent` "Leader-pinned listener for {endpoint} — runs only on the cluster's elected leader node, so the listening role moves with leader elections."
`StickyPostgresqlQueueListenerAgent` "Sticky Postgres queue listener — pinned to the per-tenant database '{name}' for queue '{name}'."

Consuming the description

Monitoring tools that want the per-agent description can read it after looking up the `IAgent`:

```csharp
if (runtime.Agents.TryFindActiveAgent(agentUri, out var agent))
{
var description = agent.Description;
// ...emit to telemetry / monitoring envelope...
}
```

No new public API surface beyond the property — `TryFindActiveAgent` already returns the strongly-typed agent.

Tests

Two new xUnit cases in `CoreTests/Runtime/Agents/IAgentDescriptionTests.cs`:

  1. `default_description_includes_uri_scheme_and_full_uri` — verifies a bare-bones IAgent that doesn't override Description still produces a non-empty description containing the scheme and URI.
  2. `overridden_description_wins_over_default` — verifies an explicit override takes precedence over the default-interface member.

All four persistence projects (RDBMS, RavenDb, CosmosDb, Postgresql) build clean. Existing test suite unaffected.

Motivation / consumer

CritterWatch issue #93 is the immediate consumer — its Service / Nodes tab wants per-agent tooltips so operators can see at a glance what each running agent is doing without having to recognise URI conventions.

External monitoring tools (e.g. CritterWatch) want to render a
human-readable explanation of what each running agent does on a
given node. Today the only metadata available is the agent's URI,
which means tooltips collapse to "you have to know what
'wolverinedb://default' means."

Adds a default-implemented `Description` property on IAgent. The
default returns "{scheme} agent: {uri}" so existing
implementations stay source-compatible with no code change. Built-
in agent types override the property with text describing what
they actually do:

- DurabilityAgent (RDBMS): "Wolverine durability agent for {uri}
  — recovers persisted inbox/outbox messages, runs scheduled
  jobs, and emits persistence metrics."
- RavenDbDurabilityAgent: similar, RavenDB-flavoured.
- CosmosDbDurabilityAgent: similar, Cosmos-DB-flavoured.
- ExclusiveListenerAgent: "Exclusive listener for {endpoint} —
  only one node at a time holds the listening role for this
  endpoint, so the cluster avoids competing consumers."
- LeaderPinnedListenerAgent: "Leader-pinned listener for
  {endpoint} — runs only on the cluster's elected leader node,
  so the listening role moves with leader elections."
- StickyPostgresqlQueueListenerAgent: "Sticky Postgres queue
  listener — pinned to the per-tenant database '{name}' for queue
  '{name}'."

CritterWatch consumers can read `agent.Description` after looking
up the IAgent via `IAgentRuntime.TryFindActiveAgent<IAgent>(uri,
out var agent)`. No new public API needed beyond the property
itself; the existing `TryFindActiveAgent` already returns the
strongly-typed agent.

Tests: two new xUnit cases cover the default-interface fallback
(generic description from URI) and an explicit override winning
through. All four persistence projects build clean. Existing test
suite unaffected.
@jeremydmiller jeremydmiller merged commit 99d9bee into main May 1, 2026
20 of 21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant