Metadata-Version: 2.4
Name: pulse-observability
Version: 0.1.1
Summary: FastAPI HTTP tracing and structured request logs for a self-hosted Pulse server
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1,>=0.110
Requires-Dist: opentelemetry-sdk==1.45.2
Requires-Dist: opentelemetry-instrumentation-fastapi==0.66b2

# Pulse Python SDK

Python 3.10+ FastAPI HTTP tracing and structured request logs for Pulse.
This distribution is not currently published to PyPI. Install the wheel from
your Pulse server through a normal pip requirements file:

```text
pulse-observability @ https://pulse.example.com/sdk/python/pulse_observability-0.1.1-py3-none-any.whl
```

```bash
python -m pip install -r requirements.txt
```

```python
from pulse_observability import instrument_fastapi

# After creating the existing FastAPI app, before serving requests:
instrument_fastapi(app)
```

Set PULSE_ENDPOINT and PULSE_SECRET_KEY before importing the app, plus
OTEL_SERVICE_NAME and PULSE_ENVIRONMENT. Never place a project key in a
requirements URL or in this package. Use a server address reachable from the
machine or container doing the installation; prefer HTTPS for distribution.

Provides request traces, latency, status codes and redacted request logs.
Does not automatically collect arbitrary Python logging, database calls, Pod
resources, browser visitors or background jobs. Batching is in memory, so
telemetry can be lost during an outage or forced shutdown. Business requests
do not wait for export. Existing OpenTelemetry instrumentation must be
integrated rather than instrumenting the app twice.

The source of the FastAPI integration is `pulse_observability/fastapi.py`.
The Pulse guide builder also creates the legacy standalone download from this
source. The adjacent legacy `pulse.py` event client is not part of this wheel.

FastAPI JSON error responses supply `error.message` from `detail`/`message`.
Standard validation errors are grouped into `bodyErrors`, `queryErrors` and
`paramErrors`. Input values require the corresponding `PULSE_LOG_BODY_FIELDS`,
`PULSE_LOG_QUERY_PARAMS` or `PULSE_LOG_PATH_PARAMS` allowlist. Passwords, `pw`,
passphrases and tokens are redacted even when allowed. Error-response inspection
is limited to 16 KiB; full responses and validation context are never exported.
