containarium-telemetry 0.22.0__tar.gz

containarium_telemetry-0.22.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: containarium-telemetry
+Version: 0.22.0
+Summary: Containarium telemetry distro for Python — opinionated OpenTelemetry init that pairs with the Containarium platform's monitoring infrastructure.
+Author: FootprintAI
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/footprintai/containarium
+Project-URL: Documentation, https://github.com/footprintai/containarium/blob/main/docs/TELEMETRY-DISTRO-DESIGN.md
+Project-URL: Repository, https://github.com/footprintai/containarium
+Project-URL: Issues, https://github.com/footprintai/containarium/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
+Requires-Dist: opentelemetry-instrumentation>=0.48b0
+Provides-Extra: flask
+Requires-Dist: opentelemetry-instrumentation-flask>=0.48b0; extra == "flask"
+Provides-Extra: fastapi
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == "fastapi"
+Provides-Extra: django
+Requires-Dist: opentelemetry-instrumentation-django>=0.48b0; extra == "django"
+Provides-Extra: requests
+Requires-Dist: opentelemetry-instrumentation-requests>=0.48b0; extra == "requests"
+Provides-Extra: httpx
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0; extra == "httpx"
+Provides-Extra: sqlalchemy
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.48b0; extra == "sqlalchemy"
+Provides-Extra: asyncpg
+Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.48b0; extra == "asyncpg"
+Provides-Extra: psycopg
+Requires-Dist: opentelemetry-instrumentation-psycopg>=0.48b0; extra == "psycopg"
+Provides-Extra: redis
+Requires-Dist: opentelemetry-instrumentation-redis>=0.48b0; extra == "redis"
+Provides-Extra: logging
+Requires-Dist: opentelemetry-instrumentation-logging>=0.48b0; extra == "logging"
+Provides-Extra: all
+Requires-Dist: opentelemetry-instrumentation-flask>=0.48b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-django>=0.48b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-requests>=0.48b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.48b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.48b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-psycopg>=0.48b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-redis>=0.48b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-logging>=0.48b0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: flask>=2.0; extra == "dev"
+Requires-Dist: opentelemetry-instrumentation-flask>=0.48b0; extra == "dev"

containarium_telemetry-0.22.0/pyproject.toml

@@ -0,0 +1,103 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "containarium-telemetry"
+version = "0.22.0"
+description = "Containarium telemetry distro for Python — opinionated OpenTelemetry init that pairs with the Containarium platform's monitoring infrastructure."
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "FootprintAI" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "opentelemetry-api>=1.27.0",
+    "opentelemetry-sdk>=1.27.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.27.0",
+    # Required for ContainariumDistro / Configurator entry points and
+    # the auto-instrumentation runtime used by `containarium-instrument`.
+    "opentelemetry-instrumentation>=0.48b0",
+]
+
+[project.urls]
+Homepage = "https://github.com/footprintai/containarium"
+Documentation = "https://github.com/footprintai/containarium/blob/main/docs/TELEMETRY-DISTRO-DESIGN.md"
+Repository = "https://github.com/footprintai/containarium"
+Issues = "https://github.com/footprintai/containarium/issues"
+
+# Per-framework extras pull in the upstream OTel instrumentation package
+# for that framework. The instrumentation packages themselves declare
+# the framework as a transitive dep, so e.g. `pip install
+# containarium-telemetry[flask]` installs flask too. Tenants who already
+# pin their framework get no version conflict because the OTel
+# instrumentation packages declare ranges, not pins.
+[project.optional-dependencies]
+flask = ["opentelemetry-instrumentation-flask>=0.48b0"]
+fastapi = ["opentelemetry-instrumentation-fastapi>=0.48b0"]
+django = ["opentelemetry-instrumentation-django>=0.48b0"]
+requests = ["opentelemetry-instrumentation-requests>=0.48b0"]
+httpx = ["opentelemetry-instrumentation-httpx>=0.48b0"]
+sqlalchemy = ["opentelemetry-instrumentation-sqlalchemy>=0.48b0"]
+asyncpg = ["opentelemetry-instrumentation-asyncpg>=0.48b0"]
+psycopg = ["opentelemetry-instrumentation-psycopg>=0.48b0"]
+redis = ["opentelemetry-instrumentation-redis>=0.48b0"]
+logging = ["opentelemetry-instrumentation-logging>=0.48b0"]
+# `all` is the convenience bundle — recommended default for greenfield
+# apps. Tenants with image-size sensitivity pin individual extras.
+all = [
+    "opentelemetry-instrumentation-flask>=0.48b0",
+    "opentelemetry-instrumentation-fastapi>=0.48b0",
+    "opentelemetry-instrumentation-django>=0.48b0",
+    "opentelemetry-instrumentation-requests>=0.48b0",
+    "opentelemetry-instrumentation-httpx>=0.48b0",
+    "opentelemetry-instrumentation-sqlalchemy>=0.48b0",
+    "opentelemetry-instrumentation-asyncpg>=0.48b0",
+    "opentelemetry-instrumentation-psycopg>=0.48b0",
+    "opentelemetry-instrumentation-redis>=0.48b0",
+    "opentelemetry-instrumentation-logging>=0.48b0",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    # Used by integration tests for the instrumentor auto-discovery path.
+    "flask>=2.0",
+    "opentelemetry-instrumentation-flask>=0.48b0",
+]
+
+# `containarium-instrument` is always installed (D8) — it's a console
+# script alias over `opentelemetry-instrument` that adds --dry-run +
+# branding.
+[project.scripts]
+containarium-instrument = "containarium_telemetry._exec_shim:main"
+
+# Entry points the OTel auto-instrumentation runtime discovers. When
+# `opentelemetry-instrument` (or our `containarium-instrument` alias)
+# runs, it loads our Distro + Configurator so that the init we run via
+# direct API call also runs via the auto-instrument path.
+[project.entry-points."opentelemetry_distro"]
+containarium = "containarium_telemetry._distro:ContainariumDistro"
+
+[project.entry-points."opentelemetry_configurator"]
+containarium = "containarium_telemetry._distro:ContainariumConfigurator"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+containarium_telemetry = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

containarium_telemetry-0.22.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

containarium_telemetry-0.22.0/src/containarium_telemetry/__init__.py

@@ -0,0 +1,16 @@
+"""Containarium telemetry distro for Python.
+
+Public API:
+
+    from containarium_telemetry import init, Shutdown
+
+    handle = init()
+    ...
+    handle.shutdown(timeout_s=5.0)
+
+See docs/TELEMETRY-DISTRO-DESIGN.md for the full contract.
+"""
+from ._init import Shutdown, init
+from ._version import __version__
+
+__all__ = ["init", "Shutdown", "__version__"]

containarium_telemetry-0.22.0/src/containarium_telemetry/_config.py

@@ -0,0 +1,54 @@
+"""Env-driven configuration for the distro.
+
+The dataclass exists so tests can construct it directly without
+monkey-patching os.environ — every other module in the distro reads
+from a DistroConfig, never from os.getenv().
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class DistroConfig:
+    # OTel-standard env vars (the SDK also reads these directly; we
+    # capture them here for diagnostics and for code paths that need
+    # to branch on their presence).
+    endpoint: Optional[str]
+    service_name: Optional[str]
+    resource_attributes: Optional[str]
+    headers: Optional[str]
+    protocol: Optional[str]
+
+    # Containarium-stamped env vars (split form per
+    # docs/OTEL-AGENT-RELAY-DESIGN.md decision #5).
+    container_id: Optional[str]
+    backend_id: Optional[str]
+    tenant_id: Optional[str]
+
+    # Tenant-controlled, used for service.version stamping.
+    service_version: Optional[str]
+
+    @classmethod
+    def from_env(cls, env: Optional[dict] = None) -> "DistroConfig":
+        e = env if env is not None else os.environ
+
+        def get(key: str) -> Optional[str]:
+            v = e.get(key)
+            if v is None or v == "":
+                return None
+            return v
+
+        return cls(
+            endpoint=get("OTEL_EXPORTER_OTLP_ENDPOINT"),
+            service_name=get("OTEL_SERVICE_NAME"),
+            resource_attributes=get("OTEL_RESOURCE_ATTRIBUTES"),
+            headers=get("OTEL_EXPORTER_OTLP_HEADERS"),
+            protocol=get("OTEL_EXPORTER_OTLP_PROTOCOL"),
+            container_id=get("CONTAINARIUM_CONTAINER_ID"),
+            backend_id=get("CONTAINARIUM_BACKEND_ID"),
+            tenant_id=get("CONTAINARIUM_TENANT_ID"),
+            service_version=get("SERVICE_VERSION"),
+        )

containarium_telemetry-0.22.0/src/containarium_telemetry/_distro.py

@@ -0,0 +1,66 @@
+"""OTel Distro + Configurator entry points for the auto-instrument path.
+
+When the user runs `containarium-instrument python app.py` (or the
+upstream `opentelemetry-instrument` with this package installed), the
+OTel runtime loads:
+
+  1. ContainariumDistro._configure()  — sets exporter env defaults
+  2. ContainariumConfigurator._configure() — runs our init()
+  3. Then iterates registered opentelemetry_instrumentor entry points
+     and calls .instrument() on each.
+
+Our init() detects the auto-instrument context via the
+_CONTAINARIUM_TELEMETRY_AUTO_INSTRUMENT env sentinel and skips its own
+instrumentation-registration step so we don't double-instrument.
+"""
+from __future__ import annotations
+
+import logging
+import os
+
+from opentelemetry.instrumentation.distro import BaseDistro
+from opentelemetry.sdk._configuration import _BaseConfigurator
+
+logger = logging.getLogger("containarium_telemetry")
+
+# Sentinel set by ContainariumConfigurator. init() reads it to decide
+# whether to register instrumentors itself or defer to the runtime.
+AUTO_INSTRUMENT_ENV_KEY = "_CONTAINARIUM_TELEMETRY_AUTO_INSTRUMENT"
+
+
+class ContainariumDistro(BaseDistro):
+    """OTel Distro plugin — sets exporter env defaults.
+
+    setdefault throughout: the user's explicit env always wins. We're a
+    distro, not a policy enforcer.
+    """
+
+    def _configure(self, **kwargs) -> None:
+        # OTLP metrics by default — matches the central collector.
+        os.environ.setdefault("OTEL_METRICS_EXPORTER", "otlp")
+        # v1 collector is metrics-only (decision D4); muting trace + log
+        # export avoids the SDK fighting an empty endpoint. v2 flips
+        # these to "otlp" when Tempo + Loki land.
+        os.environ.setdefault("OTEL_TRACES_EXPORTER", "none")
+        os.environ.setdefault("OTEL_LOGS_EXPORTER", "none")
+        # Pin HTTP/protobuf — the protocol the central collector and
+        # otel-sidecar both speak.
+        os.environ.setdefault("OTEL_EXPORTER_OTLP_PROTOCOL", "http/protobuf")
+
+
+class ContainariumConfigurator(_BaseConfigurator):
+    """OTel Configurator plugin — installs MeterProvider via init().
+
+    Configurators are responsible for actually wiring up the SDK
+    providers (TracerProvider, MeterProvider, LoggerProvider). Only
+    one configurator runs in the auto-instrument flow — ours wins
+    because we register an entry point.
+    """
+
+    def _configure(self, **kwargs) -> None:
+        os.environ[AUTO_INSTRUMENT_ENV_KEY] = "1"
+        # Lazy import so the OTLP exporter module isn't loaded when
+        # only the Distro half of the entry-point pair fires.
+        from ._init import init
+
+        init()

containarium_telemetry-0.22.0/src/containarium_telemetry/_dry_run.py

@@ -0,0 +1,64 @@
+"""Pretty-printer for the resolved telemetry config.
+
+Used by `containarium-instrument --dry-run` (D12). Reports endpoint,
+protocol, resource attrs, headers (bearer redacted by default), and
+whether the pipeline would actually wire up given the env.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ._config import DistroConfig
+from ._version import __version__
+
+_REDACTED_HEADER_KEYS = frozenset({"authorization", "x-api-key"})
+
+
+def format_config(config: DistroConfig, *, redact_bearer: bool = True) -> str:
+    """Return a human-readable rendering of the resolved config."""
+    lines = [
+        "# containarium-telemetry resolved config",
+        f"distro_version       : {__version__}",
+        f"endpoint             : {config.endpoint or '<unset>'}",
+        f"protocol             : {config.protocol or '<default: http/protobuf>'}",
+        f"service_name         : {config.service_name or '<unset — SDK will default to unknown_service>'}",
+        f"resource_attributes  : {config.resource_attributes or '<unset>'}",
+        f"headers              : {_format_headers(config.headers, redact_bearer)}",
+        "",
+        "# Containarium identity (CONTAINARIUM_* env)",
+        f"container.id         : {config.container_id or '<unset>'}",
+        f"backend.id           : {config.backend_id or '<unset>'}",
+        f"tenant.id            : {config.tenant_id or '<unset>'}",
+        f"service.version      : {config.service_version or '<unset>'}",
+        "",
+        "# Defended distro stamp (always present, never overridable)",
+        f"containarium.distro  : py/{__version__}",
+        "",
+    ]
+
+    if config.endpoint:
+        lines.append("Status: telemetry pipeline will be configured.")
+    else:
+        lines.append("Status: TELEMETRY WILL BE NO-OP. Endpoint env not set; init() will fail-open.")
+        lines.append("Enable monitoring on this LXC with:")
+        lines.append("  containarium monitoring enable <username>")
+
+    return "\n".join(lines)
+
+
+def _format_headers(raw: Optional[str], redact: bool) -> str:
+    if not raw:
+        return "<unset>"
+    if not redact:
+        return raw
+    parts = []
+    for kv in raw.split(","):
+        if "=" not in kv:
+            parts.append(kv)
+            continue
+        k, _ = kv.split("=", 1)
+        if k.strip().lower() in _REDACTED_HEADER_KEYS:
+            parts.append(f"{k.strip()}=<redacted>")
+        else:
+            parts.append(kv)
+    return ",".join(parts)

containarium_telemetry-0.22.0/src/containarium_telemetry/_exec_shim.py

@@ -0,0 +1,92 @@
+"""containarium-instrument console script.
+
+Thin alias over `opentelemetry-instrument` (decision D8 — always
+installed). Adds:
+
+  - `--dry-run`: prints resolved config and exits without launching
+    the app (D12).
+  - `--version` / `--help`: branding + usage.
+
+Anything else execvp()s `opentelemetry-instrument` with the same args
+and lets the upstream runtime drive the auto-instrument flow. Our
+Distro + Configurator are registered as opentelemetry entry points, so
+the upstream `opentelemetry-instrument` picks up our customizations
+without us forking its argv parser.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from typing import List, Optional
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    if not argv or argv[0] in ("-h", "--help"):
+        _print_help()
+        return 0 if argv else 2
+
+    if argv[0] in ("-V", "--version"):
+        from ._version import __version__
+
+        print(f"containarium-instrument {__version__}")
+        return 0
+
+    if argv[0] == "--dry-run":
+        return _dry_run()
+
+    # Delegate to upstream. execvp replaces the process so any state
+    # we set on the way in (e.g. env defaults from importing this
+    # module's deps) carries forward.
+    cmd = "opentelemetry-instrument"
+    try:
+        os.execvp(cmd, [cmd] + argv)
+    except FileNotFoundError:
+        print(
+            f"containarium-instrument: '{cmd}' not found in PATH. "
+            "Reinstall containarium-telemetry to pull the "
+            "opentelemetry-instrumentation dep, or pip install "
+            "opentelemetry-instrumentation directly.",
+            file=sys.stderr,
+        )
+        return 127
+    # Unreachable on success — execvp replaces the process.
+    return 0
+
+
+def _dry_run() -> int:
+    from ._config import DistroConfig
+    from ._dry_run import format_config
+
+    config = DistroConfig.from_env()
+    print(format_config(config))
+    return 0
+
+
+def _print_help() -> None:
+    print(
+        """containarium-instrument — Run a Python app with the Containarium telemetry distro.
+
+Usage:
+  containarium-instrument [--dry-run | --version | --help] <command> [args ...]
+
+Options:
+  --dry-run    Print the resolved telemetry config (endpoint, resource
+               attrs, redacted headers, distro version) and exit. Does
+               NOT launch the wrapped command.
+  --version    Print distro version and exit.
+  --help       Show this help and exit.
+
+Without a flag, exec()s opentelemetry-instrument with the same args.
+Our Distro + Configurator are registered as OTel entry points, so
+auto-instrumentation picks up the Containarium identity stamping and
+OTLP/HTTP defaults transparently.
+
+Examples:
+  containarium-instrument python app.py
+  containarium-instrument --dry-run
+  containarium-instrument python -m flask run
+"""
+    )

containarium_telemetry-0.22.0/src/containarium_telemetry/_init.py

@@ -0,0 +1,156 @@
+"""Distro init — the public entry point.
+
+Contract (per docs/TELEMETRY-DISTRO-DESIGN.md):
+- Always fail-open. Missing endpoint → WARN + no-op handle (D10).
+- Idempotent. Repeat calls log at DEBUG and return the existing handle.
+- The OTLPMetricExporter reads OTEL_EXPORTER_OTLP_{ENDPOINT,HEADERS,
+  PROTOCOL} from env directly, so we do not pass them as constructor
+  args — that would shadow user overrides we're meant to honor.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Dict, Optional
+
+from opentelemetry import metrics, trace
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import (
+    OTLPMetricExporter,
+)
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.trace import NoOpTracerProvider
+
+from ._config import DistroConfig
+from ._distro import AUTO_INSTRUMENT_ENV_KEY
+from ._instrumentations import InstrumentationsArg, register_instrumentations
+from ._resource import build_resource
+
+logger = logging.getLogger("containarium_telemetry")
+
+_initialized: bool = False
+_shutdown_handle: Optional["Shutdown"] = None
+
+
+class Shutdown:
+    """Idempotent shutdown handle returned by init()."""
+
+    def __init__(self, provider: Optional[MeterProvider]):
+        self._provider = provider
+        self._done = False
+
+    def shutdown(self, timeout_s: float = 5.0) -> None:
+        if self._done:
+            return
+        self._done = True
+        if self._provider is None:
+            return
+        try:
+            self._provider.shutdown(timeout_millis=int(timeout_s * 1000))
+        except Exception as e:  # noqa: BLE001 — never raise from shutdown
+            logger.warning("containarium_telemetry shutdown failed: %s", e)
+
+    def __call__(self, timeout_s: float = 5.0) -> None:
+        # Lets callers use the handle directly as `handle()` instead of
+        # `handle.shutdown()` — convenient with atexit.register().
+        self.shutdown(timeout_s)
+
+
+def init(
+    service_name: Optional[str] = None,
+    extra_attrs: Optional[Dict[str, str]] = None,
+    instrumentations: InstrumentationsArg = "auto",
+    metric_export_interval_ms: int = 5_000,
+    metric_export_timeout_ms: int = 10_000,
+) -> Shutdown:
+    """Initialize the distro. Returns an idempotent Shutdown handle.
+
+    Args:
+        service_name: Override OTEL_SERVICE_NAME if not already set.
+        extra_attrs: Extra resource attributes — win over env attrs
+            (precedence #5 in TELEMETRY-DISTRO-DESIGN.md).
+        instrumentations: "auto" (default — every installed
+            opentelemetry_instrumentor), "off", or a list of names.
+            Skipped when invoked from `containarium-instrument` /
+            `opentelemetry-instrument` (the runtime handles it).
+        metric_export_interval_ms: Periodic export tick. Default 5s,
+            matching the sidecar's batch processor.
+        metric_export_timeout_ms: Per-export timeout. Default 10s.
+
+    Fail-open: missing OTEL_EXPORTER_OTLP_ENDPOINT logs WARN and returns
+    a no-op handle. The app never crashes because telemetry isn't wired.
+    """
+    global _initialized, _shutdown_handle
+
+    if _initialized:
+        logger.debug("init() called twice — returning existing handle")
+        return _shutdown_handle  # type: ignore[return-value]
+
+    if service_name:
+        # setdefault — explicit user env still wins over the arg.
+        os.environ.setdefault("OTEL_SERVICE_NAME", service_name)
+
+    config = DistroConfig.from_env()
+
+    if not config.endpoint:
+        logger.warning(
+            "containarium_telemetry: OTEL_EXPORTER_OTLP_ENDPOINT not set; "
+            "telemetry will be a no-op. Enable monitoring on the LXC with "
+            "`containarium monitoring enable <username>`."
+        )
+        _shutdown_handle = Shutdown(None)
+        _initialized = True
+        return _shutdown_handle
+
+    try:
+        resource = build_resource(config, extra_attrs=extra_attrs)
+        exporter = OTLPMetricExporter()
+        reader = PeriodicExportingMetricReader(
+            exporter,
+            export_interval_millis=metric_export_interval_ms,
+            export_timeout_millis=metric_export_timeout_ms,
+        )
+        provider = MeterProvider(resource=resource, metric_readers=[reader])
+        metrics.set_meter_provider(provider)
+    except Exception as e:  # noqa: BLE001 — fail-open per contract
+        logger.warning("containarium_telemetry init failed: %s", e)
+        _shutdown_handle = Shutdown(None)
+        _initialized = True
+        return _shutdown_handle
+
+    # No-op tracer provider so apps that call trace.get_tracer(...)
+    # don't crash — v1 collector accepts metrics only (D4). The v2
+    # traces pipeline will replace this with a real provider.
+    _set_noop_tracer_provider_if_unset()
+
+    # Skip instrumentation registration when invoked from the
+    # auto-instrument runtime (containarium-instrument /
+    # opentelemetry-instrument) — the runtime registers them itself
+    # after we return.
+    if os.environ.get(AUTO_INSTRUMENT_ENV_KEY) != "1":
+        register_instrumentations(instrumentations)
+
+    _shutdown_handle = Shutdown(provider)
+    _initialized = True
+    return _shutdown_handle
+
+
+def _set_noop_tracer_provider_if_unset() -> None:
+    """Install NoOpTracerProvider only if no real one is configured.
+
+    OTel's default `ProxyTracerProvider` already returns no-op spans
+    when nothing has been set, so this is mostly belt-and-braces — but
+    it makes the v1→v2 transition cleaner (one call to flip).
+    """
+    current = trace.get_tracer_provider()
+    # Only stamp if nothing real has been installed yet. Don't clobber
+    # an app that already wired its own tracer.
+    if type(current).__name__ == "ProxyTracerProvider":
+        trace.set_tracer_provider(NoOpTracerProvider())
+
+
+def _reset_for_tests() -> None:
+    """Reset module-level init state. Tests only — not part of the API."""
+    global _initialized, _shutdown_handle
+    _initialized = False
+    _shutdown_handle = None