Bizrk.AgentLedger.Core 1.0.3

Bizrk Agent Ledger (.NET)

Agent Ledger is a runtime telemetry pipeline that enforces a strict boundary between library instrumentation and host environment configuration.

This is the C# equivalent of the @bizrk/agent-ledger TypeScript package, ensuring 1-to-1 parity for full-stack, chronologically perfect logging.

Core Philosophy

• Libraries emit structured entries only. They do not manage outputs, filters, or formatting.
• The Host Application owns all configuration and outputs.
• Strict Vocabulary: Uses a bounded set of semantic categories (app, action, network, flow, etc.).

Packages

Install the packages you need for your specific project layer:

dotnet add package Bizrk.AgentLedger.Core
dotnet add package Bizrk.AgentLedger.Hosting
dotnet add package Bizrk.AgentLedger.AspNetCore

• Core: Pure C#. Interfaces (IAgentLedger) and AsyncLocal context. Perfect for class libraries.
• Hosting: Sinks (Console, File, InMemory), AgentLedgerConfig, and MS DI registration.
• AspNetCore: AgentLedgerMiddleware (Support Mode Header parsing) and the secure /stream endpoint.

Quick Start (ASP.NET Core)

1. Configuration (appsettings.json)

{
  "AgentLedger": {
    "Enabled": true,
    "Level": "Debug",
    "Categories": ["app", "flow", "action", "error", "engine"],
    "Console": { "Enabled": true },
    "File": { "Enabled": true, "Path": "agentledger.log" }
  }
}

2. Bootstrapping (Program.cs)

using Bizrk.AgentLedger.Hosting;
using Bizrk.AgentLedger.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAgentLedger(builder.Configuration);
builder.Logging.AddAgentLedgerBridge(); // Pipes standard ILogger traffic into Agent Ledger

var app = builder.Build();

app.UseAgentLedgerContext(); // Reads X-Agent-Ledger-Session-Id headers
app.MapAgentLedgerEndpoints().RequireAuthorization(); // Exposes /api/system/agent-ledger/stream

app.Run();

3. Usage

public class OrderService
{
    private readonly IAgentLedger _logger;

    public OrderService(IAgentLedger ledger)
    {
        _logger = ledger.Scope("OrderService", LogCategory.Flow);
    }

    public void Process()
    {
        _logger.Info("Processing started");
    }
}

4. Custom Enterprise Sinks (Azure, Datadog) Do not pipe Agent Ledger logs back into standard .NET ILogger. Doing so creates infinite loops (since standard logs are piped into Agent Ledger) and destroys the highly structured JSON payloads.

To integrate with enterprise observability platforms, create a custom IAgentLedgerSink:

public class AzureAppInsightsSink : IAgentLedgerSink
{
    public void Emit(LedgerEntry entry)
    {
        // Send structured JSON perfectly to Azure
        _telemetry.TrackTrace(entry.Message, entry.Level, new Dictionary<string, string> {
            { "SessionId", entry.SessionId },
            { "Category", entry.Category.ToString() }
        });
    }
}

Register it via DI:

builder.Services.AddSingleton<IAgentLedgerSink, AzureAppInsightsSink>();