phlo-observe

A coherent observability system for Phlo and related Python applications.

The system has four components:

• phlo-observe-core — generic wide-event observability, context propagation, structured errors, buffering, redaction, sampling and drains.
• phlo-observe — Phlo-specific contexts and integrations for Dagster, dbt, DLT, Pandera, WAP, Iceberg/Nessie and Trino.
• phlo-observe-query — read-only query client and agent tools for investigation.
• phlo-observer — central ingestion, normalization, correlation, persistence and query service for Observatory and downstream telemetry systems.

The implementation contracts are in docs/V1_SPEC.md and docs/V2_SPEC.md. See V2 features for the query API, state engine, insights, and operator workflows.

First event in under five minutes

phlo-observe-core needs nothing but Python 3.12+ — no database, no server:

pip install phlo-observe-core

from observe_core import configure, observe

configure(service_name="demo")

with observe("demo.work") as evt:
    evt.set(rows_loaded=1000)

2025-01-01T00:00:00.000Z INFO     demo.work                        success 0ms service=demo

One wide event per operation, printed by the console drain by default. Add an HttpDrainConfig to point the same call at the observer below.

Quickstart

mise install          # pinned Python + uv
uv sync --all-packages

docker compose up -d postgres
export PHLO_OBSERVER_DATABASE_URL=postgresql+asyncpg://phlo:phlo@localhost:5432/phlo_observer

phlo-observer migrate && phlo-observer serve
# ingest a canonical event
curl -X POST localhost:8080/v1/events -H 'content-type: application/json' -d "{
  \"schema_version\":\"1.0\",\"event\":\"pipeline.run\",\"category\":\"pipeline\",
  \"event_id\":\"$(uuidgen)\",\"outcome\":\"success\",\"severity\":\"info\",
  \"delivery\":\"telemetry\",\"observed_at\":\"2025-01-01T00:00:00Z\",
  \"service\":{\"name\":\"demo\"},\"correlation\":{\"run_id\":\"demo-1\"},
  \"attributes\":{},\"error\":null,\"source\":{\"producer\":\"demo\"}
}"

Instrumented apps emit through phlo-observe-core (see examples/); the observer normalizes, correlates and serves GET /v1/events, /v1/runs/{id}/timeline, /health/live, /health/ready, /metrics. Auth via PHLO_OBSERVER_INGEST_TOKENS / PHLO_OBSERVER_READ_TOKENS (bearer or X-API-Key).

Repository layout

• packages/observe-core — generic library (context, queue, drains, spool)
• packages/phlo-observe-sdk — Phlo contexts + integrations
• packages/observe-query — read-only query client + agent tools
• services/phlo-observer — FastAPI + Postgres service + Alembic migrations
• schemas/ — canonical JSON Schemas
• tests/{contract,integration,performance} — cross-component suites
• docs/ — architecture, event model, configuration, deployment, troubleshooting

Status

V1 and V2 are implemented. CI covers all four packages, schema contracts, real-Postgres integration tests, live-HTTP end-to-end tests, and performance checks. The hardening report records measured behavior and operational limitations.

Audit versus observability

phlo-observe is an operational observability system. It may record decisions such as WAP promotion for visibility, but V1 is not by itself a validated authoritative electronic audit trail for GxP records.

If regulated workflows later depend on it as a system of record, separate requirements for immutability, identity, validation, retention, review, electronic signatures and change control are required.