foam-otel-core 0.2.0

Foam's shared server-side OpenTelemetry package for Python. One core, adapters as optional extras, per-customer behavior via configuration.

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

pip install foam-otel-core[fastapi]

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:

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.