Skip to content

Logging Capability (Flow)

This document describes the end-to-end technical flow for logging and diagnostics across SmrtHub components.

It answers: “When something happens, what gets logged, where does it go, and how do we triage it across components?”

Purpose and scope

  • Provide an end-to-end map of how components and subsystems cooperate for observability.
  • Define where to look during triage (logs, HTML export, support bundle).
  • Avoid duplicating per-component details; component READMEs should link here.

Entry points

  • Any runtime component startup (logging initialization)
  • Any operational action that emits logs (UI commands, triggers, background services, host processes)
  • Support workflows (export to HTML, generate support bundle)

Participating components/subsystems

  • Logging Subsystem (contracts): README.Files/Subsystems/Logging/README.md
  • C# implementation: SmrtApps/src/Smrt.Logging
  • Python implementation: SmrtApps/PythonApp/python_core/utils/logger
  • Support Bundle (consumer of logs): Smrt.SupportBundle

Sequence/flow (high level)

  1. A component initializes logging early at startup with a stable component name/slug.
  2. The logging stack writes:
  3. Text logs (human-readable)
  4. Structured logs (NDJSON / JSONL)
  5. Logs land in canonical per-component folders (Operational Data Policy).
  6. During diagnostics, optional HTML exports can be generated for quick inspection.
  7. Support Bundle tooling gathers the relevant log slices and related evidence for handoff.

Contracts and data shapes

Configuration and operational data

Observability & diagnostics

  • Primary source of truth: raw log files (text + structured).
  • Convenience views: HTML exports (sanitized/paginated).
  • Handoff artifact: Support Bundle.

Failure modes and expected behaviors

  • If log directories cannot be created or opened, components must emit a clear startup error and fail fast where appropriate.
  • If PII scrubbing is disabled for a debugging session, it must be explicit and time-bounded.

Testing & validation expectations

  • Validate log schema parity and trace/correlation behavior.
  • Validate file naming/paths match policy.
  • Validate support bundle ingestion still works.