hostess-python 0.1.0__tar.gz → 0.2.0__tar.gz

{hostess_python-0.1.0 → hostess_python-0.2.0}/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.2.0] - 2026-08-24
+
+### Added
+
+- `hostess_sdk.fastapi.post_instrument()` — additive OpenTelemetry
+  post-instrument hook for Hostess-owned telemetry. Starts the marker
+  heartbeat after `opentelemetry-instrument` has already instrumented
+  FastAPI. Does not replace the global `TracerProvider` or install FastAPI
+  instrumentation.
+- `opentelemetry_post_instrument` entry point (`hostess_sdk`) so
+  `opentelemetry-instrument fastapi run` discovers the hook automatically.
+- `opentelemetry-distro` added to the `fastapi` extra so
+  `opentelemetry-instrument` can load the default distro and discover
+  post-instrument entry points. No Hostess `opentelemetry_configurator`
+  is registered.
+
+### Behavior
+
+- `post_instrument()` and `instrument(app)` are mutually idempotent: if
+  both run, the marker heartbeat starts once.
+- `post_instrument()` is a no-op when disabled (`HOSTESS_INSTRUMENTATION=false`)
+  or when no collector endpoint is available.
+
 ## [0.1.0] - 2026-06-13
 
 Initial release. FastAPI integration for Hostess **API Insights**.
@@ -33,4 +56,5 @@ Initial release. FastAPI integration for Hostess **API Insights**.
   `HOSTESS_INSTRUMENTATION=false`) or when no collector endpoint is available.
 - Fails silent and cheap — never adds request latency or crashes the host app.
 
+[0.2.0]: https://github.com/howl-cloud/hostess-python/releases/tag/v0.2.0
 [0.1.0]: https://github.com/howl-cloud/hostess-python/releases/tag/v0.1.0

{hostess_python-0.1.0 → hostess_python-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hostess-python
-Version: 0.1.0
+Version: 0.2.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
@@ -36,6 +36,7 @@ Requires-Python: >=3.9
 Requires-Dist: opentelemetry-api>=1.27.0
 Requires-Dist: opentelemetry-sdk>=1.27.0
 Provides-Extra: fastapi
+Requires-Dist: opentelemetry-distro>=0.48b0; 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-0.1.0 → hostess_python-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostess-python"
-version = "0.1.0"
+version = "0.2.0"
 description = "Hostess SDK for Python — native API Insights for FastAPI and beyond."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -28,8 +28,12 @@ dependencies = [
 fastapi = [
     "opentelemetry-instrumentation-fastapi>=0.48b0",
     "opentelemetry-exporter-otlp-proto-http>=1.27.0",
+    "opentelemetry-distro>=0.48b0",
 ]
 
+[project.entry-points.opentelemetry_post_instrument]
+hostess_sdk = "hostess_sdk.fastapi:post_instrument"
+
 [project.urls]
 Homepage = "https://hostess.sh"
 Repository = "https://github.com/howl-cloud/hostess-python"

{hostess_python-0.1.0 → hostess_python-0.2.0}/src/hostess_sdk/fastapi.py

@@ -7,10 +7,6 @@ Usage::
 
     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
@@ -98,6 +94,44 @@ def instrument(
     return app
 
 
+def post_instrument() -> None:
+    """Hostess-specific init after ``opentelemetry-instrument`` has run.
+
+    Additive: starts the marker heartbeat. Does not install FastAPI
+    instrumentation or replace the global TracerProvider. Idempotent with
+    ``instrument(app)`` — if both run, the marker starts once. Fail-silent
+    and a no-op when disabled or when no collector endpoint is resolved.
+    """
+    if not is_enabled(None):
+        logger.debug("hostess: instrumentation disabled; skipping post-instrument")
+        return
+
+    endpoint = resolve_endpoint(None)
+    if endpoint is None:
+        logger.debug("hostess: no OTLP endpoint resolved; post-instrument is a no-op")
+        return
+
+    sdk_version, framework_version = _versions()
+    resource = build_resource(
+        service_name=None,
+        sdk_version=sdk_version,
+        framework=_FRAMEWORK,
+        framework_version=framework_version,
+    )
+
+    try:
+        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: post-instrument setup failed; continuing", exc_info=True)
+
+
 def _instrument_fastapi(app: "FastAPI", exclude_paths: Optional[Iterable[str]]) -> None:
     from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
 

hostess_python-0.2.0/tests/test_fastapi_post_instrument.py

@@ -0,0 +1,178 @@
+from importlib.metadata import entry_points
+from inspect import signature
+
+import pytest
+from fastapi import FastAPI
+from opentelemetry.sdk.metrics.export import MetricExporter, MetricExportResult
+
+from hostess_sdk import fastapi as hostess_fastapi
+from hostess_sdk._otel import marker
+
+
+def _entry_points(group: str):
+    try:
+        return entry_points(group=group)
+    except TypeError:  # Python 3.9
+        return entry_points().get(group, [])
+
+
+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
+
+
+@pytest.fixture(autouse=True)
+def _reset(monkeypatch):
+    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_post_instrument_is_public_and_takes_no_args():
+    from hostess_sdk.fastapi import post_instrument
+
+    assert list(signature(post_instrument).parameters) == []
+    post_instrument()  # no endpoint → no-op; must not raise
+
+
+def test_entry_point_registered():
+    eps = list(_entry_points("opentelemetry_post_instrument"))
+    match = [ep for ep in eps if ep.name == "hostess_sdk"]
+    assert match, "hostess_sdk missing from opentelemetry_post_instrument"
+    assert match[0].value == "hostess_sdk.fastapi:post_instrument"
+    assert match[0].load() is hostess_fastapi.post_instrument
+
+
+def test_no_hostess_configurator_entry_point():
+    values = [ep.value for ep in _entry_points("opentelemetry_configurator")]
+    assert not any(value.startswith("hostess_sdk") for value in values)
+
+
+def test_post_instrument_noop_without_endpoint():
+    hostess_fastapi.post_instrument()
+    assert marker._marker_provider is None
+
+
+def test_post_instrument_noop_when_disabled(monkeypatch):
+    monkeypatch.setenv("HOSTESS_OTEL_ENDPOINT", "http://hostess-otel:4318")
+    monkeypatch.setenv("HOSTESS_INSTRUMENTATION", "false")
+    hostess_fastapi.post_instrument()
+    assert marker._marker_provider is None
+
+
+def test_post_instrument_starts_marker_once(monkeypatch):
+    monkeypatch.setenv("HOSTESS_OTEL_ENDPOINT", "http://hostess-otel:4318")
+    monkeypatch.setattr(
+        "opentelemetry.exporter.otlp.proto.http.metric_exporter.OTLPMetricExporter",
+        _FakeExporter,
+    )
+
+    hostess_fastapi.post_instrument()
+    first = marker._marker_provider
+    assert first is not None
+
+    hostess_fastapi.post_instrument()
+    assert marker._marker_provider is first
+
+
+def test_instrument_then_post_instrument_starts_marker_once(monkeypatch):
+    monkeypatch.setenv("HOSTESS_OTEL_ENDPOINT", "http://hostess-otel:4318")
+    monkeypatch.setattr(
+        "opentelemetry.exporter.otlp.proto.http.metric_exporter.OTLPMetricExporter",
+        _FakeExporter,
+    )
+    monkeypatch.setattr(hostess_fastapi, "ensure_tracer_provider", lambda *a, **k: None)
+    monkeypatch.setattr(hostess_fastapi, "_instrument_fastapi", lambda *a, **k: None)
+
+    app = FastAPI()
+    hostess_fastapi.instrument(app)
+    first = marker._marker_provider
+    assert first is not None
+
+    hostess_fastapi.post_instrument()
+    assert marker._marker_provider is first
+
+
+def test_post_instrument_then_instrument_starts_marker_once(monkeypatch):
+    monkeypatch.setenv("HOSTESS_OTEL_ENDPOINT", "http://hostess-otel:4318")
+    monkeypatch.setattr(
+        "opentelemetry.exporter.otlp.proto.http.metric_exporter.OTLPMetricExporter",
+        _FakeExporter,
+    )
+    monkeypatch.setattr(hostess_fastapi, "ensure_tracer_provider", lambda *a, **k: None)
+    monkeypatch.setattr(hostess_fastapi, "_instrument_fastapi", lambda *a, **k: None)
+
+    hostess_fastapi.post_instrument()
+    first = marker._marker_provider
+    assert first is not None
+
+    hostess_fastapi.instrument(FastAPI())
+    assert marker._marker_provider is first
+
+
+def test_post_instrument_does_not_instrument_fastapi(monkeypatch):
+    from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+
+    monkeypatch.setenv("HOSTESS_OTEL_ENDPOINT", "http://hostess-otel:4318")
+    monkeypatch.setattr(
+        "opentelemetry.exporter.otlp.proto.http.metric_exporter.OTLPMetricExporter",
+        _FakeExporter,
+    )
+
+    called = []
+    monkeypatch.setattr(
+        FastAPIInstrumentor, "instrument_app", lambda *a, **k: called.append("app")
+    )
+    monkeypatch.setattr(
+        FastAPIInstrumentor, "instrument", lambda *a, **k: called.append("global")
+    )
+
+    hostess_fastapi.post_instrument()
+    assert called == []
+    assert marker._marker_provider is not None
+
+
+def test_post_instrument_does_not_replace_tracer_provider(monkeypatch):
+    from opentelemetry import trace
+    from opentelemetry.sdk.trace import TracerProvider
+
+    monkeypatch.setenv("HOSTESS_OTEL_ENDPOINT", "http://hostess-otel:4318")
+    monkeypatch.setattr(
+        "opentelemetry.exporter.otlp.proto.http.metric_exporter.OTLPMetricExporter",
+        _FakeExporter,
+    )
+
+    current = trace.get_tracer_provider()
+    if not isinstance(current, TracerProvider):
+        current = TracerProvider()
+        trace.set_tracer_provider(current)
+    installed = trace.get_tracer_provider()
+
+    def _boom(*_a, **_k):
+        raise AssertionError("post_instrument must not call set_tracer_provider")
+
+    monkeypatch.setattr(trace, "set_tracer_provider", _boom)
+
+    hostess_fastapi.post_instrument()
+    assert trace.get_tracer_provider() is installed
+    assert marker._marker_provider is not None