hostess-python 0.1.0__tar.gz

hostess_python-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (with the fastapi extra)
+        run: uv sync --extra fastapi
+      - name: Test
+        run: uv run pytest -q

hostess_python-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish
+
+# Cuts a PyPI release when a GitHub Release is published. Uses PyPI Trusted
+# Publishing (OIDC) — no API token stored as a secret. Configure a Trusted
+# Publisher (or a pending publisher for the first claim) at
+# https://pypi.org/manage/account/publishing/ with:
+#   project: hostess-python  workflow: publish.yml  environment: pypi
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI (trusted publishing)
+        run: uv publish

hostess_python-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+uv.lock

hostess_python-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

hostess_python-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-13
+
+Initial release. FastAPI integration for Hostess **API Insights**.
+
+### Added
+
+- `hostess_sdk.fastapi.instrument(app)` — one-line FastAPI instrumentation:
+  - Applies OpenTelemetry FastAPI instrumentation so requests produce server
+    spans carrying the route template, method, and status (never raw paths or
+    query strings).
+  - Exports spans over OTLP/HTTP to the Hostess collector. The endpoint is
+    resolved from `HOSTESS_OTEL_ENDPOINT` → `OTEL_EXPORTER_OTLP_ENDPOINT` →
+    the `otlp_endpoint` argument.
+  - Attaches to an existing global `TracerProvider` when present; installs its
+    own otherwise.
+  - Options: `enabled`, `service_name`, `exclude_paths`, `otlp_endpoint`.
+- Instrumentation marker heartbeat — periodically exports
+  `hostess_instrumentation_info{language,framework,sdk_version,framework_version} 1`
+  on a dedicated (non-global) `MeterProvider`, so the platform can distinguish
+  "installed, waiting for traffic" from "not installed".
+- `hostess-python[fastapi]` install extra.
+
+### Behavior
+
+- Idempotent; a clean no-op when disabled (`enabled=False` /
+  `HOSTESS_INSTRUMENTATION=false`) or when no collector endpoint is available.
+- Fails silent and cheap — never adds request latency or crashes the host app.
+
+[0.1.0]: https://github.com/howl-cloud/hostess-python/releases/tag/v0.1.0

hostess_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Horizon Web Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hostess_python-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: hostess-python
+Version: 0.1.0
+Summary: Hostess SDK for Python — native API Insights for FastAPI and beyond.
+Project-URL: Homepage, https://hostess.sh
+Project-URL: Repository, https://github.com/howl-cloud/hostess-python
+Author: Horizon Web Labs
+License: MIT License
+        
+        Copyright (c) 2026 Horizon Web Labs
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: fastapi,hostess,insights,observability,opentelemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Provides-Extra: fastapi
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0; extra == 'fastapi'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# hostess-python
+
+The Hostess SDK for Python. Native **API Insights** for FastAPI (and, later,
+other Python frameworks) with one line of code.
+
+```bash
+pip install "hostess-python[fastapi]"
+```
+
+```python
+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
+
+```python
+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
+
+```bash
+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).

hostess_python-0.1.0/README.md

@@ -0,0 +1,66 @@
+# hostess-python
+
+The Hostess SDK for Python. Native **API Insights** for FastAPI (and, later,
+other Python frameworks) with one line of code.
+
+```bash
+pip install "hostess-python[fastapi]"
+```
+
+```python
+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
+
+```python
+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
+
+```bash
+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).

hostess_python-0.1.0/examples/fastapi-basic/main.py

@@ -0,0 +1,23 @@
+"""Minimal instrumented FastAPI app.
+
+Run inside Hostess (the platform injects the OTLP endpoint), or locally with::
+
+    HOSTESS_OTEL_ENDPOINT=http://localhost:4318 uvicorn main:app
+"""
+
+from fastapi import FastAPI
+
+from hostess_sdk.fastapi import instrument
+
+app = FastAPI(title="hostess-python example")
+instrument(app)
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.get("/items/{item_id}")
+async def get_item(item_id: int) -> dict[str, int]:
+    return {"item_id": item_id}

hostess_python-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hostess-python"
+version = "0.1.0"
+description = "Hostess SDK for Python — native API Insights for FastAPI and beyond."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+authors = [{ name = "Horizon Web Labs" }]
+keywords = ["hostess", "observability", "opentelemetry", "fastapi", "insights"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "opentelemetry-api>=1.27.0",
+    "opentelemetry-sdk>=1.27.0",
+]
+
+# `pip install "hostess-python[fastapi]"` adds the FastAPI instrumentation and
+# the OTLP/HTTP exporter. The base package stays dependency-light.
+[project.optional-dependencies]
+fastapi = [
+    "opentelemetry-instrumentation-fastapi>=0.48b0",
+    "opentelemetry-exporter-otlp-proto-http>=1.27.0",
+]
+
+[project.urls]
+Homepage = "https://hostess.sh"
+Repository = "https://github.com/howl-cloud/hostess-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hostess_sdk"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "fastapi>=0.110",
+    "httpx>=0.27",
+]

hostess_python-0.1.0/src/hostess_sdk/__init__.py

@@ -0,0 +1,19 @@
+"""Hostess SDK for Python.
+
+The public integration surface lives in framework submodules, e.g.::
+
+    from hostess_sdk.fastapi import instrument
+
+The base package is intentionally dependency-light; framework helpers pull in
+their instrumentation via extras (``hostess-python[fastapi]``).
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("hostess-python")
+except PackageNotFoundError:  # editable/source checkout without installed metadata
+    __version__ = "0.0.0+local"
+
+__all__ = ["__version__"]

hostess_python-0.1.0/src/hostess_sdk/_otel/__init__.py

@@ -0,0 +1,108 @@
+"""Shared OTel setup: endpoint/enabled resolution, resource, tracer provider.
+
+Tracing attaches to the app's existing global ``TracerProvider`` when one is
+present (so the helper's spans share context with the app), and only installs
+its own when none exists. The marker heartbeat (see ``marker.py``) uses a
+*dedicated, non-global* ``MeterProvider`` instead, because metric readers cannot
+be added to an existing provider and we must never clobber the app's metrics.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+logger = logging.getLogger("hostess_sdk")
+
+_TRUE = {"1", "true", "yes", "on"}
+_FALSE = {"0", "false", "no", "off"}
+
+
+def is_enabled(enabled: bool | None) -> bool:
+    """Resolve the enabled flag: explicit arg, then env, then default-on."""
+    if enabled is not None:
+        return enabled
+    raw = os.getenv("HOSTESS_INSTRUMENTATION")
+    if raw is not None and raw.strip().lower() in _FALSE:
+        return False
+    return True
+
+
+def resolve_endpoint(explicit: str | None) -> str | None:
+    """Resolve the OTLP base endpoint.
+
+    Precedence: platform-injected ``HOSTESS_OTEL_ENDPOINT`` →
+    ``OTEL_EXPORTER_OTLP_ENDPOINT`` → the explicit ``otlp_endpoint`` argument.
+    """
+    for candidate in (
+        os.getenv("HOSTESS_OTEL_ENDPOINT"),
+        os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT"),
+        explicit,
+    ):
+        if candidate and candidate.strip():
+            return candidate.strip()
+    return None
+
+
+def signal_endpoint(base: str, signal: str) -> str:
+    """Append the OTLP/HTTP signal path (``v1/traces``, ``v1/metrics``)."""
+    base = base.rstrip("/")
+    suffix = f"/v1/{signal}"
+    if base.endswith(suffix):
+        return base
+    return base + suffix
+
+
+def build_resource(
+    *,
+    service_name: str | None,
+    sdk_version: str,
+    framework: str,
+    framework_version: str,
+) -> Resource:
+    """Build the OTel resource.
+
+    ``Resource.create`` already folds in env-detected attributes
+    (``OTEL_SERVICE_NAME``, ``OTEL_RESOURCE_ATTRIBUTES`` injected by the
+    platform). These are advisory: authoritative tenant attribution comes from
+    the collector's k8sattributes processor.
+    """
+    attrs: dict[str, str] = {
+        "hostess.sdk.language": "python",
+        "hostess.sdk.version": sdk_version,
+        "hostess.framework": framework,
+        "hostess.framework.version": framework_version,
+    }
+    resolved_name = service_name or os.getenv("HOSTESS_SERVICE_NAME")
+    if resolved_name:
+        attrs["service.name"] = resolved_name
+    return Resource.create(attrs)
+
+
+def ensure_tracer_provider(resource: Resource, base_endpoint: str) -> TracerProvider:
+    """Return the global SDK ``TracerProvider``, attaching our OTLP exporter.
+
+    Attaches a span processor to an existing SDK provider, or installs a new
+    one (with our resource) if only the API default proxy is present.
+    """
+    # Imported lazily so the base package doesn't hard-require the http exporter
+    # (it ships with the framework extra).
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+    exporter = OTLPSpanExporter(endpoint=signal_endpoint(base_endpoint, "traces"))
+    processor = BatchSpanProcessor(exporter)
+
+    current = trace.get_tracer_provider()
+    if isinstance(current, TracerProvider):
+        current.add_span_processor(processor)
+        return current
+
+    provider = TracerProvider(resource=resource)
+    provider.add_span_processor(processor)
+    trace.set_tracer_provider(provider)
+    return provider

hostess_python-0.1.0/src/hostess_sdk/_otel/marker.py

@@ -0,0 +1,86 @@
+"""The instrumentation-info marker heartbeat.
+
+Periodically exports the gauge
+``hostess_instrumentation_info{language,framework,sdk_version,framework_version} 1``.
+This is what lets the platform tell "installed, no traffic yet" from "not
+installed" — spans only appear once requests arrive.
+
+Uses its own ``MeterProvider`` (not the global one) so it exports the marker to
+the Hostess collector regardless of, and without disturbing, any MeterProvider
+the application configures for its own metrics.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Iterable
+
+from opentelemetry.metrics import CallbackOptions, Observation
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.resources import Resource
+
+from . import signal_endpoint
+
+logger = logging.getLogger("hostess_sdk")
+
+# Holds the dedicated provider so its reader thread isn't garbage-collected and
+# so a re-instrument call can detect it (idempotency).
+_marker_provider: MeterProvider | None = None
+
+
+def start_marker_heartbeat(
+    *,
+    resource: Resource,
+    base_endpoint: str,
+    language: str,
+    framework: str,
+    sdk_version: str,
+    framework_version: str,
+    interval_seconds: int = 60,
+) -> MeterProvider | None:
+    """Start the marker heartbeat. Idempotent: a no-op if already running."""
+    global _marker_provider
+    if _marker_provider is not None:
+        return _marker_provider
+
+    from opentelemetry.exporter.otlp.proto.http.metric_exporter import (
+        OTLPMetricExporter,
+    )
+
+    exporter = OTLPMetricExporter(endpoint=signal_endpoint(base_endpoint, "metrics"))
+    reader = PeriodicExportingMetricReader(
+        exporter, export_interval_millis=interval_seconds * 1000
+    )
+    provider = MeterProvider(resource=resource, metric_readers=[reader])
+    meter = provider.get_meter("hostess_sdk")
+
+    attributes = {
+        "language": language,
+        "framework": framework,
+        "sdk_version": sdk_version,
+        "framework_version": framework_version,
+    }
+
+    def _observe(_options: CallbackOptions) -> Iterable[Observation]:
+        yield Observation(1, attributes)
+
+    meter.create_observable_gauge(
+        name="hostess_instrumentation_info",
+        callbacks=[_observe],
+        description="Hostess instrumentation marker (1 = installed).",
+    )
+
+    _marker_provider = provider
+    return provider
+
+
+def _reset_for_tests() -> None:
+    """Tear down the heartbeat so tests can re-run instrument() cleanly."""
+    global _marker_provider
+    if _marker_provider is not None:
+        try:
+            _marker_provider.shutdown()
+        except Exception:  # pragma: no cover - best effort
+            pass
+        _marker_provider = None

hostess_python-0.1.0/src/hostess_sdk/fastapi.py

@@ -0,0 +1,123 @@
+"""FastAPI integration for Hostess.
+
+Usage::
+
+    from fastapi import FastAPI
+    from hostess_sdk.fastapi import instrument
+
+    app = FastAPI()
+    instrument(app)
+
+The helper is deliberately thin: it preconfigures battle-tested OpenTelemetry
+FastAPI instrumentation to push to the Hostess collector, and emits the marker
+heartbeat. It adds no routes to the application.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Iterable, Optional
+
+from ._otel import (
+    build_resource,
+    ensure_tracer_provider,
+    is_enabled,
+    resolve_endpoint,
+)
+from ._otel.marker import start_marker_heartbeat
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+logger = logging.getLogger("hostess_sdk")
+
+_LANGUAGE = "python"
+_FRAMEWORK = "fastapi"
+
+# Apps already instrumented in this process, for idempotency.
+_instrumented_apps: "set[int]" = set()
+
+
+def instrument(
+    app: "FastAPI",
+    *,
+    enabled: Optional[bool] = None,
+    service_name: Optional[str] = None,
+    exclude_paths: Optional[Iterable[str]] = None,
+    otlp_endpoint: Optional[str] = None,
+) -> "FastAPI":
+    """Instrument a FastAPI app for Hostess API Insights.
+
+    - Applies ``opentelemetry-instrumentation-fastapi`` so requests produce
+      server spans carrying the route template, method, and status.
+    - Exports spans over OTLP/HTTP to the Hostess collector (endpoint injected
+      by the platform; overridable via ``otlp_endpoint`` for local use).
+    - Starts the marker heartbeat.
+
+    Idempotent, fail-silent, and a no-op when disabled or when no collector
+    endpoint can be resolved. Returns the original ``app`` for fluent use.
+    """
+    if not is_enabled(enabled):
+        logger.debug("hostess: instrumentation disabled; skipping")
+        return app
+
+    if id(app) in _instrumented_apps:
+        logger.debug("hostess: app already instrumented; skipping")
+        return app
+
+    endpoint = resolve_endpoint(otlp_endpoint)
+    if endpoint is None:
+        # Common when running locally outside Hostess: stay a clean no-op.
+        logger.debug("hostess: no OTLP endpoint resolved; instrumentation is a no-op")
+        return app
+
+    sdk_version, framework_version = _versions()
+    resource = build_resource(
+        service_name=service_name,
+        sdk_version=sdk_version,
+        framework=_FRAMEWORK,
+        framework_version=framework_version,
+    )
+
+    try:
+        ensure_tracer_provider(resource, endpoint)
+        _instrument_fastapi(app, exclude_paths)
+        start_marker_heartbeat(
+            resource=resource,
+            base_endpoint=endpoint,
+            language=_LANGUAGE,
+            framework=_FRAMEWORK,
+            sdk_version=sdk_version,
+            framework_version=framework_version,
+        )
+    except Exception:  # never break the host app over telemetry setup
+        logger.debug("hostess: instrumentation setup failed; continuing", exc_info=True)
+        return app
+
+    _instrumented_apps.add(id(app))
+    return app
+
+
+def _instrument_fastapi(app: "FastAPI", exclude_paths: Optional[Iterable[str]]) -> None:
+    from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+
+    excluded_urls = ",".join(exclude_paths) if exclude_paths else None
+    FastAPIInstrumentor.instrument_app(app, excluded_urls=excluded_urls)
+
+
+def _versions() -> "tuple[str, str]":
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as pkg_version
+
+    def safe(name: str) -> str:
+        try:
+            return pkg_version(name)
+        except PackageNotFoundError:
+            return "unknown"
+
+    return safe("hostess-python"), safe("fastapi")
+
+
+def _reset_for_tests() -> None:
+    """Clear per-process idempotency state (test helper)."""
+    _instrumented_apps.clear()

hostess_python-0.1.0/tests/test_fastapi_instrumentation.py

@@ -0,0 +1,138 @@
+import importlib
+
+import pytest
+from fastapi import FastAPI
+
+from hostess_sdk import _otel
+from hostess_sdk import fastapi as hostess_fastapi
+from hostess_sdk._otel import marker
+
+
+@pytest.fixture(autouse=True)
+def _reset(monkeypatch):
+    # Clear per-process idempotency + marker state between tests, and start from
+    # a clean env (no platform-injected vars).
+    hostess_fastapi._reset_for_tests()
+    marker._reset_for_tests()
+    for var in (
+        "HOSTESS_OTEL_ENDPOINT",
+        "OTEL_EXPORTER_OTLP_ENDPOINT",
+        "HOSTESS_INSTRUMENTATION",
+        "HOSTESS_SERVICE_NAME",
+    ):
+        monkeypatch.delenv(var, raising=False)
+    yield
+    hostess_fastapi._reset_for_tests()
+    marker._reset_for_tests()
+
+
+def test_is_enabled_precedence(monkeypatch):
+    assert _otel.is_enabled(True) is True
+    assert _otel.is_enabled(False) is False
+    monkeypatch.setenv("HOSTESS_INSTRUMENTATION", "false")
+    assert _otel.is_enabled(None) is False
+    monkeypatch.setenv("HOSTESS_INSTRUMENTATION", "true")
+    assert _otel.is_enabled(None) is True
+    monkeypatch.delenv("HOSTESS_INSTRUMENTATION", raising=False)
+    assert _otel.is_enabled(None) is True  # default on
+
+
+def test_resolve_endpoint_precedence(monkeypatch):
+    assert _otel.resolve_endpoint(None) is None
+    monkeypatch.setenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://otel:4318")
+    assert _otel.resolve_endpoint(None) == "http://otel:4318"
+    monkeypatch.setenv("HOSTESS_OTEL_ENDPOINT", "http://hostess-otel:4318")
+    assert _otel.resolve_endpoint(None) == "http://hostess-otel:4318"  # wins
+    assert _otel.resolve_endpoint("http://arg:4318") == "http://hostess-otel:4318"
+
+
+def test_signal_endpoint():
+    assert _otel.signal_endpoint("http://h:4318", "traces") == "http://h:4318/v1/traces"
+    assert _otel.signal_endpoint("http://h:4318/", "metrics") == "http://h:4318/v1/metrics"
+    # Idempotent if the path is already present.
+    assert (
+        _otel.signal_endpoint("http://h:4318/v1/traces", "traces")
+        == "http://h:4318/v1/traces"
+    )
+
+
+def test_noop_without_endpoint():
+    app = FastAPI()
+    returned = hostess_fastapi.instrument(app)
+    assert returned is app
+    assert id(app) not in hostess_fastapi._instrumented_apps
+
+
+def test_disabled_is_noop(monkeypatch):
+    monkeypatch.setenv("HOSTESS_OTEL_ENDPOINT", "http://hostess-otel:4318")
+    app = FastAPI()
+    hostess_fastapi.instrument(app, enabled=False)
+    assert id(app) not in hostess_fastapi._instrumented_apps
+
+    monkeypatch.setenv("HOSTESS_INSTRUMENTATION", "false")
+    app2 = FastAPI()
+    hostess_fastapi.instrument(app2)
+    assert id(app2) not in hostess_fastapi._instrumented_apps
+
+
+def test_idempotent(monkeypatch):
+    monkeypatch.setenv("HOSTESS_OTEL_ENDPOINT", "http://hostess-otel:4318")
+
+    calls = {"tracer": 0, "fastapi": 0, "marker": 0}
+    monkeypatch.setattr(
+        hostess_fastapi, "ensure_tracer_provider",
+        lambda *a, **k: calls.__setitem__("tracer", calls["tracer"] + 1),
+    )
+    monkeypatch.setattr(
+        hostess_fastapi, "_instrument_fastapi",
+        lambda *a, **k: calls.__setitem__("fastapi", calls["fastapi"] + 1),
+    )
+    monkeypatch.setattr(
+        hostess_fastapi, "start_marker_heartbeat",
+        lambda *a, **k: calls.__setitem__("marker", calls["marker"] + 1),
+    )
+
+    app = FastAPI()
+    hostess_fastapi.instrument(app)
+    hostess_fastapi.instrument(app)  # second call must be a no-op
+
+    assert calls == {"tracer": 1, "fastapi": 1, "marker": 1}
+
+
+def test_route_template_span_no_raw_path(monkeypatch):
+    """Requests produce server spans with the route template, never raw paths."""
+    from opentelemetry import trace
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+    from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
+        InMemorySpanExporter,
+    )
+    from fastapi.testclient import TestClient
+
+    provider = trace.get_tracer_provider()
+    if not isinstance(provider, TracerProvider):
+        provider = TracerProvider()
+        trace.set_tracer_provider(provider)
+    memory = InMemorySpanExporter()
+    provider.add_span_processor(SimpleSpanProcessor(memory))
+
+    # Avoid any real network export; only the in-memory exporter matters here.
+    monkeypatch.setattr(hostess_fastapi, "ensure_tracer_provider", lambda *a, **k: provider)
+    monkeypatch.setattr(hostess_fastapi, "start_marker_heartbeat", lambda *a, **k: None)
+    monkeypatch.setenv("HOSTESS_OTEL_ENDPOINT", "http://hostess-otel:4318")
+
+    app = FastAPI()
+
+    @app.get("/items/{item_id}")
+    async def get_item(item_id: int):
+        return {"item_id": item_id}
+
+    hostess_fastapi.instrument(app)
+    client = TestClient(app)
+    assert client.get("/items/42").status_code == 200
+
+    spans = memory.get_finished_spans()
+    routes = [s.attributes.get("http.route") for s in spans if s.attributes]
+    assert "/items/{item_id}" in routes
+    # The raw path with the concrete id must never be a span route.
+    assert "/items/42" not in routes

hostess_python-0.1.0/tests/test_fastapi_marker.py

@@ -0,0 +1,58 @@
+import pytest
+from opentelemetry.sdk.metrics.export import MetricExporter, MetricExportResult
+
+from hostess_sdk._otel import marker
+
+
+@pytest.fixture(autouse=True)
+def _reset():
+    marker._reset_for_tests()
+    yield
+    marker._reset_for_tests()
+
+
+class _FakeExporter(MetricExporter):
+    """A real MetricExporter that exports nowhere (no network in tests)."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__()
+
+    def export(self, metrics_data, timeout_millis=10_000, **kwargs):
+        return MetricExportResult.SUCCESS
+
+    def force_flush(self, timeout_millis=10_000):
+        return True
+
+    def shutdown(self, timeout_millis=10_000, **kwargs):
+        pass
+
+
+def test_marker_registers_gauge(monkeypatch):
+    from opentelemetry.sdk.resources import Resource
+
+    # Avoid real network: swap the OTLP metric exporter for a no-op.
+    monkeypatch.setattr(
+        "opentelemetry.exporter.otlp.proto.http.metric_exporter.OTLPMetricExporter",
+        _FakeExporter,
+    )
+
+    provider = marker.start_marker_heartbeat(
+        resource=Resource.create({"service.name": "svc"}),
+        base_endpoint="http://hostess-otel:4318",
+        language="python",
+        framework="fastapi",
+        sdk_version="0.1.0",
+        framework_version="0.115.0",
+    )
+    assert provider is not None
+
+    # A second call is idempotent — same provider, no new heartbeat.
+    again = marker.start_marker_heartbeat(
+        resource=Resource.create({}),
+        base_endpoint="http://hostess-otel:4318",
+        language="python",
+        framework="fastapi",
+        sdk_version="0.1.0",
+        framework_version="0.115.0",
+    )
+    assert again is provider