Metadata-Version: 2.4
Name: foam-otel-core
Version: 0.2.0
Summary: Foam's shared server-side OpenTelemetry package for Python. One core, adapters as optional extras, per-customer behavior via configuration.
License: MIT
Project-URL: Repository, https://github.com/foam-ai/packages
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: opentelemetry-api>=1.27.0
Requires-Dist: opentelemetry-sdk>=1.27.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == "fastapi"

# foam-otel-core (Python)

Foam's shared server-side OpenTelemetry package for Python — the Python
counterpart of `@foam-ai/otel-core`. One core, adapters as optional extras,
per-customer behavior via configuration.

## Quick start

```bash
pip install foam-otel-core[fastapi]
```

```python
from foam_otel import init
from foam_otel.fastapi import FoamMiddleware

init(service_name="my-service")  # token from FOAM_OTEL_TOKEN env
app.add_middleware(FoamMiddleware)
```

`init()` only exports in production (`ENVIRONMENT`/`ENV`/`PYTHON_ENV`/
`NODE_ENV` set to `production`) or with `force_export=True`. It registers
global OTel providers, so afterwards the **standard OTel API exports to
foam**:

```python
from opentelemetry import trace, metrics
from foam_otel import get_tracer, get_meter, get_logger

with get_tracer("app").start_as_current_span("work") as span:
    span.record_exception(err)          # exceptions
get_meter("app").create_counter("jobs").add(1)
get_meter("app").create_histogram("latency_ms").record(12.5)
get_meter("app").create_up_down_counter("active").add(-1)
get_logger("app").emit(...)             # log records
```

## Configuration

| Option | Default | Notes |
| --- | --- | --- |
| `token` | `FOAM_OTEL_TOKEN` env | required to export |
| `endpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` env, then `https://otel.api.foam.ai` | |
| `force_export` | `False` | export outside production |
| `redact_contact_info` | `False` | adds email/phone/telefono/celular to redaction |
| `redact_keys` | `[]` | extra keys to redact |
| `health_routes` | `[]` | routes exempted from request-context capture (none by default — health checks are captured) |

Batch cadence honors `OTEL_BSP_SCHEDULE_DELAY`, `OTEL_BLRP_SCHEDULE_DELAY`,
and `OTEL_METRIC_EXPORT_INTERVAL` (read natively by the SDK).

The wire contract (stamps, `foam.rid` baggage, redaction defaults,
anti-fabrication) is specified in `contract/SPEC.md` and enforced by
`test-apps/python-fastapi`.
