Skip to content

Decouple structured events from stdlib logging via explicit EventSink#37

Merged
marcleblanc2 merged 1 commit into
mainfrom
refactor-logging-and-files
Jun 12, 2026
Merged

Decouple structured events from stdlib logging via explicit EventSink#37
marcleblanc2 merged 1 commit into
mainfrom
refactor-logging-and-files

Conversation

@marcleblanc2

Copy link
Copy Markdown
Collaborator

Implements Track B (lib side) of the file-handling + observability redesign
(spec: src-auth-perms-sync dev/PLAN.md).

What changed

  • New events module: EventSink protocol with Null/InMemory/Callback/
    Composite/JSONL sinks and an EventRuntime ambient run scope (default:
    null sink — importing the library never writes anywhere).
  • OTel Logs Data Model event schema: time_unix_nano, severity_text/
    severity_number, event_name, body, trace_id/span_id/
    parent_span_id, nested attributes, resource stamped once per run.
  • Wide-event discipline: the span-end event is the canonical wide event;
    span-start events demoted to debug; error_typeerror.type (semconv).
  • Module-friendly logging: observability_context() owns one run without
    touching stdlib handlers. cli_logging_handlers() attaches terminal +
    EventBridgeHandler to named package loggers only — never the root
    logger, no handlers.clear() (fixes host applications having their
    logging config destroyed on import). cli_run_context() composes both
    with the JSONL sink for CLI entrypoints.
  • Carried over: httpcore wire-debug mining, HTTP header secret
    redaction, exc_info tracebacks (now in the bridge), log-file retention
    pruning, resource sampler, run summaries.
  • HTTP run-summary counters renamed to http.client.* aligned names;
    metric reset moved into observability_context (per-run correctness for
    long-running hosts).
  • OTLP logs: logs provider configured when exporting; OtelLogsSink
    emits wide events through the OTel Logs API.
  • Deleted: configure_logging root clearing, JSONLogFileHandler,
    _DropStructuredEvents, structured-record magic attrs.

Verification

  • uv run python -m unittest discover -s tests — 104 tests OK
  • uv run pyright — 0 errors (strict, src + tests)
  • uv run ruff check / format --check — clean
  • Consumer (src-auth-perms-sync) developed against this branch: full fast
    suite 102/102 and live e2e 119/120 against the sgdev test instance (the
    one failure is the wheel smoke needing this release on PyPI).

- New events module: EventSink protocol, Null/InMemory/Callback/Composite/
  JSONL sinks, EventRuntime ambient run scope (default: null sink)
- Events are OTel Logs Data Model shaped: time_unix_nano, severity_text/
  number, event_name, body, trace_id/span_id/parent_span_id, attributes,
  resource stamped once on run start
- span() end event is the canonical wide event; start events demoted to
  debug; error_type renamed to error.type (semconv)
- observability_context() owns one run without touching stdlib handlers;
  cli_logging_handlers() attaches terminal + EventBridgeHandler to named
  package loggers only (never root, no handlers.clear()); cli_run_context()
  composes both with the JSONL sink for CLI entrypoints
- EventBridgeHandler carries httpcore wire-debug mining, header secret
  redaction, and exc_info tracebacks into the event stream
- HTTP run-summary counters renamed to http.client.* aligned names
- HTTP metric reset moved into observability_context (per-run, not
  per-handler-config)
- OTLP logs: logs provider configured when exporting; OtelLogsSink emits
  wide events through the OTel Logs API
- Deleted: configure_logging root clearing, JSONLogFileHandler,
  _DropStructuredEvents, structured-record magic attrs

Amp-Thread-ID: https://ampcode.com/threads/T-019eba67-c19d-7166-9690-dcb2f0eed165
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 marcleblanc2 merged commit af1daec into main Jun 12, 2026
6 checks passed
@marcleblanc2 marcleblanc2 deleted the refactor-logging-and-files branch June 12, 2026 09:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant