Diagnostics and Instrumentation

Polecat provides several tools for monitoring, debugging, and understanding what's happening in your application.

Session Logging

IPolecatLogger

Implement IPolecatLogger at the store level to create per-session loggers:

public class ConsolePolecatLogger : IPolecatLogger
{
    public IPolecatSessionLogger StartSession(IQuerySession session)
    {
        return new ConsoleSessionLogger();
    }
}

public class ConsoleSessionLogger : IPolecatSessionLogger
{
    public void OnBeforeExecute(string sql)
    {
        Console.WriteLine($"Executing: {sql}");
    }

    public void LogSuccess(string sql)
    {
        Console.WriteLine($"Success: {sql}");
    }

    public void LogFailure(string sql, Exception ex)
    {
        Console.WriteLine($"Failed: {sql} - {ex.Message}");
    }

    public void RecordSavedChanges(IDocumentSession session)
    {
        Console.WriteLine($"Saved changes ({session.RequestCount} requests)");
    }
}

Register the logger:

opts.Logger(new ConsolePolecatLogger());

Request Counting

Track database requests per session:

await using var session = store.LightweightSession();
await session.LoadAsync<User>(id);
Console.WriteLine(session.RequestCount); // 1

SQL Preview

ToSql

Preview the SQL generated by a LINQ query:

var sql = session.Query<User>()
    .Where(x => x.LastName == "Smith")
    .ToSql();

Console.WriteLine(sql);
// SELECT data FROM pc_doc_user WHERE JSON_VALUE(data, '$.lastName') = @p0

Schema Diagnostics

ToDatabaseScript

Generate the complete DDL script for all Polecat tables:

var script = await store.Advanced.ToDatabaseScript();
Console.WriteLine(script);

WriteCreationScriptToFileAsync

Save the schema script to a file:

await store.Advanced.WriteCreationScriptToFileAsync("/path/to/schema.sql");

Data Cleanup

CleanAllDocumentsAsync

Delete all data from all document tables:

await store.Advanced.CleanAllDocumentsAsync();

CleanAsync

Delete all data from a specific document table:

await store.Advanced.CleanAsync<User>();

CleanAllEventDataAsync

Delete all event data (events, streams, progressions):

await store.Advanced.CleanAllEventDataAsync();

WARNING

These cleanup methods permanently delete data. They are intended for testing and development, not production use.

Projection Daemon Monitoring

Extended Progression Tracking

Polecat can extend its event-progression table (pc_event_progression) with additional columns that the asynchronous projection daemon uses to report per-shard health — the same surface monitoring tools such as CritterWatch read to show heartbeat liveness, agent status, pause reasons, and per-shard alert thresholds.

Opt in via the event store options:

var store = DocumentStore.For(opts =>
{
    opts.Connection("...");
    opts.Events.EnableExtendedProgressionTracking = true;
});

When enabled, the next schema apply adds six nullable columns to pc_event_progression (heartbeat, agent_status, pause_reason, running_on_node, warning_behind_threshold, critical_behind_threshold); the daemon writes its runtime agent state to them, and they are read back into JasperFx.Events.Projections.ShardState. The default is false, in which case no extra columns are created.

StoreOptions.Events also implements the storage-agnostic JasperFx.Events.IEventStoreInstrumentation interface, whose ExtendedProgressionEnabled property is an alias for EnableExtendedProgressionTracking. This lets store-agnostic tooling toggle the same monitoring fidelity across Marten and Polecat without referencing store-specific types:

IEventStoreInstrumentation instrumentation = store.Options.Events;
instrumentation.ExtendedProgressionEnabled = true;