Skip to content

Backend Logging

Plan Metadata

  • Plan type: sub-plan
  • Parent plan: logging.md
  • Depends on: N/A
  • Status: documentation

System Intent

  • What is being built: Target contract for shared backend logger behavior.
  • Primary consumer(s): Lambda handlers in main/server.
  • Boundary (black-box scope only): create_logger({flow}) scope binding and returned log_event(payload) emitted flow step [additional] log-line behavior from logging.md.

Stage Gate Tracker

  • [x] Stage 1 Mermaid approved
  • [x] Stage 2 I/O contracts approved
  • [x] Stage 3 pseudocode approved or skipped

1. Mermaid Diagram

Reference: .agent/skills/create-mermaid-diagram/SKILL.md

flowchart TD
  Handler[Lambda Handler Call Site - main/server/api and main/server/auth] -->|scope dict {flow}| CreateLogger[create_logger - main/server/layers/shared/python/shared/logger.py]
  CreateLogger -->|step + optional additional| LogEvent[log_event closure - main/server/layers/shared/python/shared/logger.py]
  LogEvent -->|validate payload fields| Validate[_validate_payload - main/server/layers/shared/python/shared/logger.py]
  LogEvent -->|add time fields and stringify values| BuildPayload[_build_log_payload - main/server/layers/shared/python/shared/logger.py]
  BuildPayload -->|format line and logger.info| RuntimeOutput[Encache Logger Output - runtime logging stream]

  classDef unchanged fill:#d3d3d3,stroke:#666,stroke-width:1px;
  classDef updated fill:#ffe58a,stroke:#666,stroke-width:1px;
  classDef deleted fill:#f4a6a6,stroke:#666,stroke-width:1px;
  classDef created fill:#a8e6a3,stroke:#666,stroke-width:1px;

  class Handler,CreateLogger,LogEvent,Validate,BuildPayload,RuntimeOutput unchanged;

2. Black-Box Inputs and Outputs

Global Types

BackendLoggerFactoryInput {
  flow: string (required, non-empty)
}

BackendLogInput {
  step: string (required, non-empty)
  additional?: unknown
}

BackendLogEvent {
  flow: string
  step: string
  additional?: string
  time: string (UTC ISO8601)
  time_unix_ms: string
}

BackendLogError {
  type: TypeError | ValueError
  message: string
}

Flow: main/server/layers/shared/python/shared/logger.py.log_event, main/server/tests/unit/test_logger.py

path-name input output/expected state change path-type notes updated
backend-create-logger.scope-validation BackendLoggerFactoryInput with missing/invalid flow BackendLogError type=ValueError message starts with "Required log fields must be non-empty strings:" error flow must be set when creating logger
backend-log-event.success BackendLogInput with required fields BackendLogEvent and INFO log line on logger=encache happy path flow comes from logger factory scope
backend-log-event.invalid-payload-type payload is not a dict BackendLogError type=TypeError message="log payload must be a dict" error fails before any log emission
backend-log-event.missing-required-field payload missing step BackendLogError type=ValueError message starts with "Missing required log fields:" error missing keys are listed in sorted order
backend-log-event.invalid-required-string step empty/non-string BackendLogError type=ValueError message starts with "Required log fields must be non-empty strings:" error enforces required string fields
backend-log-event.unsupported-field payload includes keys outside step/additional BackendLogError type=ValueError message starts with "Unsupported log payload fields:" error payload contract is strict after scope binding

3. Pseudocode for Critical Flows

Not needed...

After all stages are approved, apply .agent/skills/reconcile-plans/SKILL.md to propagate contract updates across linked plans.