Dot.Inscribe 1.0.0

Dot.Inscribe

A lightweight helper library for configuring Serilog in ASP.NET Core apps with sensible defaults, a simple fluent builder, HTTP request logging, and common enrichers.

Highlights:

• Fluent builder to configure sinks (Console, File, SQL Server, optional Splunk HEC) and enrichers (CorrelationId, Activity Span, HttpContext basics, Machine/Thread).
• Request logging built on Serilog.AspNetCore with optional request/response body capture, header redaction, path/status level overrides, sampling helpers, and ignore lists.
• Options to tailor SQL Server sink columns and add additional varchar columns.

Compatibility:

• Target framework: .NET 9.0
• Core dependencies: Serilog 4.x, Serilog.AspNetCore 8.x, Serilog.Enrichers.Environment, Serilog.Enrichers.Thread
• Optional: Serilog.Sinks.MSSqlServer, Serilog.Sinks.Splunk

What Dot.Inscribe does for you:

• Registers Serilog and wires it into Microsoft.Extensions.Logging (MEL) with a single Build(configuration) call.
• Automatically registers required DI services: IHttpContextAccessor, Serilog.Extensions.Hosting DiagnosticContext, and Serilog.ILogger for compatibility with Serilog.AspNetCore’s RequestLoggingMiddleware.
• Provides a single place to configure sinks and enrichers without Host.UseSerilog().

Installation

Until published to NuGet, add a project reference to Dot.Inscribe. When available on NuGet, you can install it via:

• dotnet CLI: dotnet add package Dot.Inscribe
• Package Manager: Install-Package Dot.Inscribe

Quick Start

Program.cs (minimal hosting):

using Dot.Inscribe;
using Serilog.Events;

var builder = WebApplication.CreateBuilder(args);

// 1) Register Dot.Inscribe builder
var inscribe = builder.Services.AddDotInscribe()
    .WriteToConsole()
    .WriteToFile(o => o.Path("logs/app-.log").RollingDaily().Retain(7))
    .EnrichWithMachineAndThread()
    .EnrichWithHttpContext()
    .EnrichWithCorrelation()
    .EnrichWithSpan()
    .MinimumLevel(LogEventLevel.Information)
    .Override("Microsoft.AspNetCore", LogEventLevel.Warning);

// 2) Build Serilog and wire it into Microsoft.Extensions.Logging
inscribe.Build(builder.Configuration);

var app = builder.Build();

// 3) Enable HTTP request logging with optional body capture
app.UseDotRequestLogging(o => o
    .MessageTemplate("HTTP {RequestMethod} {RequestPath} responded {StatusCode} in {Elapsed:0.0000} ms")
    .IncludeRequestBodyWhen("application/json", 2048)
    .IncludeResponseBody(2048)
    .RedactCommonAuthHeaders()
);

app.MapGet("/", () => Results.Ok(new { Hello = "world" }));

app.Run();

Middleware ordering tips:

• Place UseDotRequestLogging early in the pipeline, after exception handling and before endpoints.
• If you use other middleware that affect the response body, ensure they’re compatible with body capture.

Sinks

Console

.WriteToConsole()

File

.WriteToFile(o => o
    .Path("logs/app-.log")
    .RollingDaily()
    .Retain(7)
)

• Path: file path (supports Serilog rolling template like app-.log)
• RollingDaily: use daily rolling files
• Retain: approximate retention (retainedFileCountLimit)

In the included Demo, logs are written to Dot.Inscribe.Demo/logs/demo-YYYYMMDD.log with a 7-day retention.

SQL Server (optional)

inscribe.WriteToSqlServer(o => o
    .Connection(builder.Configuration.GetConnectionString("Logs")!)
    .Schema("dbo")
    .Table("Logs")
    .AutoCreateTable()
    .Columns(c => c
        .UseStandard(level: true, message: true, timestamp: true, exception: true, properties: true)
        .AddVarchar("RequestPath", 512)
        .AddVarchar("CorrelationId", 64)
    )
);

Notes:

• Column selection is applied via the sink’s ColumnOptions.Store collection. Additional varchar columns are appended.

Splunk HEC (optional)

This extension uses reflection and only works if Serilog.Sinks.Splunk is referenced by your app.

inscribe.WriteToSplunkHec(o =>
{
    o.Host = "https://splunk:8088/services/collector";
    o.Token = "<hec-token>";
    o.Index = "main";        // optional
    o.Source = "dot-inscribe"; // optional
    o.SourceType = "_json";   // optional
    o.MinimumLevel = Serilog.Events.LogEventLevel.Information;
    o.BatchSizeLimit = 1000;
    o.Period = TimeSpan.FromSeconds(2);
});

If the Splunk sink package is missing, this call is safely ignored.

Enrichers

• EnrichWithCorrelation(string headerName = "X-Correlation-ID"): Adds CorrelationId from request header, W3C traceparent, or TraceIdentifier.
• EnrichWithSpan(): Adds TraceId and SpanId from System.Diagnostics.Activity.Current.
• EnrichWithHttpContext(): Adds RequestMethod, RequestPath, and ClientIp when available.
• EnrichWithMachineAndThread(): Adds EnvironmentName, MachineName, and ThreadId.

Levels and Overrides

• MinimumLevelInformation() or MinimumLevel(LogEventLevel level)
• Override(source, level) to adjust noisy components, e.g.:

.MinimumLevel(Serilog.Events.LogEventLevel.Information)
.Override("Microsoft.AspNetCore", Serilog.Events.LogEventLevel.Warning)

Request Logging

Request logging integrates Serilog.AspNetCore with extra context and optional body/header capture.

Default message template:

• "HTTP {RequestMethod} {RequestPath} responded {StatusCode} in {Elapsed:0.0000} ms"

Options (fluent):

app.UseDotRequestLogging(o => o
    .MessageTemplate("HTTP {RequestMethod} {RequestPath} responded {StatusCode} in {Elapsed:0.0000} ms")
    // Body capture
    .IncludeRequestBody(1024)                         // global limit
    .IncludeRequestBodyWhen("application/json", 2048) // per content type limit
    .IncludeResponseBody(2048)
    // Header redaction
    .RedactHeaders("Authorization", "Cookie")
    .RedactCommonAuthHeaders()
    .RedactCloudHeaders()
    .RedactSecrets()
    // Level control helpers
    .LevelForPathStartsWith("/health", Serilog.Events.LogEventLevel.Debug)
    .LevelForStatusCode(500, Serilog.Events.LogEventLevel.Error)
    // Future-friendly helpers (no filtering hook in Serilog.AspNetCore v8)
    .IgnorePathStartsWith("/health", "/metrics", "/swagger")
    .SampleRequests(0.1)
);

Captured properties include: RequestMethod, RequestPath, StatusCode, ClientIp, Host, Scheme, Protocol, ContentLength, UserAgent, Referer, CorrelationId, TraceId, SpanId, RequestHeaders (redacted), RequestBody, ResponseBody (when enabled).

Security and performance:

• Capturing bodies impacts memory/CPU; keep limits low in production and prefer per-content-type capture.
• Only UTF-8 text is captured, truncated to the configured size.
• Redact Authorization, Cookie, and other secrets. Use provided helpers.

Configuration and DI Notes

• Build(IConfiguration) wires Serilog into MEL and clears default providers. It applies only the fluent configuration; it does not bind appsettings.json automatically.
• AddDotInscribe() registers IHttpContextAccessor, Serilog.Extensions.Hosting DiagnosticContext, and Serilog.ILogger in DI to ensure Serilog.AspNetCore’s RequestLoggingMiddleware can resolve its dependencies without Host.UseSerilog().
• You can still extend the LoggerConfiguration via internal hooks (used in tests) or by adding sinks through the fluent API.

Troubleshooting

• No logs? Ensure inscribe.Build(...) is called before builder.Build(), and that at least one sink is configured.
• Splunk not logging? Ensure Serilog.Sinks.Splunk is referenced; otherwise the Splunk extension is a no-op.
• SQL sink issues? Verify the connection string, table/schema, and enable AutoCreateTable for first run.
• "Synchronous operations are disallowed" in tests: the response copying stream avoids synchronous Flush; ensure your own middleware doesn’t force sync I/O.

Demo

See Dot.Inscribe.Demo/Program.cs for a working minimal API demonstrating:

• Console + rolling daily file logging to logs/demo-.log (7-day retention).
• Request logging with JSON body capture, header redaction, and error level override for 500s.
• Swagger endpoints.

Development and Tests

An xUnit test project (Dot.Inscribe.Tests) is included.

Run tests:

dotnet test

License

MIT (assumed). Update as needed.