C#: logging, diagnostics, tests and shutdown

​

The log file

[2026-10-23T12:00:00.000Z] [sdk=1.0.0 dotnet=8.0.11 mcp=2.2.0] Successfully sent event <event ID> | mcp:tools/call | session <session ID> | <project ID> | 12 ms | <actor ID>

• No debug option. The log is always on. The C# SDK has no debug mode and does not read AGENTCAT_DEBUG_MODE.
• Never stdout or stderr. AgentCat writes nothing to the console, so the stdout of a stdio server stays the JSON-RPC stream.
• No usable home directory. When the process has none, or when AgentCat cannot open the file, it writes no log for the rest of the process. Your server runs as usual.
• Several processes. Server processes of one user can share the file. AgentCat opens the file for each line and writes the whole line.
• While AgentCat is off (see Turn AgentCat on or off), it writes nothing and creates no file.

​

Send the lines to your logger: LogToHost

builder.Services.AddMcpServer()
    .WithHttpTransport(o => o.Stateless = true)
    .WithTools<MyTools>()
    .WithAgentCat("proj_YOUR_PROJECT_ID", options =>
    {
        options.LogToHost = true;
    });

// Keep the failure lines and drop the routine ones (see Levels below)
builder.Logging.AddFilter("AgentCat", LogLevel.Warning);

• Levels. A line that starts with WARN: is a warning. Else a line that contains fail or error, in any ASCII case, is an error. Else a line that contains Warning: is a warning. Every other line is information. Routine lines that carry a value of yours or an ID, such as the success line (it ends with the actor ID), the setup lines and the exporter lines, are always information, so a tool or actor named search_errors raises nothing. Lines that report a lost event (queue full, shutdown), an ignored custom event or tag, or an unknown exporter are warnings or errors whatever their text says. Your logger gets the message without the time and the version prefix.
• One line for each event. AgentCat logs Successfully sent event … at the Information level for each event that it delivers. Failure lines log at the Error level: for example Failed to send event …, Failed to deliver AgentCat event after retries: …, Failed to initialize exporter … and Telemetry export failed for …. The filter in the sample keeps every failure line and every warning, and drops the success lines. To see every line, leave the category at Information.
• WithAgentCat() only. Only dependency injection gives AgentCat a logger factory. AgentCatSdk.Track() keeps the file and logs WARN: AgentCat LogToHost works only with WithAgentCat; Track keeps writing to the AgentCat log file once.
• The first call decides. The first WithAgentCat() call with LogToHost = true whose service provider has an ILoggerFactory sends the lines of the whole process to that logger. Without a logger factory, AgentCat keeps the file.
• stdio servers send their console logs to stderr (LogToStandardErrorThreshold = LogLevel.Trace), because stdout carries the MCP messages. See stdio on the generic host.

​

Diagnostics

• session IDs and actor IDs: AgentCat logs one line for each event it sends, in the form Successfully sent event <event ID> | <event type> | session <session ID> | <project ID> | <duration> ms | <actor ID>;
• tool names, and error messages, which hold whatever the code that threw put in them: your hooks, your options delegate and your tools/list handler included;
• the answers of exporters that failed, quoted (up to 64 KB), with the key part of a Sentry DSN replaced by ***;
• the keys of the tags that AgentCat drops.

• set options.DisableDiagnostics = true on the first WithAgentCat() or Track() of the process (the first install decides);
• or set the environment variable AGENTCAT_DISABLE_DIAGNOSTICS=true. The TypeScript name DISABLE_DIAGNOSTICS=true works too, but only to turn them off. When the two disagree, off wins. AGENTCAT_DISABLE_DIAGNOSTICS=false turns them on in a test run.

​

Turn AgentCat on or off

​

Test runs

• A server that your test starts as a child process is not a test run: AgentCat tracks it and sends its events. Set AGENTCAT_ENABLED=false in the environment of that process.
• A production app that ships a test framework (one of them is in its dependencies) is a test run, so AgentCat stays off. Set AGENTCAT_ENABLED=true for that app.
• AGENTCAT_ENABLED=true in a test run turns AgentCat on, with real delivery. Diagnostics stay off unless AGENTCAT_DISABLE_DIAGNOSTICS=false.

​

Testing

using AgentCat;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.TestHost;
using Microsoft.Extensions.DependencyInjection;
using ModelContextProtocol.Client;
using Xunit;

public class EchoToolTests
{
    [Fact]
    public async Task The_echo_call_is_tracked()
    {
        var cancellationToken = TestContext.Current.CancellationToken;

        // First: in a test run, AgentCat is off until a fake is current
        using var fake = AgentCatSdk.Fake();

        var builder = WebApplication.CreateBuilder();
        builder.WebHost.UseTestServer();
        builder.Services.AddMcpServer()
            .WithHttpTransport(o => o.Stateless = true)
            .WithTools<MyTools>()
            .WithAgentCat("proj_YOUR_PROJECT_ID");

        await using var app = builder.Build();
        app.MapMcp();
        await app.StartAsync(cancellationToken);

        var transport = new HttpClientTransport(
            new HttpClientTransportOptions { Endpoint = new Uri("http://localhost/") },
            app.GetTestClient());
        await using var client = await McpClient.CreateAsync(transport, cancellationToken: cancellationToken);
        await client.CallToolAsync(
            "echo",
            new Dictionary<string, object?> { ["message"] = "hi" },
            cancellationToken: cancellationToken);

        await fake.AssertTrackedCountAsync(1, cancellationToken);
        await fake.AssertTrackedAsync(e => e.ResourceName == "echo", cancellationToken);
    }
}

• Create the fake first. A stdio or stateful HTTP server builds its server options once. When it built them while AgentCat was off, it stays untracked, and a failed tool-call assertion says so. A stateless HTTP server builds new server options for each request, so a stateless server in a shared fixture follows the fake of each test: AgentCat tracks it from its next request.
• One fake at a time. The fake is process-wide. Tests that use a fake must not run in parallel with each other, or with other tests that use AgentCat. In xUnit, put them in one test collection with DisableParallelization = true.
• No Clear(). Create a new fake in each test: a new fake becomes current and starts empty. Dispose it at the end of the test.
• After Dispose(), the newest fake that is not disposed becomes current, or none. The servers that you set up under the disposed fake record into the current fake, or AgentCat drops their events. They never send them. While no fake is current, a stateless server that you set up under a fake serves its requests unchanged: no get_more_tools, no injected parameters and no session text. A stdio or stateful server keeps these changes for its lifetime.
• AGENTCAT_ENABLED does not affect the fake. While a fake is current, FlushAsync and ShutdownAsync act on the queue of the fake.

​

Shutdown

• After the host stops (WithAgentCat()). AgentCat waits until every hosted service has stopped, the MCP stdio session and Kestrel included, so the events of tool calls that end during the stop are in the queue too. Then it sends the queued events for at most 5 seconds, and its last diagnostics batch for at most 1 second. It ignores the shutdown token of the host, so a stop can take up to 6 seconds longer than HostOptions.ShutdownTimeout. This flush does not close the queue: another host or server in the process keeps sending.
• At process exit (AppDomain.ProcessExit, WithAgentCat() and Track()). AgentCat closes the queue and sends the queued events, then its last diagnostics batch.
• On SIGTERM and SIGINT (Track() on .NET 8 and later). .NET 10 no longer raises ProcessExit on SIGTERM, so without these handlers a server without a host loses its queue on docker stop. The handlers send the queued events and never cancel the signal, so the process ends as usual, with its usual exit code. They do nothing when a handler that ran before them, the handler of a .NET host for example, cancelled the signal. WithAgentCat() adds no signal handler: the host owns the signals, and AgentCat flushes after the host stops.

​

About 6 seconds for a stop

​

What the stop paths need

• Microsoft.Extensions.Hosting 8 or later for the flush after the host stops: AgentCat runs it in IHostedLifecycleService.StoppedAsync. Older hosts and the legacy WebHost never call it, so they rely on the process-exit handler.
• A host. Only a host runs the flush. If you build and dispose a service provider yourself, call FlushAsync or ShutdownAsync before you dispose it.
• The first install decides. The first WithAgentCat() or Track() of the process, while AgentCat is on, adds the handlers: Track() adds the process-exit and signal handlers, and WithAgentCat() adds only the process-exit handler. DisableShutdownHandlers = true on that install adds none, and the flush after the host stops stays on. An install while a fake is current does not count.
• Signal order. .NET 8 calls signal handlers in the order of their registration, and .NET 10 calls the newest first. So the handler of Track() can run before the handler of a .NET host in the same process: on .NET 10 when the host started before Track(), and on .NET 8 when it started after it. AgentCat then sends the queued events first, and the graceful stop of the host starts up to 6 seconds later.

​

When no stop path runs

• SIGKILL and unhandled exceptions. No handler runs, and the queued events are lost.
• .NET Framework. All ProcessExit handlers of the process share 2 seconds, and AgentCat adds no signal handler.
• The official C# stdio client kills the server. When an McpClient over StdioClientTransport is disposed, it kills the server process instead of closing its input: at once on ModelContextProtocol 1.0 to 1.2, and after the ShutdownTimeout of the client on 1.3 and later. No flush runs, and the events that AgentCat has not sent by then are lost.

​

FlushAsync and ShutdownAsync

using AgentCat;

// Wait at most 2 seconds for the queued events, without closing the queue
bool sent = await AgentCatSdk.FlushAsync(TimeSpan.FromSeconds(2));

// Your own code ends the process: close the queue and send the queued events for at most 5 seconds
bool nothingLeft = await AgentCatSdk.ShutdownAsync();

• FlushAsync(timeout, cancellationToken) waits until AgentCat has delivered the queued events and sent their exporter requests. It returns true when nothing is left, and false when the timeout or the token ended the wait first. Without a timeout, it waits without a limit, and a negative timeout counts as zero. The token ends only the wait: AgentCat keeps sending.
• ShutdownAsync(cancellationToken) closes the process-wide queue, sends the queued events for at most 5 seconds, then sends the last diagnostics batch and waits at most 1 second for it. It returns true when nothing was left. After it, AgentCat drops every new event of the process, tool-call events included, and logs Queue is shutting down, event dropped for each. Call it once, when your own code ends the process. A second call waits for the same drain.