Metadata-Version: 2.4
Name: policyengine-observability
Version: 1.1.0
Summary: Shared PolicyEngine observability runtime for logs, timings, metrics, and OpenTelemetry.
Author-email: PolicyEngine <hello@policyengine.org>
Requires-Python: >=3.12
Requires-Dist: opentelemetry-api
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc
Requires-Dist: opentelemetry-exporter-otlp-proto-http
Requires-Dist: opentelemetry-instrumentation-fastapi
Requires-Dist: opentelemetry-instrumentation-httpx
Requires-Dist: opentelemetry-sdk
Provides-Extra: all
Requires-Dist: fastapi; extra == 'all'
Requires-Dist: flask>=2.2; extra == 'all'
Requires-Dist: google-cloud-logging>=3.15.0; extra == 'all'
Requires-Dist: httpx; extra == 'all'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: towncrier>=24.8.0; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.2; extra == 'flask'
Provides-Extra: google
Requires-Dist: google-cloud-logging>=3.15.0; extra == 'google'
Provides-Extra: httpx
Requires-Dist: httpx; extra == 'httpx'
Provides-Extra: otel
Provides-Extra: otlp-grpc
Provides-Extra: otlp-http
Description-Content-Type: text/markdown

# policyengine-observability

Shared PolicyEngine observability runtime for fail-open local timings,
structured logs, OpenTelemetry traces, and OpenTelemetry metrics.

The package intentionally keeps framework support in adapters:

- `policyengine_observability.adapters.flask`
- `policyengine_observability.adapters.fastapi`
- `policyengine_observability.integrations.httpx`

OpenTelemetry support is installed and enabled by default. Timing and
structured logging run even without an OTLP collector; when no endpoint is
configured, spans and metrics stay in-process while logs still receive trace
context. Set `OTEL_ENABLED=false` to opt out. Configure
`OTEL_EXPORTER_OTLP_ENDPOINT` to export traces and metrics.

Structured logs write to stdout by default:

```bash
OBSERVABILITY_LOG_DESTINATIONS=stdout
```

Cloud Run captures stdout and stderr into Google Cloud Logging, so stdout is
usually the right destination for Cloud Run services. Non-GCP runtimes such as
Modal can write directly to Google Cloud Logging by installing the `google`
extra and enabling the Google destination:

```bash
OBSERVABILITY_LOG_DESTINATIONS=google_cloud_logging
OBSERVABILITY_GOOGLE_CLOUD_PROJECT=policyengine-observability
OBSERVABILITY_GOOGLE_CLOUD_LOG_NAME=policyengine-observability
```

Multiple destinations can be enabled with a comma-separated list, for example
`OBSERVABILITY_LOG_DESTINATIONS=stdout,google_cloud_logging`. Google Cloud
Logging uses Application Default Credentials and requires permission to create
log entries, typically through `roles/logging.logWriter`.

## Release workflow

Changes should include a Towncrier fragment in `changelog.d/`. Pull requests
run changelog, Ruff, and coverage checks. Pushes to `main` run the same gates,
then publish a versioning commit that builds the changelog and bumps
`pyproject.toml`. That versioning commit publishes the package to PyPI through
trusted publishing, creates a matching git tag, and opens a GitHub release.
