Pacem.Extensions.Logging.Http 0.10.18-pascal

HTTP Logging Extensions

⚗️ ==Experimental==

⚠️ Experimental libs are discouraged to use in production.

About

Pacem.Extensions.Logging.Http provides extensions to ship your logs to an HTTP endpoint (a webhook, a log-ingestion API, a collector, ...).

Delivery goes through an HttpClient (from IHttpClientFactory) and is performed by a background consumer, one entry at a time, so logging calls never block on the network.

⚠️ The IHttpClientFactory pipeline logs its own requests under the System.Net.Http.* categories. Left unfiltered those entries feed straight back into this sink and amplify without bound — scope the sink to the categories you actually care about (builder.AddFilter(...) or the filter argument) or silence System.Net.Http.

⚠️ The sink does not own its HttpClient. Point clientFactory at a client you configured (AddHttpClient), or emit absolute URIs and headers from your converter/executor. The no-clientFactory fallback is the default IHttpClientFactory client, which is unconfigured unless you set it up app-wide with ConfigureHttpClientDefaults.

The following paragraphs exemplify the library utilization given common use cases.

How to

Add the logger to the logging builder (e.g. ILoggingBuilder). There are two ways to describe a delivery, and two ways to supply the HttpClient.

1. Converter mode — build the request, the sink sends it

Provide a HttpRequestLogPayload -> HttpRequestMessage converter.

// Program.cs
builder.Logging.AddPacemHttpLogging(
    // log line -> request
    log => new HttpRequestMessage(HttpMethod.Post, "/ingest")
    {
        Content = JsonContent.Create(new
        {
            timestamp = log.Timestamp,
            source = log.Name,
            level = log.LogLevel.ToString(),
            message = log.Message,
            error = log.Exception?.ToString(),
            data = log.Data
        })
    });

2. Executor mode — you own the send

Provide a (HttpClient, HttpRequestLogPayload) -> Task. Handy when you call an SDK, batch differently, or need the response.

builder.Logging.AddPacemHttpLogging(
    async (client, log) =>
    {
        using var response = await client.PostAsJsonAsync("/ingest", new
        {
            source = log.Name,
            level = log.LogLevel.ToString(),
            message = log.Message
        });
        response.EnsureSuccessStatusCode();
    });

Supplying the HttpClient

Both modes take the same two optional arguments after the delivery delegate:

The recommended way to give the sink a base address, default headers, a primary handler or Polly policies is to configure your own client and select it with clientFactory:

builder.Services.AddHttpClient("my-logs", c =>
{
    c.BaseAddress = new Uri("https://logs.example.com");
    c.DefaultRequestHeaders.Add("X-Api-Key", "…");
});

builder.Logging.AddPacemHttpLogging(
    log => new HttpRequestMessage(HttpMethod.Post, "/ingest") { /* … */ },
    clientFactory: (factory, log) => factory.CreateClient("my-logs"),
    // don't ship our own transport noise back over HTTP
    filter: log => !log.Name.StartsWith("System.Net.Http"));

Without clientFactory the sink uses the default IHttpClientFactory client, so the converter/executor must produce absolute URIs (and set any headers on the request itself), unless you configure the default client app-wide:

builder.Services.ConfigureHttpClientDefaults(b =>
    b.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://logs.example.com")));

3. Full control

builder.Logging.AddPacemHttpLogging(options =>
{
    options.FormatHttpRequestMessage = log => /* ... */;   // or options.SendHttpLogAsync
    options.CreateHttpClient = (factory, log) => factory.CreateClient("my-configured-client");
    options.Filter = log => log.LogLevel >= LogLevel.Warning;
});

ℹ️ Set at least one of FormatHttpRequestMessage / SendHttpLogAsync — otherwise the sink throws on the first write.

Plans for version next

Optional client-side batching and a retry / dead-letter policy.