QuickAssist.Logging 2.0.3

QuickAssist.Logging

QuickAssist.Logging is a .NET 9 NuGet package for Serilog configuration, MediatR request logging, and ASP.NET Core exception handling. Its Serilog configuration writes rolling text files and can send events to Elasticsearch and Slack.

AddLoggingServies adds a request logging scope at the start of the ASP.NET Core middleware pipeline. Logs emitted within that HTTP request through the package's Serilog configuration share RequestId from HttpContext.TraceIdentifier, including logs outside MediatR handlers. LoggingBehavior also adds request type and available HTTP user fields while a MediatR request runs. It logs the request payload before calling the handler and the response payload after successful completion, using Serilog destructuring ({@RequestPayload} and {@ResponsePayload}). Payload properties appear in the rendered messages in text files and as structured properties in structured sinks. Configure trusted forwarded headers in the consuming ASP.NET Core app before relying on RemoteIpAddressField. The default text file template prints RequestId, the active activity's distributed TraceId, and all MediatR request scope fields. Startup logs, background jobs, and logs emitted before the request scope do not have an HTTP RequestId.

ConfigurationViewModel.FromConfiguration(IConfiguration) reads the existing ElasticConfiguration, SlackConfiguration, and FileConfiguration sections into one model. The logger utilities use that model internally; existing configuration keys remain unchanged.

The logger utilities use an explicit Serilog configuration assembly set instead of scanning every Serilog-named dependency automatically. This prevents stale optional entries in a consuming application's dependency manifest from causing startup FileNotFoundException errors. Additional sinks or enrichers configured in the Serilog JSON section must declare their installed assembly in Serilog:Using.

Optional Elasticsearch sink

SeriLoggerUtility.Configure and StaticSeriLoggerUtility.CreateLoggerFactory add the Elasticsearch sink only when ElasticConfiguration:Uri has a value. TSeriLoggerUtility.Configure adds it only when ElasticConfiguration:Node1, Node2, and Node3 are all set; a partial node configuration fails with a clear error. Without these settings, file logging remains available.

Optional Slack sink

The logger utilities add the Slack error sink only when SlackConfiguration:WebHookUrl is set. Provide the webhook through protected configuration, such as the SlackConfiguration__WebHookUrl environment variable. Use environment-specific configuration values for Development, Staging, and Production. Without a webhook, file logging continues and no Slack sink is created. When enabled, the existing error/fatal filters remain in effect and Slack messages use an environment-specific display name, including Prod Critical Exception in Production.

File sink configuration

File logging is enabled by default with the existing logs_{projectName}/{projectName}-log.txt path, daily rolling, and seven retained files. Its text template appends RequestId, TraceId, RequestType, UserNameField, UserIdField, IsAuthenticatedField, AuthenticationTypeField, RemoteIpAddressField, and LocalIpAddressField to each line. These scope fields are populated while a MediatR request runs; unavailable strings render as empty quotes or null. RequestId identifies the HTTP request within the registered middleware pipeline; TraceId identifies the active distributed trace. The HTTP error response currently names its request identifier TraceId. Set FileConfiguration:Enabled to false to omit the file sink. When enabled, FileConfiguration:Path, FileConfiguration:RollingInterval, FileConfiguration:RetainedFileCountLimit, and FileConfiguration:OutputTemplate can override those defaults. Remove an existing FileConfiguration:OutputTemplate to use the new default, or include the desired field placeholders in your custom template. The path may contain {projectName}, which is replaced by the entry assembly name in lowercase with dots changed to hyphens. Invalid configured values fail with a configuration error.

The default output template is:

{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj} RequestId="{RequestId:l}" TraceId="{TraceId}" RequestType="{RequestType:l}" UserNameField="{UserNameField:l}" UserIdField="{UserIdField:l}" IsAuthenticatedField={IsAuthenticatedField} AuthenticationTypeField="{AuthenticationTypeField:l}" RemoteIpAddressField="{RemoteIpAddressField:l}" LocalIpAddressField="{LocalIpAddressField:l}"{NewLine}{Exception}

Configuration and agent guidance

The single configuration-and-usage guide is agent-rules/AGENTS.md. It documents package registration, sink configuration, application logging, exception middleware, correlation, and rules for coding agents.

NuGet does not make agents in consuming repositories automatically follow a guidance file inside a package. Copy or adapt the relevant rules into the consuming repository's AGENTS.md. The packaged guide is provided for reference and is not imported into an application automatically.