pinqloq 4.3.2

Pinqloq

Pinqloq is an ASP.NET Core structured logging and log shipping SDK for centralized application logs. It captures HTTP request/response logs through middleware and sends manual application events to the Pinqloq log management platform using in-memory buffering, batching, and HTTPS delivery.

Features

• Automatic ASP.NET Core request logging
• Correlation id read from the caller's header, falling back to the trace id
• Attribute-based redaction of sensitive fields and endpoints
• Manual structured application events
• Buffered and batched HTTPS delivery
• No customer-managed message broker or token refresh flow
• Graceful shutdown flush

Requirements

• .NET 8.0 or later
• A Pinqloq project and secret key

Installation

dotnet add package pinqloq

Quick Start

Store your secret key in configuration, an environment variable, or a secret manager. Do not hardcode production credentials.

{
  "Pinqloq": {
    "SecretKey": "your-secret-key",
    "ApiLogsCollectionName": "myapp_api_logs",
    "DeviceIdentifier": "myapp-instance-1"
  }
}

Register Pinqloq and enable automatic request logging:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddPinqloq(options =>
{
    options.SecretKey =
        builder.Configuration["Pinqloq:SecretKey"]
        ?? throw new InvalidOperationException("Pinqloq secret key is missing.");

    options.ApiLogsCollectionName =
        builder.Configuration["Pinqloq:ApiLogsCollectionName"];

    options.DeviceIdentifier =
        builder.Configuration["Pinqloq:DeviceIdentifier"];
});

var app = builder.Build();

app.UsePinqloqRequestLogging(options =>
{
    options.ExcludePaths("/health", "/swagger");
});

app.MapControllers();
app.Run();

The middleware fills the fixed Event and Path fields (the panel title and the request path) and captures the HTTP method and status code as searchable metadata. The request body, response body, request headers, and response headers go to the log detail as InputJson, OutputJson, RequestHeaders, and ResponseHeaders. Bodies are truncated at 32 KB.

Manual Logging

Inject IPinqloqLogger to send structured application events:

public class OrderService(IPinqloqLogger pinqloqClient)
{
    public void CreateOrder(Order order)
    {
        pinqloqClient.Enqueue(new PinqloqLogEntry
        {
            Event = "order.created",
            DeviceIdentifier = order.CustomerId.ToString(),
            LogLevel = PinqloqLogLevel.Information,
            LogSourceType = PinqloqLogSourceType.Backend,
            Metadata = new()
            {
                ["orderId"] = order.Id.ToString()
            }
        });
    }
}

Event is required on every entry and is used as the log title. The request-logging middleware fills it automatically. Path (the request path) is filled by the middleware too, but stays null on a manual entry unless you set it.

DeviceIdentifier is optional. Leave it unset on an entry to inherit the global PinqloqOptions.DeviceIdentifier. If neither is set, the log is stored without one.

Add Request Metadata

By default the middleware reads the optional DeviceIdentifier from the device-identifier request header. Override how it is resolved with SetDeviceIdentifier (a claim, trace id, a different header, …). The override wins. If it returns null/empty, the middleware falls back to the device-identifier header, then to the global PinqloqOptions.DeviceIdentifier. If none of these resolve a value, the log is stored without a DeviceIdentifier.

To attach searchable request metadata, replace the middleware call from Quick Start with the following configuration. Use AddMetadata for searchable values such as user and tenant IDs. Use AddDetail for additional drill-down information. The Event field (the panel title) defaults to "{method} {path}" and can be overridden with AddMetadata("event", …) — the override lands on the entry's Event field, not in Metadata.

app.UsePinqloqRequestLogging(options =>
{
    options.ExcludePaths("/health", "/swagger");

    options.SetDeviceIdentifier(context =>
        context.User.FindFirst("sub")?.Value);

    options.SetAppVersionName(context =>
        context.Request.Headers["X-App-Version"].ToString());

    options.AddMetadata("userId", context =>
        context.User.FindFirst("sub")?.Value);
});

Correlation ID

Every log carries a CorrelationId that ties together the records of a single request or flow. The request-logging middleware fills it with no configuration:

1. The caller's correlation-id request header, when present (case-insensitive).
2. Otherwise HttpContext.TraceIdentifier.

A caller that already propagates a correlation id keeps it across services.

On a manual Enqueue the field is optional and stays null unless you set it:

pinqloqClient.Enqueue(new PinqloqLogEntry
{
    Event = "order.created",
    DeviceIdentifier = order.CustomerId.ToString(),
    CorrelationId = currentCorrelationId
});

Running your own request-logging middleware? Read the same header through the exposed constant rather than hardcoding it:

var header = context.Request.Headers[PinqloqRequestLoggingMiddleware.CorrelationIdHeaderName]
    .ToString();

entry.CorrelationId = string.IsNullOrWhiteSpace(header)
    ? context.TraceIdentifier
    : header;

Redacting Sensitive Values

Request and response bodies and headers may contain credentials, tokens, or personal information. Mask them at the source with two attributes, both MVC-controller-only (they resolve through ControllerActionDescriptor, so minimal API endpoints are not scanned):

• [PinqloqRedact] on a DTO property masks just that property's value with *****REDACTED***** wherever it appears in InputJson/OutputJson — the property can belong to the action's parameter type, its return type, or anything nested inside them (nested objects, collections).
• [PinqloqRedactEndpoint] on an action (or on the controller class, covering every action in it) masks every value in InputJson, OutputJson, RequestHeaders, and ResponseHeaders for that endpoint, keeping the JSON structure and header names intact.

public class AuthResponse
{
    [PinqloqRedact]
    public string Token { get; set; } = "";

    public string UserId { get; set; } = "";
}

[ApiController]
[Route("api/user")]
public class UserController : ControllerBase
{
    [HttpPost("Auth")]
    public AuthResponse Auth([FromBody] AuthRequest request) => ...;

    [PinqloqRedactEndpoint]
    [HttpPost("Payment")]
    public IActionResult Payment([FromBody] PaymentRequest request) => ...;
}

Logs Auth produces:

{ "token": "*****REDACTED*****", "userId": "64" }

Logs Payment produces (every value masked, including headers):

{ "cardNumber": "*****REDACTED*****", "amount": "*****REDACTED*****" }

[PinqloqRedact] only affects properties reachable from a type the middleware can see through reflection (the action's parameter and return types). It has no effect on serialization — the real value still goes out on the wire; only the log entry is masked. A non-JSON body (form data, plain text) with [PinqloqRedactEndpoint] applied is logged as a single masked string, since there is no JSON structure to preserve.

Using redaction from your own middleware

If you have your own request-logging middleware instead of UsePinqloqRequestLogging, call PinqloqRedaction.Resolve(HttpContext) directly — it runs the same reflection (cached per action) and returns a PinqloqRedactionPlan:

var plan = PinqloqRedaction.Resolve(httpContext);

// RedactAll is true when [PinqloqRedactEndpoint] applies; ShouldRedact covers both
// RedactAll and any [PinqloqRedact]-marked property name (case-insensitive).
bool isSensitive = existingSensitiveKeyCheck(fieldKey) || plan.ShouldRedact(fieldKey);

Resolve it once per request (it's endpoint-dependent, not field-dependent) and reuse the same PinqloqRedactionPlan for every field you check — plan.HasRedactions tells you upfront whether there's anything to mask at all, so you can skip the check entirely when it's false. ShouldRedact only knows about names (JSON property names and, for RedactAll, everything); it does not itself walk JSON — you still own how bodies/headers are traversed.

Security and Reliability

Redaction is opt-in and reflection-based — it protects only fields you've marked. Exclude sensitive endpoints entirely with ExcludePaths if you'd rather not log them at all.

Logs are buffered in memory and sent in batches. Buffered logs may be lost if the process is terminated without a graceful shutdown.

Delivery failures are reported through onFailed callbacks and, even without callbacks, as throttled entries in your application log — never silently discarded, but also never blocking. If your secret key is authorized for more than one collection, set ApiLogsCollectionName (or a per-entry CollectionName); otherwise the batch is rejected.

Documentation

• Full documentation
• LLM-friendly Markdown reference

License

MIT