Skip to content

[observability] Add Python logging integration with structured events #111

@dgenio

Description

@dgenio

Problem

contextweaver has zero import logging across its entire codebase. Users cannot observe what the context pipeline or routing engine is doing at runtime. When a context build drops items unexpectedly or routing returns surprising results, there is no diagnostic output.

Proposal

Add Python standard library logging integration with structured messages at key pipeline stages. Zero-cost at default log level (WARNING), rich at DEBUG.

Loggers

  • contextweaver.context — context pipeline events
  • contextweaver.routing — routing engine events
  • contextweaver.store — store operations
  • contextweaver.adapters — adapter conversions

Log points (examples)

DEBUG: candidate generation counts, sensitivity filter drops, firewall interceptions, scoring top-k, dedup removals, selection packing, token budgets used

INFO: build summaries ("context build: phase=%s, included=%d, dropped=%d, tokens=%d/%d"), route summaries ("route: query=%r, top_k=%d, candidates=%s")

Sensitivity guard

  • NEVER log item text content at any level
  • Log only IDs, counts, scores, and structural metadata

Acceptance Criteria

  • Loggers created for context, routing, store, and adapters
  • DEBUG-level messages at each context pipeline stage
  • INFO-level summary messages for build and route completions
  • No item text content logged at any level
  • Zero performance impact at default log level
  • No runtime dependencies added (stdlib only)
  • All existing tests still pass

File Paths

  • src/contextweaver/context/manager.py, candidates.py, scoring.py, dedup.py, selection.py, firewall.py, sensitivity.py (edit)
  • src/contextweaver/routing/router.py (edit)
  • src/contextweaver/adapters/mcp.py, a2a.py (edit)

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/contextContext engine: manager, pipeline, firewallarea/observabilityMetrics, logging, debuggingarea/routingRouting engine: catalog, graph, router, cardscomplexity/averageStandard effort, moderate familiarity neededenhancementNew feature or requestmilestone/v0.2v0.2 — Core pipeline completionpriority/highHigh priority — closes a critical gap

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions