Skip to content

Release reusable observability runtime version 2 - #30

Merged
anth-volk merged 12 commits into
mainfrom
codex/centralize-api-v1-observability
Sep 23, 2026
Merged

anth-volk merged 12 commits into
mainfrom
codex/centralize-api-v1-observability

Conversation

@anth-volk

@anth-volk anth-volk commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #29

Summary

  • release an explicit version 2 runtime for structured logs, traces, metrics, framework adapters, HTTPX propagation, and asynchronous context propagation
  • expose provider-neutral log destination strategies with independently bounded delivery and failure isolation
  • configure trace and metric OTLP exporters separately, with pluggable authentication and no embedded provider destination
  • remove version 1 compatibility aliases and application-specific deployment assets
  • require each consumer to supply its service identity, destinations, attribute policy, endpoints, and credentials
  • validate configuration before creating workers, exporters, or logging handlers and raise ConfigurationError with every detected error
  • reject malformed sensitive-value and attribute-allowlist configuration during startup validation
  • redact configured sensitive values from logs, span attributes, span exception events, metrics, and local internal diagnostics before export
  • give every logging destination and formatter a deep copy of each record, including nested values
  • start Flask observation before existing request callbacks and complete it during teardown so early responses and uncaught exceptions retain full telemetry
  • mark HTTP 5xx spans as errors and count them as request errors even when Flask handled the exception
  • restore Flask callback state and report a local diagnostic when adapter installation fails
  • follow the OpenTelemetry endpoint contract by appending signal paths to common HTTP endpoints and preserving signal-specific HTTP endpoints exactly
  • run inline writer cleanup outside application execution with a shared shutdown deadline
  • construct Google JSON and Workload Identity credentials in memory without package-created credential files

Failure behavior

Invalid configuration fails during startup before runtime setup has side effects. After validation succeeds, logging and OpenTelemetry setup, formatting, queue, credential, export, flush, cleanup, and shutdown failures are contained inside the runtime. Application responses and calculations continue. Each queued log destination has an independent bounded queue, and a failed or slow destination does not block another destination. Inline writer cleanup cannot block application execution and orderly shutdown waits only for the configured logging timeout.

Validation

  • ruff format --check and ruff check
  • 129 tests passed
  • 90% statement and branch coverage
  • Pyright passed with no errors
  • source distribution and wheel built as version 2.0.0
  • changelog draft rendered successfully
  • Google Auth constructed a Workload Identity credential from the in-memory subject-token supplier without a network request
  • regression tests verify sensitive-value redaction in logs, span attributes, span exception events, metrics, and local internal diagnostics
  • regression tests verify fatal sensitive-value and attribute-allowlist configuration errors and nested-record isolation between destinations and formatters
  • regression tests verify Flask early responses, exception details, span error status, nonfatal late installation, rollback at every callback-registration step, and successful retry
  • regression tests verify common and exact signal-specific OTLP/HTTP endpoint handling

The API v1 Google Cloud deployment definitions and service-specific operations guide now live in PolicyEngine/policyengine-api#3850. Consumer instrumentation and deployment configuration live in that pull request and PolicyEngine/policyengine-sim-api#686.

@anth-volk anth-volk changed the title Centralize API v1 observability in Google Cloud Release reusable observability runtime version 2 Sep 22, 2026
@anth-volk
anth-volk marked this pull request as ready for review September 23, 2026 10:57
@anth-volk
anth-volk merged commit 6218ae8 into main Sep 23, 2026
3 checks passed
@anth-volk
anth-volk deleted the codex/centralize-api-v1-observability branch September 23, 2026 10:57
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.

Release reusable observability runtime version 2

1 participant