hostess-python 0.1.0

Hostess SDK for Python — native API Insights for FastAPI and beyond.

hostess-python

The Hostess SDK for Python. Native API Insights for FastAPI (and, later, other Python frameworks) with one line of code.

pip install "hostess-python[fastapi]"

from fastapi import FastAPI
from hostess_sdk.fastapi import instrument

app = FastAPI()
instrument(app)

That's it. When deployed on Hostess, route-level traffic, latency, status codes, and error rates appear in Studio — no OTLP, collector, or Prometheus configuration required.

What instrument(app) does

• Applies OpenTelemetry FastAPI instrumentation, so requests produce server spans carrying the route template (/items/{item_id}), method, and status — never raw paths or query strings.
• Exports spans over OTLP/HTTP to the Hostess collector. The endpoint is injected by the platform (HOSTESS_OTEL_ENDPOINT); override with otlp_endpoint= for local use.
• Emits a periodic marker heartbeat so Studio can tell "installed, waiting for traffic" from "not installed".

It is idempotent, fails silent and cheap (bounded queue, never adds request latency or crashes the app), and is a clean no-op when disabled (enabled=False / HOSTESS_INSTRUMENTATION=false) or when no collector endpoint is available.

Options

instrument(
    app,
    enabled=None,            # None → env (HOSTESS_INSTRUMENTATION), default on
    service_name=None,       # defaults to the platform-injected name
    exclude_paths=["/health"],
    otlp_endpoint=None,      # local/advanced override
)

Privacy

The helper collects HTTP method, route template, status code, and duration. It never collects request/response bodies, query strings, raw URLs, headers, cookies, tokens, user IDs, or client IPs.

Development

uv sync
uv run pytest

Status

v0.1 — instrument(app) for FastAPI. Roadmap: a HostessFastAPI drop-in, opt-in exception metrics, and additional framework helpers (Django, Flask).