systems observability

Observability

Active contributors: Bryan

Lode's observability is local and lightweight. src/lode/observability.py provides structured JSON logs, sensitive-field redaction, and in-memory request counters used by src/lode/daemon.py.

Directory layout

src/lode/observability.py # sanitize, log_event, Metrics
src/lode/features.py      # environment-driven feature flags
src/lode/daemon.py        # request IDs, /metrics, request logging
tests/test_observability.py

Key abstractions

Name	File	Description
sanitize()	src/lode/observability.py	Recursively redacts sensitive dict fields.
log_event()	src/lode/observability.py	Emits sorted JSON log events to stderr or a provided stream.
Metrics	src/lode/observability.py	Counts daemon requests by method, path, and status.
enabled()	src/lode/features.py	Reads LODE_FEATURE_* environment flags.
ensure_request_id()	src/lode/daemon.py	Sets or propagates x-request-id.

How it works

sequenceDiagram
    participant Client
    participant Daemon as src/lode/daemon.py
    participant Metrics as src/lode/observability.py
    participant Logs as stderr

    Client->>Daemon: HTTP request
    Daemon->>Daemon: ensure_request_id()
    Daemon->>Metrics: record(method, path, status)
    Daemon->>Logs: log_event("http_request")
    Daemon-->>Client: response with x-request-id

Loading

/metrics is only exposed when LODE_FEATURE_METRICS is enabled. The metrics format is Prometheus-style text with a loded_requests_total counter.

Integration points

• src/lode/daemon.py records every response in record_request().
• tests/test_observability.py verifies redaction, log shape, and metrics rendering.
• docs/runbooks/loded.md describes operational checks for the daemon.

Entry points for modification

Add new daemon counters to Metrics in src/lode/observability.py, then expose them through render(). Add new feature flags through src/lode/features.py and document the flag in .env.example if operators need it.

Key source files

File	Purpose
src/lode/observability.py	Structured logs and local metrics.
src/lode/features.py	Environment feature flags.
src/lode/daemon.py	Request IDs and metrics endpoint.
tests/test_observability.py	Observability tests.

Related pages

• Logging
• Metrics
• Security