hostess-python 0.1.0__py3-none-any.whl

hostess_python-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+hostess_sdk/__init__.py,sha256=MgnQ13cclXwFRPoVnzxVpqpVt6tMaTMlexwsAwz486Q,598
+hostess_sdk/fastapi.py,sha256=NxLRQUH5K44WOB8Hhox-_VjDJxQsvHAIJZf2Xp2U7ZY,3782
+hostess_sdk/_otel/__init__.py,sha256=9w2DP9j128BGfoDp_szyLaL65j5g55TrK-2u7f5YI0Y,3724
+hostess_sdk/_otel/marker.py,sha256=qVFnlCLEIqeB4S-eUHOYbko8mmQ-gdE-TXTC-BWkOUE,2780
+hostess_python-0.1.0.dist-info/METADATA,sha256=X9baUeG5rTmdGV0XleHVLuwp3ayhH3035EY83gq1-BM,4073
+hostess_python-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+hostess_python-0.1.0.dist-info/licenses/LICENSE,sha256=eGflFTCTA2JY5LjhbvOqDh1cO_ZfjocMJ_L7KxNe7YU,1073
+hostess_python-0.1.0.dist-info/RECORD,,

hostess_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

hostess_python-0.1.0.dist-info/licenses/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_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_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_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_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()