Skip to content

Component: Smrt.Logging

Canonical source: SmrtApps/src/Smrt.Logging/README.md (mirrored below)

Smrt.Logging

Overview & Responsibilities

  • Enterprise-grade logging stack for all SmrtHub components, delivering structured JSONL, text, and HTML export outputs.
  • Encapsulates Serilog configuration, shared enrichers, activity scopes, and correlation helpers consumable across runtimes.
  • Maintains parity with Python logging implementations as documented in the canonical policy.
  • Ships deterministic test-and-diagnostics hooks (TestSinkExtensions, HTML exporters) used by support workflows.

Dependencies & Integrations

  • Targets .NET 8; depends on Serilog packages and consumes Smrt.Config for embedded default settings and path resolution.
  • Hosts integrate defaults via Smrt.Config.Logging.LoggingConfigurationExtensions.AddSmrtHubLoggingDefaults before configuring sinks.
  • Support bundle tooling ingests the generated log artifacts without additional wiring.

Configuration & Log Paths

  • Logs are emitted to %LOCALAPPDATA%/SmrtHub/Logs/<component-slug>/ following the Operational Data Policy.
  • Configuration overlays reside in %APPDATA%/SmrtHub/Config/<component-slug>/<slug>-config.json; prefer Smrt.Config helpers to access and merge content.
  • HTML export is available through Logger.ExportUnifiedHtmlLogs(...), aligning with support bundle expectations.

Runtime Flows

  • Hosts initialize logging via Logger.ConfigureFrom(...) using either bound SmrtLoggingOptions or raw IConfiguration sections.
  • Activity scopes, structured redaction enrichers, and trace context propagation are enabled by default for correlation and PII control.
  • Test-focused sinks (TestSinkExtensions) provide deterministic capture for automated validation and support bundle previews.

Public surface

The primary public surface is the logger API and helpers listed under Key APIs below.

Key APIs

  • Logger.Initialize(componentName, level?, options?) – primary entry point for configuring sinks, redaction, HTML export, and activity enrichment.
  • Logger.ConfigureFrom(IConfiguration configuration, string componentName, string sectionPath = "Logging:SmrtHub") – binds SmrtLoggingOptions from configuration sources (including Smrt.Config defaults).
  • Logger.BeginActivity(...), Logger.BeginCorrelation(...), and Logger.BeginScope(...) – helpers for W3C-aligned tracing and contextual properties.
  • Logger.ExportUnifiedHtmlLogs(autoOpen?, maxEntriesPerComponent?) – writes sanitized HTML viewers for support workflows.
  • TestSinkExtensions / TestSinkExtensionsLocal – deterministic Serilog sink used by automated tests to assert log outputs without hitting the filesystem.

Testing & Validation

  • Run Smrt.Logging.Tests when modifying enrichers, sinks, or export behavior.
  • Validate HTML export rendering and retention policies after significant configuration schema changes.
  • Exercise backpressure, redaction, and trace-context scenarios under load to ensure metrics and drop policies behave as expected.

Support Bundle & Diagnostics

  • Unified log directories and HTML exports are automatically included in support bundles; avoid custom sinks that bypass the canonical layout.
  • For manual diagnostics, prefer the documented export helpers over bespoke scripts.
  • Tests provide fixture helpers (e.g., TestLogger) that can be reused in diagnostic harnesses to capture structured output without mutating production directories.
  • Logging Subsystem (contracts and invariants): README.Files/Subsystems/Logging/README.md.
  • Logging Capability (end-to-end flow): README.Files/Capabilities/Logging/README.md.
  • Comprehensive design, option matrix, and parity requirements: README.Files/Reference-Guides/SmrtHub.Logging.README.md.

Subdirectories

  • bin/, obj/ – Generated build artifacts.
  • Tests/ – See the sibling project Smrt.Logging.Tests for validation coverage.