InvertedSoftware.PLogger

From log sink to diagnostic engine. Sentry, Seq, App Insights, and Datadog tell you what broke and where. PLogger 2.0 tells you what to change in code to fix it — every error becomes a structured diagnostic with an LLM-generated root-cause hypothesis, a concrete proposed code change as a unified diff, and a confidence/risk score, queryable via SQL and exposed as an MCP server so Claude Code, Copilot, or any agent can pull production diagnostics directly into the editor.

• What's new in 2.0
• Architecture at a glance
• Solution layout
• Quick start
• Configuration reference
• Per-package guide
  • Core
  • Diagnostics
  • Diagnostics.SqlServer
  • Diagnostics.SourceLink
  • Diagnostics.AI
  • Diagnostics.Agents
  • Diagnostics.Mcp
  • Diagnostics.GitHub / Slack / Teams
• Sample app
• Building and testing
• Privacy and cost rails
• Roadmap
• Upgrade guide from 1.x
• License

PLogger 2.0 is a ground-up modernization of the 1.x library while remaining a drop-in upgrade for existing consumers. The original appsettings.json keys all keep working unchanged, and loggerFactory.AddPLogger(Configuration) still does what it always did.

                                                   ┌──────────────────────────────┐
                                                   │      Microsoft.Extensions.AI │
                                                   │      IChatClient (provider   │
                                                   │      pluggable: OpenAI /     │
                                                   │      Azure / Ollama / Foundry│
                                                   │      Local / etc.)           │
                                                   └──────────────┬───────────────┘
                                                                  │
ILogger.LogError(ex,…)                                            ▼
        │                                          ┌──────────────────────────────┐
        ▼                                          │  Diagnostics.Agents          │
┌──────────────┐    bounded     ┌────────────────┐ │  Triage → Context →          │
│   PLogger    │── Channel ────▶│ PLoggerDrain   │ │  Diagnosis → Fix →           │
│  (hot path)  │    (8192,      │ Service        │ │  Validator                   │
│              │    DropOldest) │  (single rdr)  │ └──────────────┬───────────────┘
│ <1 alloc/call│                │                │                │
│ no I/O       │                │  fan-out       │                ▼
│ no blocking  │                │  to N sinks ─┐ │ ┌──────────────────────────────┐
└──────────────┘                └──────────────┴─┴▶│  Diagnostics.SourceLink      │
        ▲                                          │  (PortablePDB → SourceSnippet)│
        │                                          └──────────────┬───────────────┘
        │                                                         ▼
   Activity.Current.TraceId / SpanId           ┌──────────────────────────────────┐
   (auto-captured)                             │   Diagnostics pipeline:          │
                                               │   capture sink → 2nd channel →   │
                                               │   enrich → vector dedup gate →   │
                                               │   diagnose → persist → notify    │
                                               └──────────────────┬───────────────┘
                                                                  │
                              ┌───────────────────────────────────┼─────────────────────┐
                              ▼                                   ▼                     ▼
              ┌──────────────────────────┐    ┌────────────────────────┐   ┌────────────────────┐
              │   File / SQL sink        │    │ Diagnostics.SqlServer  │   │ Notifiers (opt):   │
              │   (Phase 1)              │    │  plogger.Diagnostics   │   │  GitHub / Slack /  │
              │   plogger.txt /          │    │  + DiagnosticOcc.      │   │  Teams             │
              │   sproc                  │    │  + VECTOR(1536) for    │   │  (idempotent)      │
              └──────────────────────────┘    │  similarity dedup      │   └─────────┬──────────┘
                                              └───────────┬────────────┘             │
                                                          ▼                          ▼
                                              ┌─────────────────────────┐  ┌──────────────────┐
                                              │ Diagnostics.Mcp server  │  │  Webhook /       │
                                              │ (ASP.NET Core 10        │  │  GitHub issues   │
                                              │  endpoint at            │  │  with proposed   │
                                              │  /mcp/diagnostics)      │  │  diff + risk     │
                                              │                         │  └──────────────────┘
                                              │  Tools:                 │
                                              │   get_diagnosis         │  ◀───── Claude Code
                                              │   mark_fix_applied      │  ◀───── Copilot
                                              │   list_tools            │  ◀───── any MCP agent
                                              └─────────────────────────┘

Key invariants (apply at every layer):

1. Logger invariant. A failure anywhere downstream (enrichment, fingerprinting, AI, store, notifier) never bubbles into ILogger.Log. The basic log write always succeeds.
2. Hot-path budget. No I/O, no allocation beyond the LogEvent. All work happens in background services downstream of the channel.
3. Backward compatibility. Any 1.x consumer is a PackageReference bump.

/src
  InvertedSoftware.PLogger.Core/                   the modernized provider — channel pipeline, sinks
  InvertedSoftware.PLogger.Diagnostics/            abstractions: records, interfaces, capture sink, pipeline service
  InvertedSoftware.PLogger.Diagnostics.SqlServer/  SQL Server 2025 store with VECTOR(1536) similarity search
  InvertedSoftware.PLogger.Diagnostics.SourceLink/ stack-frame → source-code resolver
  InvertedSoftware.PLogger.Diagnostics.AI/         IChatClient single-prompt diagnosis + redaction + token budget
  InvertedSoftware.PLogger.Diagnostics.Agents/     multi-agent pipeline (Triage / Context / Diagnosis / Fix / Validator)
  InvertedSoftware.PLogger.Diagnostics.Mcp/        MCP server exposing diagnostics to dev-time AI agents
  InvertedSoftware.PLogger.Diagnostics.GitHub/     GitHub issue + PR notifier with fingerprint-keyed idempotency
  InvertedSoftware.PLogger.Diagnostics.Slack/      Slack incoming-webhook notifier (Block Kit)
  InvertedSoftware.PLogger.Diagnostics.Teams/      Microsoft Teams incoming-webhook notifier (Adaptive Card)
/tests
  InvertedSoftware.PLogger.Core.Tests/             xUnit v3 — hot path, channel, drain, fingerprinter, back-compat
  InvertedSoftware.PLogger.Core.Benchmarks/        BenchmarkDotNet — LogError hot-path allocation + latency
  InvertedSoftware.PLogger.Diagnostics.Tests/      unit + Testcontainers SQL Server integration tests
/samples
  InvertedSoftware.PLogger.Sample.Web/             minimal-API .NET 10 demo (/health, /log, /throw, /diagnose, /mcp/...)

Apache-2.0 licensed; central-package-managed via Directory.Packages.props.

dotnet add package InvertedSoftware.PLogger.Core --version 2.0.0-preview.1

using Microsoft.Extensions.Logging;

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddPLogger();   // reads "Logging:PLogger" section of appsettings.json
var app = builder.Build();

Or via the v1 surface (ILoggerFactory):

loggerFactory.AddPLogger(Configuration);

appsettings.json:

{
  "Logging": {
    "LogLevel": { "Default": "Information" },
    "PLogger": {
      "PLogType": "file",
      "BaseNameFile": "plogger.txt",
      "PLogFileMaxSizeKB": 1024
    }
  }
}

That's it — every error logged via ILogger flows through the channel, lands in plogger.txt, with OTel TraceId/SpanId correlation captured automatically.

var diag = builder.Logging.AddPLogger()
    .AddPLoggerDiagnostics()                        // Phase 2: capture pipeline
    .AddSqlServerStore()                            // Phase 2: SQL Server 2025 store
    .AddPLoggerSourceLink(o => o.AllowedNamespaces  // Phase 3: source resolver
        = new[] { "MyCompany.*" })
    .AddPLoggerAi()                                 // Phase 3: single-prompt LLM
    // .AddPLoggerMultiAgent()                      // Phase 4: replaces single-prompt with Triage/Diagnosis/Fix/Validator
    .AddPLoggerMcpServer()                          // Phase 5: MCP endpoint
    .AddGitHubNotifier()                            // Phase 6: file issues / PRs
    .AddSlackNotifier()                             //         Block Kit cards
    .AddTeamsNotifier();                            //         Adaptive Cards

// (caller registers the IChatClient via Microsoft.Extensions.AI separately)
builder.Services.AddChatClient(/* OpenAI / Azure / Ollama / etc. */);

Each Add* is opt-in and reads its own configuration section under Logging:PLogger:Diagnostics. Calling none of them = identical behaviour to PLogger 1.x.

Every configuration value below is bound through hand-rolled IConfigureOptions<T> (no ConfigurationBinder.Bind reflection) and hot-reloads via IOptionsMonitor<T> change-token sources.

The provider. Contains PLogger (hot path), PLoggerProvider (ILoggerProvider), PLoggerChannel (bounded Channel<LogEvent>), PLoggerDrainService (single-reader BackgroundService), RollingFileLogSink, SqlLogSink, LogEvent, LogEventFormatter, StackFingerprinter, every legacy AddPLogger(...) overload preserved.

builder.Logging.AddPLogger();

public sealed record LogEvent(
    DateTimeOffset TimestampUtc,
    LogLevel Level,
    string Category,
    EventId EventId,
    string Message,
    Exception? Exception,
    IReadOnlyList<KeyValuePair<string, object?>> Scope,
    string? TraceId,
    string? SpanId);

using InvertedSoftware.PLogger.Core.Fingerprinting;

byte[] hash         = StackFingerprinter.Compute(ex);    // 16 bytes (xxHash3, BINARY(16) compatible)
string normalized   = StackFingerprinter.Normalize(ex);  // input to the hash; safe to log

Normalization rules:

• Strips line numbers, IL offsets, file paths.
• Collapses generic args to arity (List1[Int32]→List1).
• Strips lambda display classes (<>c__DisplayClass3_0 → <display>).
• Strips async state-machine machinery (<Method>d__N, MoveNext, Mono <>c__AnonStorey\d+, <>c__Iterator\d+, etc.).
• Walks InnerException chain with a delimiter.

Two exceptions with identical normalized stacks fingerprint identically across runs, machines, and CoreCLR ↔ Mono.

Abstractions: LogEvent enrichment to DiagnosticContext, fingerprinting, the IDiagnosticPipeline orchestrator, DiagnosticCaptureSink (the second sink that pushes onto a separate channel), DiagnosticPipelineService (its single reader), IDiagnosticEnricher / IDiagnosticAgent / IDiagnosticStore / IDiagnosticNotifier / ITokenBudgetEnforcer / IPiiScanner extension points.

builder.Logging.AddPLogger().AddPLoggerDiagnostics(o =>
{
    o.AppName = "OrderService";
    o.Environment = "Production";
    o.MinSeverity = LogLevel.Error;
});

SQL Server 2025 backing store. Idempotent schema (plogger.Diagnostics + plogger.DiagnosticOccurrences), MERGE-based upsert keyed on (AppName, Environment, Fingerprint), OccurrenceCount increments on dedup hit, native VECTOR(1536) for similarity search via JSON_ARRAY_TO_VECTOR(@vec, 1536) + VECTOR_DISTANCE('cosine', col, vec).

builder.Logging.AddPLogger().AddPLoggerDiagnostics()
    .AddSqlServerStore(o =>
    {
        o.ConnectionString = "Server=...;Database=...;Authentication=Active Directory Default";
        o.ApplySchemaOnStartup = true;
    });

The schema file is embedded as Schema/0001_initial.sql and applied idempotently at host start; it's also safe to apply via your own migration tooling (it uses IF NOT EXISTS guards everywhere).

Walks Exception.StackTrace, gates frames by AllowedNamespaces (defense-in-depth — empty allow-list = nothing resolves), reads the local source span when reachable. AOT-safe namespace extraction via System.Diagnostics.DiagnosticMethodInfo (the trim-safe alternative to StackFrame.GetMethod()).

builder.Logging.AddPLogger().AddPLoggerDiagnostics()
    .AddPLoggerSourceLink(o =>
    {
        o.AllowedNamespaces = new[] { "MyCompany.*" };
        o.ContextLines = 5;
    });

When registered, replaces the default IDiagnosticEnricher with one that populates DiagnosticContext.Source for any frame inside the allow-list whose source file is reachable on disk.

Single-prompt LLM diagnosis on top of Microsoft.Extensions.AI's IChatClient.

• Redaction via [GeneratedRegex] patterns: AWS / Azure / GCP / generic Bearer API keys, JWTs, ADO.NET / MongoDB / PostgreSQL connection strings, password key/value pairs, emails, IPv4/IPv6, SSNs, Luhn-validated credit cards. Patterns are deliberately over-aggressive — false positives become <redacted-{kind}> tags; false negatives are never tolerated.
• Token budget via ITokenBudgetEnforcer (sliding 60-second window, lock-free reservation, refundable on cancellation).
• Structured outputs via JsonSerializerContext source generators — no regex parsing of LLM responses.
• Vector dedup gate — IDiagnosticStore.FindSimilarAsync(embedding, threshold=0.92) short-circuits the LLM call when a similar prior diagnosis exists.
• Startup validator that throws an actionable error message at host start if IChatClient isn't registered.

builder.Services.AddChatClient(/* OpenAI / Azure / Ollama / Foundry Local */);
builder.Logging.AddPLogger().AddPLoggerDiagnostics()
    .AddSqlServerStore()
    .AddPLoggerSourceLink(o => o.AllowedNamespaces = new[] { "MyCompany.*" })
    .AddPLoggerAi(o =>
    {
        o.Model = "gpt-5-mini";
        o.TokenBudgetPerMinute = 100_000;
    });

AOT note: This package is IsAotCompatible=false because Microsoft.Extensions.AI uses reflection on response shapes. Every other Diagnostics package stays AOT-clean.

Replaces AiDiagnosisAgent with a five-stage orchestrator: Triage → Context → Diagnosis → Fix → Validator.

If ValidatorAgent rejects, the orchestrator can retry the FixAgent once (configurable). Each stage is gated by ITokenBudgetEnforcer.

.AddPLoggerMultiAgent(o =>
{
    o.TriageModel = "gpt-5-mini";
    o.FrontierModel = "claude-opus-4-7";
    o.FixRetryCount = 1;
})

MCP server hosted in ASP.NET Core 10 minimal API. The marketing wedge: when a developer asks Claude Code "fix the bug in the order service," the agent calls these tools and pulls full root-cause hypotheses + proposed diffs into the editor.

Tools exposed:

(Phase 5.x adds get_recent_diagnostics, find_similar, list_unresolved, get_recent_logs.)

Wire it up in any ASP.NET Core 10 app:

builder.Logging.AddPLogger().AddPLoggerDiagnostics()
    .AddSqlServerStore(o => o.ConnectionString = "...")
    .AddPLoggerMcpServer(o =>
    {
        o.Enabled = true;
        o.RoutePrefix = "/mcp/diagnostics";
        o.BearerToken = builder.Configuration["MCP_BEARER"]; // constant-time compared
    });

var app = builder.Build();
app.MapPLoggerMcp();   // mounts at the configured route prefix

Connect Claude Code to the running server with this .mcp.json:

{
  "mcpServers": {
    "plogger": {
      "type": "http",
      "url": "https://your-app.example.com/mcp/diagnostics",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Notifier sinks that the pipeline calls after a successful persist. All three are independently optional and fan out in parallel; one failing notifier never blocks the others.

Title carries a [plogger-fp:<HEX>] tag the search API uses to find existing issues before creating a new one. Per-request HttpRequestMessage headers (no shared DefaultRequestHeaders mutation, so concurrent fan-outs can't race or leak the bearer token).

.AddGitHubNotifier(o =>
{
    o.Repository = "myorg/myapp";
    o.Token = builder.Configuration["GITHUB_TOKEN"];
    o.Labels = new[] { "plogger", "auto-filed", "production" };
    o.MinOccurrenceCount = 5;   // wait until it's actually a recurring issue
})

.AddSlackNotifier(o =>
{
    o.WebhookUrl = builder.Configuration["SLACK_WEBHOOK"];
    o.AppDisplayName = "OrderService Production";
})

.AddTeamsNotifier(o =>
{
    o.WebhookUrl = builder.Configuration["TEAMS_WEBHOOK"];
})

All three notifiers also use a shared bounded LRU RecentSet (15-min TTL, 256 entries) to dedupe rapid in-process repeats of the same fingerprint between channel-flush cycles — the SQL store does the authoritative dedup; this just stops a tight error loop from spamming external endpoints.

samples/InvertedSoftware.PLogger.Sample.Web is a minimal-API .NET 10 demo that exercises every layer.

cd samples/InvertedSoftware.PLogger.Sample.Web
dotnet run -c Release

Endpoints:

End-to-end dedup demo:

curl http://localhost:5099/throw/fingerprint
# {"fingerprintHex":"3E1DF2C149245AABA0D1C06EC6F99722"}

for i in {1..50}; do curl -s -o /dev/null http://localhost:5099/throw; done

curl http://localhost:5099/diagnostics/3E1DF2C149245AABA0D1C06EC6F99722
# DiagnosticRecord with OccurrenceCount=50, FirstSeenUtc, LastSeenUtc, ...

Requires .NET 10 SDK (global.json pins 10.0.100 with latestMinor roll-forward).

dotnet build InvertedSoftware.PLogger.slnx -c Release
dotnet test  InvertedSoftware.PLogger.slnx -c Release

Currently: 9 packages, 71 tests passed, 1 skipped (Docker-dependent SQL Server integration test), 0 failed, 0 build warnings.

Run the BenchmarkDotNet suite:

dotnet run --project tests/InvertedSoftware.PLogger.Core.Benchmarks -c Release -- --filter '*HotPath*'

Hot-path target — verified: 104 bytes per LogError call (just the LogEvent record), no Gen1 pressure under sustained load.

The Testcontainers SQL Server integration test (SqlServerStoreIntegrationTests) runs against mcr.microsoft.com/mssql/server:2022-latest; it's auto-skipped when the Docker daemon isn't reachable. To exercise it, install Docker Desktop (Windows / macOS) or a Docker Engine (Linux) and re-run dotnet test.

The library packages that are AOT-clean (Core, Diagnostics, Diagnostics.SqlServer's analyzer pass aside, Diagnostics.SourceLink, Diagnostics.GitHub, Diagnostics.Slack, Diagnostics.Teams) all carry <IsAotCompatible>true</IsAotCompatible>. The application:

dotnet publish samples/InvertedSoftware.PLogger.Sample.Web -c Release -p:PublishAot=true

(Requires the Visual Studio Desktop Development for C++ workload on Windows for the linker.)

The Diagnostics.AI, Diagnostics.Agents, and Diagnostics.Mcp packages opt out of AOT (their dependencies — Microsoft.Extensions.AI, the MCP SDK — use reflection on response shapes). Including them in an AOT-published app is not currently supported.

Hard requirements baked into Phase 3+ — without these, the framework is unshippable in regulated industries.

Phase 4.x (next milestone): expose the full ContextAgent tool surface (ReadSourceFile, FindSimilarErrors, GetGitBlame, GetOtelTrace, GetRecentLogs) so the diagnosis stage has rich grounding rather than just the source span.

Phase 5.x: complete the MCP tool surface (get_recent_diagnostics, find_similar, list_unresolved, get_recent_logs).

For consumers of PLogger 1.x: upgrading is a PackageReference version bump. No code changes, no config changes.

<PackageReference Include="InvertedSoftware.PLogger.Core" Version="2.0.0-preview.1" />

Every key in the original appsettings.json keeps working unchanged. Every existing AddPLogger(...) overload (on ILoggerFactory and ILoggingBuilder, with and without IConfiguration / PLoggerSettings / LogLevel parameters) keeps the same signatures. PLoggerSettings itself remains as a back-compat shim around the new PLoggerOptions.

Original v1 configuration table — kept verbatim for documentation continuity:

Apache-2.0 — see LICENSE. Copyright 2020 Inverted Software (Gal Ratner).

The patent grant in Apache-2.0 is intentional given the agent / fix-proposal IP in Phase 3+.

Issues and pull requests welcome at github.com/invertedsoftware/InvertedSoftware.PLogger.Core.

Conventional-commit messages preferred (feat(core): …, fix(diagnostics): …, docs: …). Each commit should pass dotnet build -c Release (zero warnings — TreatWarningsAsErrors is on) and dotnet test.