---
title: SAIF.NetCore.Logging overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: SAIF Platform Team
last_reviewed: 2026-10-02
library: SAIF.NetCore.Logging
reference_type: package
---

# SAIF.NetCore.Logging overview

> **Documentation context:** Packaged Component (NuGet)

SAIF.NetCore.Logging is the SAIF platform's structured logging engine for three host styles — Web, Windows Service, and Console — all derived from a shared base class, writing each log entry sequentially to Microsoft's `ILogger<ISaifLoggable>` first and then to a process-global Serilog pipeline, and shipping structured log and error records to the central SAIF Logging API over HTTP. The two writes are not wrapped in a try/catch, so an exception thrown by the `ILogger` call prevents the subsequent Serilog call from running*. It depends only on the foundation package `SAIF.NetCore.ServiceContracts` and is itself consumed by `SAIF.NetCore.ServiceExtensions` and, as one of the three documented implementation-to-implementation exceptions, by `SAIF.NetCore.Services.Messaging`.

## Purpose
- Implement the `ServiceContracts` logging interfaces (`ISaifLogService`, `ISaifWindowsServiceLogService`) and the standalone `IConsoleLogService` contract for three host styles.
- Resolve log thresholds, patterns, and the Logging API base URL/routes from the SAIF Environment API, with `appsettings.json` overrides.
- Format exceptions into an error payload carrying machine, user, stack trace, and SAIF exception log details — with captured HTTP request details for the web logger.
- Ship non-error and error log records to the central SAIF Logging API via a custom Serilog sink.

## Responsibilities
- Generate a correlation log ID per entry and propagate it to the Serilog `LogContext` and to `Activity.Current` tags.
- Gate all logging behind an explicit `Configure`/construction step; no log reaches any sink until the logger reports itself configured.
- Apply `appsettings.json` overrides to the Environment-API-derived base threshold and to standard per-sink configs, on a per-`LoggerType` basis.
- Provide a lazily-configured auxiliary file-logging channel for console hosts.

## Key components
- `SaifLogBase`: shared abstract engine — level switch, per-sink levels/patterns, the 20 overloaded log methods, and the configured guard.
- `SaifLog`, `SaifWindowsServiceLog`, `ConsoleLogService`: host-specific subclasses, each supplying its own sink set.
- `ExceptionFormatService` / `ExceptionFormatServiceForWeb`: build the error payload consumed by the error-logging path; the web variant adds captured HTTP request state.
- `LoggingApiSink`: the Serilog sink boundary that owns the only outbound network call this library makes.
- `WebHostBuilderExtensions.UseSaifLog()`: the host-wiring helper that routes ASP.NET Core logging to the static Serilog logger this library configures.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Service registration](service-registration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts.

## Sources
- `src/SAIF.NetCore.Logging/SAIF.NetCore.Logging/SAIF.NetCore.Logging/SaifLogBase.cs`
- `src/SAIF.NetCore.Logging/SAIF.NetCore.Logging/SAIF.NetCore.Logging/SaifLog.cs`
- `src/SAIF.NetCore.Logging/SAIF.NetCore.Logging/SAIF.NetCore.Logging/SaifWindowsServiceLog.cs`
- `src/SAIF.NetCore.Logging/SAIF.NetCore.Logging/SAIF.NetCore.Logging/ConsoleLogService.cs`
- `Architecture.md`