dash0-opentelemetry 0.3.1__py3-none-any.whl

dash0/opentelemetry/_environment_variables.py

@@ -0,0 +1,41 @@
+"""Environment variables read and written by the Dash0 distribution.
+
+Grouped here so the distro, the configurator and the resource detection share a
+single definition of each name.
+"""
+
+# --- Dash0-specific knobs (mirrors the Node.js distribution) ---
+
+DASH0_DISABLE = "DASH0_DISABLE"
+"""When set to ``true`` the distribution does nothing at all."""
+
+DASH0_OTEL_COLLECTOR_BASE_URL = "DASH0_OTEL_COLLECTOR_BASE_URL"
+"""Base URL of the collector to export to. Required; without it the
+distribution disables itself, because there is nowhere to send telemetry."""
+
+DASH0_AUTOMATIC_SERVICE_NAME = "DASH0_AUTOMATIC_SERVICE_NAME"
+"""Set to ``false`` to opt out of deriving a fallback ``service.name``."""
+
+DASH0_BOOTSTRAP_SPAN = "DASH0_BOOTSTRAP_SPAN"
+"""When set, a single span with this name is emitted once at startup."""
+
+DASH0_FLUSH_ON_SIGTERM_SIGINT = "DASH0_FLUSH_ON_SIGTERM_SIGINT"
+"""Set to ``true`` to flush telemetry on SIGTERM/SIGINT before exiting."""
+
+
+# --- Standard OpenTelemetry variables the distribution defaults ---
+
+OTEL_TRACES_EXPORTER = "OTEL_TRACES_EXPORTER"
+OTEL_METRICS_EXPORTER = "OTEL_METRICS_EXPORTER"
+OTEL_LOGS_EXPORTER = "OTEL_LOGS_EXPORTER"
+OTEL_EXPORTER_OTLP_PROTOCOL = "OTEL_EXPORTER_OTLP_PROTOCOL"
+OTEL_EXPORTER_OTLP_TRACES_PROTOCOL = "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"
+OTEL_EXPORTER_OTLP_METRICS_PROTOCOL = "OTEL_EXPORTER_OTLP_METRICS_PROTOCOL"
+OTEL_EXPORTER_OTLP_LOGS_PROTOCOL = "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL"
+OTEL_EXPORTER_OTLP_ENDPOINT = "OTEL_EXPORTER_OTLP_ENDPOINT"
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"
+OTEL_EXPORTER_OTLP_METRICS_ENDPOINT = "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"
+OTEL_EXPORTER_OTLP_LOGS_ENDPOINT = "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT"
+OTEL_SERVICE_NAME = "OTEL_SERVICE_NAME"
+OTEL_RESOURCE_ATTRIBUTES = "OTEL_RESOURCE_ATTRIBUTES"
+OTEL_SDK_DISABLED = "OTEL_SDK_DISABLED"

dash0/opentelemetry/configurator.py

@@ -0,0 +1,77 @@
+"""SDK configurator for the Dash0 OpenTelemetry distribution.
+
+Registered as the single ``opentelemetry_configurator`` entry point. It runs
+after :class:`~dash0.opentelemetry.distro.Dash0Distro` has set the environment,
+so it lets the standard OpenTelemetry SDK configurator build the providers,
+exporters and Resource from that environment, then adds two Dash0 behaviors from
+the Node.js distribution: an optional startup ("bootstrap") span and optional
+graceful flushing on SIGTERM/SIGINT.
+
+Normal-exit flushing is already handled by the SDK: the tracer/meter/logger
+providers register ``atexit`` shutdown hooks. The signal handling below covers
+container termination, where ``atexit`` does not run by default.
+"""
+
+import signal
+from logging import getLogger
+from os import environ, getpid, kill
+
+from opentelemetry import _logs, metrics, trace
+from opentelemetry.sdk._configuration import _OTelSDKConfigurator
+
+from ._environment_variables import (
+    DASH0_BOOTSTRAP_SPAN,
+    DASH0_FLUSH_ON_SIGTERM_SIGINT,
+)
+from .settings import evaluate_gate, is_true
+
+_logger = getLogger(__name__)
+
+
+class Dash0Configurator(_OTelSDKConfigurator):
+    """Configure the OpenTelemetry SDK for the Dash0 distribution."""
+
+    def _configure(self, **kwargs):
+        enabled, reason = evaluate_gate()
+        if not enabled:
+            _logger.debug(
+                "Dash0 distribution disabled (%s); skipping SDK configuration",
+                reason,
+            )
+            return
+
+        super()._configure(**kwargs)
+
+        bootstrap_span_name = environ.get(DASH0_BOOTSTRAP_SPAN)
+        if bootstrap_span_name:
+            trace.get_tracer("dash0-python-distribution").start_span(
+                bootstrap_span_name
+            ).end()
+
+        if is_true(environ.get(DASH0_FLUSH_ON_SIGTERM_SIGINT)):
+
+            def _flush_and_reraise(signum, _frame):
+                for provider in (
+                    trace.get_tracer_provider(),
+                    metrics.get_meter_provider(),
+                    _logs.get_logger_provider(),
+                ):
+                    shutdown = getattr(provider, "shutdown", None)
+                    if shutdown is not None:
+                        try:
+                            shutdown()
+                        except Exception:  # pylint: disable=broad-except
+                            _logger.exception("dash0: error shutting down %s", provider)
+                # Restore the default disposition and re-raise so the process
+                # terminates with the expected exit semantics.
+                signal.signal(signum, signal.SIG_DFL)
+                kill(getpid(), signum)
+
+            try:
+                signal.signal(signal.SIGTERM, _flush_and_reraise)
+                signal.signal(signal.SIGINT, _flush_and_reraise)
+            except ValueError:
+                # signal handlers can only be installed from the main thread
+                _logger.debug(
+                    "dash0: not on main thread, SIGTERM/SIGINT flush not installed"
+                )

dash0/opentelemetry/distro.py

@@ -0,0 +1,218 @@
+"""Dash0 OpenTelemetry distribution.
+
+Provides :class:`Dash0Distro`, the ``opentelemetry_distro`` entry point activated
+by ``opentelemetry-instrument`` when the Dash0 distribution is installed. It runs
+before the configurator, so it is where the distribution:
+
+* gates itself off if disabled or if no collector endpoint is configured;
+* selects the pure-Python OTLP exporters (no native dependencies, safe to
+  inject) matching the configured OTLP protocol — ``http/protobuf`` by
+  default, ``grpc`` when requested — and points them at the Dash0 collector;
+* injects the detected resource attributes (distro name/version, a fallback
+  service name, and the Kubernetes pod UID) so the SDK's Resource picks them up;
+* activates every instrumentor defensively, so a single failing instrumentor
+  cannot abort auto-instrumentation of an injected process.
+
+This mirrors the Dash0 Node.js distribution, adapted to Python's distro/
+configurator machinery.
+"""
+
+from logging import getLogger
+from os import environ
+from urllib.parse import urlparse, urlunparse
+
+from opentelemetry.instrumentation.distro import BaseDistro
+
+from ._environment_variables import (
+    DASH0_OTEL_COLLECTOR_BASE_URL,
+    OTEL_EXPORTER_OTLP_ENDPOINT,
+    OTEL_EXPORTER_OTLP_LOGS_ENDPOINT,
+    OTEL_EXPORTER_OTLP_LOGS_PROTOCOL,
+    OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,
+    OTEL_EXPORTER_OTLP_METRICS_PROTOCOL,
+    OTEL_EXPORTER_OTLP_PROTOCOL,
+    OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+    OTEL_EXPORTER_OTLP_TRACES_PROTOCOL,
+    OTEL_LOGS_EXPORTER,
+    OTEL_METRICS_EXPORTER,
+    OTEL_SDK_DISABLED,
+    OTEL_TRACES_EXPORTER,
+)
+from .resource import apply_detected_resource_attributes
+from .settings import evaluate_gate
+from .version import __version__
+
+_logger = getLogger(__name__)
+
+_GRPC_PROTOCOL = "grpc"
+_HTTP_PROTOCOL = "http/protobuf"
+
+# Entry-point names under which the pure-Python (pyproto) exporters register
+# themselves, keyed by OTLP protocol. In an injected tree only the pyproto
+# exporters ship under these names, so they resolve to the pure-Python
+# implementations rather than the protobuf/grpcio ones.
+_PYPROTO_EXPORTERS_BY_PROTOCOL = {
+    _HTTP_PROTOCOL: "otlp_proto_http",
+    _GRPC_PROTOCOL: "otlp_proto_grpc",
+}
+
+_DEFAULT_PROTOCOL = _HTTP_PROTOCOL
+
+# Default OTLP receiver port per protocol. OTLP/gRPC and OTLP/HTTP conventionally
+# listen on different ports, so a single collector base URL cannot address both.
+_OTLP_DEFAULT_PORT = {_GRPC_PROTOCOL: 4317, _HTTP_PROTOCOL: 4318}
+
+# Per-signal wiring: the exporter-selection variable, the per-signal protocol
+# override, the per-signal endpoint override, and the OTLP/HTTP export path.
+_SIGNALS = (
+    (
+        OTEL_TRACES_EXPORTER,
+        OTEL_EXPORTER_OTLP_TRACES_PROTOCOL,
+        OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+        "v1/traces",
+    ),
+    (
+        OTEL_METRICS_EXPORTER,
+        OTEL_EXPORTER_OTLP_METRICS_PROTOCOL,
+        OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,
+        "v1/metrics",
+    ),
+    (
+        OTEL_LOGS_EXPORTER,
+        OTEL_EXPORTER_OTLP_LOGS_PROTOCOL,
+        OTEL_EXPORTER_OTLP_LOGS_ENDPOINT,
+        "v1/logs",
+    ),
+)
+
+
+def _per_signal_endpoint_override(base_endpoint, protocol, signal_path):
+    """Return the per-signal endpoint a signal on ``protocol`` needs, or ``None``
+    when the shared ``OTEL_EXPORTER_OTLP_ENDPOINT`` already resolves correctly.
+
+    OTLP/gRPC (default port 4317, address used as ``host:port``) and OTLP/HTTP
+    (default port 4318, signal path appended) cannot share one endpoint. When a
+    signal's protocol differs from the transport ``base_endpoint`` points at —
+    detected by its port being the *other* supported protocol's default — the
+    port is rewritten to this protocol's default so the single Dash0 collector
+    base URL still routes every signal correctly. For an HTTP signal the path is
+    appended here, because the exporter appends it only to the shared endpoint,
+    not to a per-signal one. A custom or absent port is left untouched (the
+    collector is assumed to serve that protocol there, or the user supplies an
+    explicit per-signal endpoint, which is always honored).
+    """
+    parsed = urlparse(base_endpoint)
+    try:
+        current_port = parsed.port
+    except ValueError:
+        return None
+    other_protocol_ports = {
+        port for candidate, port in _OTLP_DEFAULT_PORT.items() if candidate != protocol
+    }
+    if current_port not in other_protocol_ports:
+        return None
+    host = parsed.hostname or ""
+    if ":" in host:  # bracket an IPv6 literal so the port stays unambiguous
+        host = f"[{host}]"
+    netloc = f"{host}:{_OTLP_DEFAULT_PORT[protocol]}"
+    if "@" in parsed.netloc:  # keep userinfo credentials, verbatim
+        netloc = f"{parsed.netloc.rsplit('@', 1)[0]}@{netloc}"
+    path = parsed.path
+    if protocol == _HTTP_PROTOCOL:
+        separator = "" if path.endswith("/") else "/"
+        path = path + separator + signal_path
+    return urlunparse(parsed._replace(netloc=netloc, path=path))
+
+
+# Instrumentor entry-point names that must never be activated by this
+# distribution. Empty by default; the standard OTEL_PYTHON_DISABLED_INSTRUMENTATIONS
+# variable is also honored by the auto-instrumentation loader.
+_DISABLED_INSTRUMENTORS = frozenset()
+
+
+class Dash0Distro(BaseDistro):
+    """OpenTelemetry distribution configured for Dash0."""
+
+    def _configure(self, **kwargs):
+        enabled, reason = evaluate_gate()
+        if not enabled:
+            # Make the SDK a no-op so nothing is exported, matching the Node.js
+            # distribution's "do nothing" behavior when disabled/misconfigured.
+            environ[OTEL_SDK_DISABLED] = "true"
+            _logger.warning(
+                "Dash0 distribution disabled: %s. No telemetry will be sent.",
+                reason,
+            )
+            return
+
+        default_protocol = environ.setdefault(
+            OTEL_EXPORTER_OTLP_PROTOCOL, _DEFAULT_PROTOCOL
+        )
+        environ.setdefault(
+            OTEL_EXPORTER_OTLP_ENDPOINT,
+            environ[DASH0_OTEL_COLLECTOR_BASE_URL],
+        )
+        # The effective shared endpoint (a user-set value is honored above), used
+        # to derive per-signal endpoints when signals resolve to different OTLP
+        # transports.
+        base_endpoint = environ[OTEL_EXPORTER_OTLP_ENDPOINT]
+        for (
+            exporter_variable,
+            protocol_variable,
+            endpoint_variable,
+            signal_path,
+        ) in _SIGNALS:
+            protocol = environ.get(protocol_variable, default_protocol)
+            exporter = _PYPROTO_EXPORTERS_BY_PROTOCOL.get(protocol)
+            if exporter is None:
+                _logger.warning(
+                    "dash0: unsupported OTLP protocol %r in %s; defaulting %s to"
+                    " the %r exporter",
+                    protocol,
+                    protocol_variable
+                    if protocol_variable in environ
+                    else OTEL_EXPORTER_OTLP_PROTOCOL,
+                    exporter_variable,
+                    _PYPROTO_EXPORTERS_BY_PROTOCOL[_DEFAULT_PROTOCOL],
+                )
+                protocol = _DEFAULT_PROTOCOL
+                exporter = _PYPROTO_EXPORTERS_BY_PROTOCOL[protocol]
+            selected_exporter = environ.setdefault(exporter_variable, exporter)
+            if selected_exporter != exporter:
+                # The user picked this signal's exporter directly; the distro
+                # cannot know which transport it speaks, so deriving an endpoint
+                # from the protocol variables could redirect a working exporter
+                # to the wrong port.
+                continue
+            signal_endpoint = _per_signal_endpoint_override(
+                base_endpoint, protocol, signal_path
+            )
+            if signal_endpoint is not None and endpoint_variable not in environ:
+                environ[endpoint_variable] = signal_endpoint
+                _logger.debug(
+                    "dash0: shared endpoint %r targets the other OTLP transport;"
+                    " derived %s=%s for protocol %r",
+                    base_endpoint,
+                    endpoint_variable,
+                    signal_endpoint,
+                    protocol,
+                )
+
+        apply_detected_resource_attributes(__version__)
+
+    def load_instrumentor(self, entry_point, **kwargs):
+        enabled, _ = evaluate_gate()
+        if not enabled:
+            return
+        if entry_point.name in _DISABLED_INSTRUMENTORS:
+            _logger.debug(
+                "dash0: instrumentor %s is disabled, skipping", entry_point.name
+            )
+            return
+        try:
+            super().load_instrumentor(entry_point, **kwargs)
+        except Exception:  # pylint: disable=broad-except
+            _logger.exception(
+                "dash0: instrumentor %s failed to load, continuing without it",
+                entry_point.name,
+            )

dash0/opentelemetry/injector/sitecustomize.py

@@ -0,0 +1,282 @@
+# -*- coding: utf-8 -*-
+# Bootstrap script for injector-based activation of the Dash0 OpenTelemetry distribution for Python.
+#
+# This file ships inside the dash0-opentelemetry wheel, but it is not meant to be imported from its packaged
+# location (importing it executes it). Consumers that build an injectable tree — such as the dash0-operator's
+# instrumentation image build — install the distribution into a self-contained directory
+# (`pip install --target <dir> dash0-opentelemetry`) and copy this file from its packaged location to
+# `<dir>/sitecustomize.py`. The OpenTelemetry injector (https://github.com/open-telemetry/opentelemetry-injector) then
+# prepends `<dir>` to the PYTHONPATH environment variable of the processes to instrument, so that Python's `site`
+# machinery imports this script on interpreter startup. The script initializes the OpenTelemetry
+# auto-instrumentation after a set of safety checks, and deactivates itself (also for child processes) when any of
+# them fails.
+#
+# The dependency-conflict check reads `<dir>/all-dependencies.txt`, a flattened list of every requirement of the
+# injected tree (one PEP 508 requirement per line). The consumer generates that file when building `<dir>`; the
+# dash0-operator does so with pipdeptree (see images/instrumentation/python/extract-flattened-requirements.sh in the
+# dash0-operator repository).
+#
+# IMPORTANT: This file must be valid Python 2.7+. The injector prepends its directory to the PYTHONPATH of any Python
+# process, including processes running interpreters this distribution does not support; this script must at least
+# parse there, so it can deactivate itself gracefully instead of crashing the process. The PEP-263 encoding
+# declaration above must stay on the first or second line: without it, Python 2.7 rejects the file's non-ASCII
+# characters at parse time.
+
+from __future__ import print_function
+import os
+from os.path import dirname
+import sys
+from sys import path, version, version_info, stderr
+
+required_python_major_version = 3
+minimum_python_minor_version = 10
+
+# Packages of the OpenTelemetry API layer. Applications legitimately depend on them for manual instrumentation
+# without being auto-instrumented, so finding them in the application does not indicate double instrumentation.
+# (Version conflicts with them are still caught by the dependency conflict check.)
+double_instrumentation_check_excluded_packages = [
+    "opentelemetry-api",
+    "opentelemetry-semantic-conventions",
+]
+
+debug_enabled = os.environ.get("OTEL_INJECTOR_LOG_LEVEL") == "debug"
+
+
+def _log_as_json_to_stderr(level, message):
+    log_body = '{{"level": "{}", "message": "{}", "logger_name": "dash0"'.format(level, message)
+    if level == "warn":
+        # All warnings are Dash0 telemetry collection issues, hence adding the respective marker.
+        log_body += ', "dash0.monitoring.telemetry_collection_issue": true'
+    log_body += '}'
+    print(log_body, file=stderr)
+
+
+def _log_warn(message):
+    _log_as_json_to_stderr("warn", message)
+
+
+def _log_debug(message):
+    if debug_enabled:
+        _log_as_json_to_stderr("debug", message)
+
+
+_log_debug("running sitecustomize.py")
+_log_debug("PYTHONPATH: {}".format(os.environ.get("PYTHONPATH")))
+
+
+def _print_cannot_auto_instrument_message(reason):
+    if hasattr(sys, "argv"):
+        # If sys.argv is available, add the full command line (" ".join(sys.argv)) to the log message, so users know
+        # which Python process this is about.
+        _log_warn("cannot auto-instrument Python process: {} [{}]".format(reason, " ".join(sys.argv)))
+    else:
+        _log_warn("cannot auto-instrument Python process: {}".format(reason))
+
+
+def _self_deactivate(current_site):
+    # Starting child processes is quite common in Python (e.g. gunicorn etc.), and in particular, the OpenTelemetry
+    # instrumentation wrapper (e.g. opentelemetry-instrument python app.py, see
+    # https://opentelemetry.io/docs/zero-code/python) does this. When self-deactivating, we need to make sure that we
+    # do not only self-deactivate for the current process but also directly deactivate the OpenTelemetry injector's
+    # auto-instrumentation for Python for child processes.
+    # Failing to do so, in particular when the application is already instrumented with the opentelemetry-instrument
+    # wrapper, might crash the child process in case of conflicting opentelemetry-* dependency versions. The reason is
+    # that the child process started by opentelemetry-instrument will run e.g.
+    # https://github.com/open-telemetry/opentelemetry-python-contrib/blob/v0.53b0/opentelemetry-instrumentation/src/opentelemetry/instrumentation/auto_instrumentation/_load.py
+    # in the version brought in by the application. But _load.py then loads other opentelemetry-* dependencies from
+    # /__otel_auto_instrumentation/agents/python/glibc/opentelemetry/instrumentation/auto_instrumentation/_load.py,
+    # that is, from the packages that we provide. This happens _before_ this sitecustomize.py script runs in the child
+    # process. Hence, we cannot rely on sitecustomize.py to self-deactivate in the child process, but must enforce
+    # self-deactivation via environment variables.
+
+    # Remove this site from PYTHONPATH so child processes do not attempt to load packages from us. PYTHONPATH entries
+    # are separated by os.pathsep (":" on POSIX).
+    current_pythonpath = os.environ.get("PYTHONPATH", "")
+    pythonpath_entries = [entry for entry in current_pythonpath.split(os.pathsep) if entry != current_site]
+    new_pythonpath = os.pathsep.join(pythonpath_entries)
+    _log_debug('setting PYTHONPATH in _self_deactivate: "{}"'.format(new_pythonpath))
+    os.environ["PYTHONPATH"] = new_pythonpath
+
+    # The OpenTelemetry injector will also run for child processes, and it would bring back the PYTHONPATH modification
+    # which we have just removed. Instruct it to not do that by disabling Python auto-instrumentation.
+    _log_debug("clearing PYTHON_AUTO_INSTRUMENTATION_AGENT_PATH_PREFIX in _self_deactivate")
+    os.environ["PYTHON_AUTO_INSTRUMENTATION_AGENT_PATH_PREFIX"] = ""
+
+    if current_site in path:
+        # Remove this site from the _current_ Python process, so our packages do not interfere with the application's
+        # dependencies.
+        path.remove(current_site)
+
+
+def _shipped_opentelemetry_package_names(current_site):
+    # The OpenTelemetry packages this distribution ships: the injected tree at current_site is exactly the pinned
+    # dependency closure of dash0-opentelemetry (see its pyproject.toml), so enumerate the packages installed
+    # there instead of maintaining a hardcoded list. Only the OpenTelemetry-related packages count for the double
+    # instrumentation check; overlap on the general-purpose support packages we also ship (wrapt, psutil, ...) is
+    # common and is handled by the dependency version conflict check instead.
+    import importlib.metadata
+    names = set()
+    for dist in importlib.metadata.distributions(path=[current_site]):
+        name = dist.metadata["Name"]
+        if name is None:
+            continue
+        name = name.lower()
+        if name in double_instrumentation_check_excluded_packages:
+            continue
+        if name.startswith(("opentelemetry-", "dash0-")):
+            names.add(name)
+    return names
+
+
+def _check_for_double_instrumentation(current_site):
+    import importlib.metadata
+    packages_we_ship = _shipped_opentelemetry_package_names(current_site)
+    offending_packages = []
+    for dist in importlib.metadata.distributions():
+        name = dist.metadata["Name"]
+        if name is not None and name.lower() in packages_we_ship:
+            offending_packages.append(str(dist._path))
+    if offending_packages:
+        _self_deactivate(current_site)
+        _print_cannot_auto_instrument_message(
+            "The application has OpenTelemetry dependencies which indicate that it is already instrumented. The " +
+            "following problematic dependencies have been found: {}. ".format(", ".join(offending_packages)) +
+            "Skipping the Dash0 Python auto-instrumentation to avoid double instrumentation. Remove the mentioned "
+            "dependencies and make sure the opentelemetry-instrument wrapper executable is not used if you want to " +
+            "use Dash0's Python auto-instrumentation")
+        return True
+    return False
+
+
+def _read_all_dependencies():
+    """Read all flattened dependencies from all-dependencies.txt. Returns list of requirement strings or None on error."""
+    dependencies_file = os.path.join(dirname(__file__), "all-dependencies.txt")
+    requirements_to_check = []
+    try:
+        with open(dependencies_file, "r") as f:
+            for line in f:
+                line = line.strip()
+                # Skip empty lines and comments
+                if not line or line.startswith("#"):
+                    continue
+                requirements_to_check.append(line)
+        return requirements_to_check
+    except (IOError, OSError):
+        return None
+
+
+def _check_dependency_version_conflict(req_string, version_conflicts):
+    """Check for dependency version conflict for a given requirement.
+
+    Args:
+        req_string: Requirement string (e.g., "package-name >=1.0.0")
+        version_conflicts: Dictionary to accumulate version conflicts (modified in place)
+    """
+    import importlib.metadata
+    from packaging.requirements import Requirement
+    from packaging.version import Version
+
+    _log_debug("_check_dependency_version_conflict({})".format(req_string))
+    req = Requirement(req_string)
+
+    # Skip extras/markers for simplicity in conflict detection
+    if req.marker and not req.marker.evaluate():
+        return
+
+    if req.name == "pip":
+        # A lot of applications depend on pip implicitly, without actually importing it, ignore pip for the dependency
+        # conflict check.
+        return
+
+    try:
+        installed_distribution = importlib.metadata.distribution(req.name)
+        installed_version = Version(installed_distribution.version)
+        _log_debug("installed_version: {}".format(installed_version))
+
+        # Check if installed version satisfies the requirement
+        if req.specifier and installed_version not in req.specifier:
+            _log_debug("adding version conflict for {}".format(req.name))
+            version_conflicts[req.name] = {
+                "version_required": str(req.specifier),
+                "version_found": str(installed_version),
+            }
+    except importlib.metadata.PackageNotFoundError:
+        _log_debug("adding version error for {}".format(req.name))
+        version_conflicts[req.name] = {"error": "required package not found"}
+
+
+def import_distro():
+    _log_debug("checking Python version")
+    current_site = dirname(__file__)
+
+    # We cannot use `sys.version_info.major` or other named attributes, as they only got introduced only in Python 3.1.
+    if version_info[0] != required_python_major_version or version_info[1] < minimum_python_minor_version:
+        _self_deactivate(current_site)
+        _print_cannot_auto_instrument_message("unsupported Python version: {}".format(version))
+        return
+    _log_debug("found eligible Python version: {}".format(version_info))
+
+    # The Dash0 Python distribution requires DASH0_OTEL_COLLECTOR_BASE_URL to activate and derives its OTLP endpoint
+    # from it. The Dash0 operator sets OTEL_EXPORTER_OTLP_ENDPOINT; bridge it here so the distribution activates
+    # without requiring operator-side changes.
+    if not os.environ.get("DASH0_OTEL_COLLECTOR_BASE_URL"):
+        otlp_endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
+        if otlp_endpoint:
+            _log_debug("bridging OTEL_EXPORTER_OTLP_ENDPOINT to DASH0_OTEL_COLLECTOR_BASE_URL: {}".format(otlp_endpoint))
+            os.environ["DASH0_OTEL_COLLECTOR_BASE_URL"] = otlp_endpoint
+
+    _log_debug("checking for double instrumentation")
+
+    # Temporarily remove this site to be able to check for problematic dependencies in all other available sites.
+    # Without the current site it is easier to differentiate between "our" dependencies and dependencies brought in by
+    # the application under monitoring.
+    # Maintenance note: After checking for double instrumentation scenarios, we add back the current site, via
+    # path.append(current_site). The remove here together with the append also deliberately reorders sys.path to put
+    # this site last, before evaluating conflicting dependency versions. See below for more details on that.
+    path.remove(current_site)
+
+    if _check_for_double_instrumentation(current_site):
+        return
+
+    _log_debug("no double instrumentation detected")
+    _log_debug("checking for dependency conflicts")
+
+    # This "path.append(current_site)" together with "path.remove(current_site)" executed a couple of lines above
+    # effectively reorders sys.path to put this site last. This is necessary to evaluate potential conflicting
+    # dependency versions.
+    #
+    # We will leave this reordering in effect when importing and initializing opentelemetry.instrumentation. Since we
+    # have already ruled out dependency conflicts, the order should not matter, but with this re-ordering we make sure
+    # the application's package versions will win over the package versions we bring (in case there are overlapping
+    # dependencies).
+    path.append(current_site)
+
+    version_conflicts = {}
+    requirements_to_check = _read_all_dependencies()
+    if requirements_to_check is None:
+        _self_deactivate(current_site)
+        _print_cannot_auto_instrument_message("cannot read all-dependencies.txt for dependency conflict checking")
+        return
+
+    for req_string in requirements_to_check:
+        _check_dependency_version_conflict(req_string, version_conflicts)
+        if version_conflicts:
+            break
+
+    if not version_conflicts:
+        try:
+            _log_debug("importing and initializing the Python auto-instrumentation now")
+            from opentelemetry.instrumentation import auto_instrumentation
+            auto_instrumentation.initialize()
+        except Exception as e:
+            _self_deactivate(current_site)
+            _print_cannot_auto_instrument_message(
+                "error when importing/initializing the Python OpenTelemetry auto-instrumentation: {}: {}".format(
+                    type(e).__name__, e))
+    else:
+        # Remove this site for good, we do not want to trigger dependency conflict issues.
+        _self_deactivate(current_site)
+        _print_cannot_auto_instrument_message("dependency conflicts: {}".format(version_conflicts))
+
+
+import_distro()

dash0/opentelemetry/resource.py

@@ -0,0 +1,239 @@
+"""Resource detection for the Dash0 distribution.
+
+Ports the two custom detectors the Node.js distribution ships (a Kubernetes pod
+UID detector and a service-name fallback) plus the ``telemetry.distro.*``
+attributes, and injects them into the standard OpenTelemetry environment
+variables *before* the SDK builds its Resource.
+
+Injecting via ``OTEL_RESOURCE_ATTRIBUTES``/``OTEL_SERVICE_NAME`` (rather than
+registering SDK resource detectors) keeps this working across OTel SDK versions:
+the distro's ``_configure`` runs before the configurator, and the SDK's own
+``Resource.create`` reads these variables.
+
+Declarative configuration (``OTEL_CONFIG_FILE``) deliberately ignores those
+environment variables, so the same attributes are also exposed as standard SDK
+resource detectors, registered under the ``opentelemetry_resource_detector``
+entry-point group (see ``pyproject.toml``):
+:class:`Dash0DistributionResourceDetector`,
+:class:`Dash0KubernetesResourceDetector` and
+:class:`Dash0ServiceNameResourceDetector`.
+"""
+
+import re
+import sys
+from os import environ, path
+
+from opentelemetry.sdk.resources import (
+    Resource,
+    ResourceDetector,
+    ServiceInstanceIdResourceDetector,
+)
+
+from ._environment_variables import (
+    DASH0_AUTOMATIC_SERVICE_NAME,
+    OTEL_RESOURCE_ATTRIBUTES,
+    OTEL_SERVICE_NAME,
+)
+from .settings import is_false
+from .version import __version__
+
+_SERVICE_NAME = "service.name"
+_SERVICE_VERSION = "service.version"
+_K8S_POD_UID = "k8s.pod.uid"
+_DISTRO_NAME = "telemetry.distro.name"
+_DISTRO_VERSION = "telemetry.distro.version"
+
+_ETC_HOSTS = "/etc/hosts"
+_K8S_HOSTS_MARKER = "# Kubernetes-managed hosts file"
+_CGROUP_V1_MOUNTINFO = "/proc/self/mountinfo"
+_CGROUP_V2_CGROUP = "/proc/self/cgroup"
+_POD_MOUNT_MARKER = "/pods/"
+_POD_UID_LEN = 36
+_CONTAINER_ID_LEN = 64
+_POD_LABEL = "pod"
+# matches cgroup v2 slices like kubepods-pode462ffed_94ce_4806_a52e_d2726f448f15.slice
+_POD_UID_IN_CGROUP = re.compile(
+    r"^[a-z_-]*pod(?P<uid>[0-9a-f]{8}[-_][0-9a-f]{4}[-_][0-9a-f]{4}"
+    r"[-_][0-9a-f]{4}[-_][0-9a-f]{12})\.slice$"
+)
+
+
+def distribution_resource_attributes(version):
+    attributes = {_DISTRO_NAME: "dash0-python"}
+    if version:
+        attributes[_DISTRO_VERSION] = version
+    return attributes
+
+
+def _read_candidate_lines(filename, minimum_length):
+    try:
+        with open(filename, encoding="utf8") as file:
+            content = file.read()
+    except OSError:
+        return []
+    return [
+        line.strip()
+        for line in content.splitlines()
+        if len(line.strip()) > minimum_length
+    ]
+
+
+def running_in_kubernetes():
+    try:
+        with open(_ETC_HOSTS, encoding="utf8") as file:
+            first_line = file.readline()
+    except OSError:
+        return False
+    return first_line.startswith(_K8S_HOSTS_MARKER)
+
+
+def pod_uid_from_cgroup_v1():
+    for line in _read_candidate_lines(_CGROUP_V1_MOUNTINFO, _POD_UID_LEN):
+        marker_index = line.find(_POD_MOUNT_MARKER)
+        if marker_index > 0:
+            after_marker = line[marker_index + len(_POD_MOUNT_MARKER) :]
+            if len(after_marker) >= _POD_UID_LEN:
+                return after_marker[:_POD_UID_LEN]
+    return None
+
+
+def pod_uid_from_cgroup_v2():
+    for line in _read_candidate_lines(_CGROUP_V2_CGROUP, _CONTAINER_ID_LEN):
+        segments = line.split("/")
+        if len(segments) <= 2:
+            continue
+        penultimate = segments[-2]
+        expected_length = _POD_UID_LEN + len(_POD_LABEL)
+        if penultimate.startswith(_POD_LABEL) and len(penultimate) == expected_length:
+            return penultimate[len(_POD_LABEL) :]
+        match = _POD_UID_IN_CGROUP.match(penultimate)
+        if match:
+            return match.group("uid").replace("_", "-")
+    return None
+
+
+def detect_kubernetes_pod_uid():
+    if not running_in_kubernetes():
+        return None
+    return pod_uid_from_cgroup_v1() or pod_uid_from_cgroup_v2()
+
+
+def _service_name_already_configured():
+    if environ.get(OTEL_SERVICE_NAME, "").strip():
+        return True
+    for pair in environ.get(OTEL_RESOURCE_ATTRIBUTES, "").split(","):
+        key, _, value = pair.partition("=")
+        if key.strip() == _SERVICE_NAME and value.strip().strip('"'):
+            return True
+    return False
+
+
+def detect_fallback_service_name():
+    """Best-effort service name from the running program.
+
+    The Node.js distribution reads ``package.json``; Python has no universal
+    equivalent, so this derives a name from the entrypoint script.
+    """
+    argv0 = sys.argv[0] if sys.argv else ""
+    if not argv0:
+        return None
+    name = path.basename(argv0)
+    if name.endswith(".py"):
+        name = name[: -len(".py")]
+    return name or None
+
+
+def _merge_into_resource_attributes(attributes):
+    existing = environ.get(OTEL_RESOURCE_ATTRIBUTES, "")
+    present_keys = {
+        pair.partition("=")[0].strip() for pair in existing.split(",") if pair.strip()
+    }
+    additions = [
+        f"{key}={value}" for key, value in attributes.items() if key not in present_keys
+    ]
+    if not additions:
+        return
+    parts = [existing] if existing.strip() else []
+    parts.extend(additions)
+    environ[OTEL_RESOURCE_ATTRIBUTES] = ",".join(parts)
+
+
+def apply_detected_resource_attributes(version):
+    if not is_false(environ.get(DASH0_AUTOMATIC_SERVICE_NAME)) and (
+        not _service_name_already_configured()
+    ):
+        fallback = detect_fallback_service_name()
+        if fallback:
+            environ[OTEL_SERVICE_NAME] = fallback
+
+    attributes = distribution_resource_attributes(version)
+    pod_uid = detect_kubernetes_pod_uid()
+    if pod_uid:
+        attributes[_K8S_POD_UID] = pod_uid
+    _merge_into_resource_attributes(attributes)
+
+
+def _detected_service_name():
+    """The ``service.name`` the environment-variable path would produce.
+
+    ``OTEL_SERVICE_NAME`` wins (mirroring the declarative ``service`` detector,
+    which also reads it); the entrypoint-derived fallback applies only when no
+    service name is configured anywhere in the environment and
+    ``DASH0_AUTOMATIC_SERVICE_NAME`` is not ``false``. A ``service.name``
+    embedded in ``OTEL_RESOURCE_ATTRIBUTES`` suppresses the fallback but is not
+    resurrected here — declarative configuration ignores that variable by
+    design.
+    """
+    explicit = environ.get(OTEL_SERVICE_NAME, "").strip()
+    if explicit:
+        return explicit
+    if is_false(environ.get(DASH0_AUTOMATIC_SERVICE_NAME)):
+        return None
+    if _service_name_already_configured():
+        return None
+    return detect_fallback_service_name()
+
+
+class Dash0DistributionResourceDetector(ResourceDetector):
+    """Reports ``telemetry.distro.name`` and ``telemetry.distro.version``.
+
+    The environment-variable injection above does not survive declarative
+    configuration: when ``OTEL_CONFIG_FILE`` is set, the declarative resource
+    builder ignores ``OTEL_RESOURCE_ATTRIBUTES``/``OTEL_SERVICE_NAME`` and only
+    runs detectors named in the config file, resolved via the
+    ``opentelemetry_resource_detector`` entry-point group. This detector and
+    its two siblings below are registered there (``dash0_distribution``,
+    ``dash0_kubernetes``, ``dash0_service_name``) and work with
+    ``OTEL_EXPERIMENTAL_RESOURCE_DETECTORS`` as well.
+    """
+
+    def detect(self):
+        return Resource(distribution_resource_attributes(__version__))
+
+
+class Dash0KubernetesResourceDetector(ResourceDetector):
+    """Reports ``k8s.pod.uid``, detected from ``/etc/hosts`` and the cgroups."""
+
+    def detect(self):
+        pod_uid = detect_kubernetes_pod_uid()
+        if pod_uid:
+            return Resource({_K8S_POD_UID: pod_uid})
+        return Resource.get_empty()
+
+
+class Dash0ServiceNameResourceDetector(ResourceDetector):
+    """Service detection: the upstream behavior plus the Dash0 fallback.
+
+    Wraps what upstream service detection provides — a stable
+    ``service.instance.id`` (via the SDK's ``ServiceInstanceIdResourceDetector``)
+    and ``service.name`` from ``OTEL_SERVICE_NAME`` — and adds the distro's
+    entrypoint-derived ``service.name`` fallback when no service name is
+    configured (see :func:`_detected_service_name`).
+    """
+
+    def detect(self):
+        attributes = dict(ServiceInstanceIdResourceDetector().detect().attributes)
+        service_name = _detected_service_name()
+        if service_name:
+            attributes[_SERVICE_NAME] = service_name
+        return Resource(attributes)

dash0/opentelemetry/settings.py

@@ -0,0 +1,33 @@
+"""Enablement gate for the Dash0 distribution.
+
+Mirrors the two hard gates the Node.js distribution checks before doing
+anything: an explicit kill switch, and a required collector endpoint (there is
+no point instrumenting if there is nowhere to send the telemetry).
+"""
+
+from os import environ
+
+from ._environment_variables import (
+    DASH0_DISABLE,
+    DASH0_OTEL_COLLECTOR_BASE_URL,
+)
+
+
+def is_true(value):
+    return value is not None and value.strip().lower() == "true"
+
+
+def is_false(value):
+    return value is not None and value.strip().lower() == "false"
+
+
+def evaluate_gate():
+    """Return ``(enabled, reason)``.
+
+    ``reason`` is a human-readable explanation when disabled, else ``None``.
+    """
+    if is_true(environ.get(DASH0_DISABLE)):
+        return False, f"{DASH0_DISABLE} is set to true"
+    if not environ.get(DASH0_OTEL_COLLECTOR_BASE_URL):
+        return False, f"{DASH0_OTEL_COLLECTOR_BASE_URL} is not set"
+    return True, None

dash0/opentelemetry/version.py

@@ -0,0 +1 @@
+__version__ = "0.3.1"

dash0_opentelemetry-0.3.1.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: dash0-opentelemetry
+Version: 0.3.1
+Summary: Dash0 OpenTelemetry distribution for Python
+Author: Dash0
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: asgiref==3.12.1
+Requires-Dist: dash0-opentelemetry-exporter-otlp-pyproto-grpc==1.44.0.post1
+Requires-Dist: dash0-opentelemetry-exporter-otlp-pyproto-http==1.44.0.post1
+Requires-Dist: opentelemetry-api==1.44.0
+Requires-Dist: opentelemetry-instrumentation-aio-pika==0.65b0
+Requires-Dist: opentelemetry-instrumentation-aiohttp-client==0.65b0
+Requires-Dist: opentelemetry-instrumentation-aiohttp-server==0.65b0
+Requires-Dist: opentelemetry-instrumentation-aiokafka==0.65b0
+Requires-Dist: opentelemetry-instrumentation-aiopg==0.65b0
+Requires-Dist: opentelemetry-instrumentation-asgi==0.65b0
+Requires-Dist: opentelemetry-instrumentation-asyncclick==0.65b0
+Requires-Dist: opentelemetry-instrumentation-asyncio==0.65b0
+Requires-Dist: opentelemetry-instrumentation-asyncpg==0.65b0
+Requires-Dist: opentelemetry-instrumentation-boto3sqs==0.65b0
+Requires-Dist: opentelemetry-instrumentation-botocore==0.65b0
+Requires-Dist: opentelemetry-instrumentation-cassandra==0.65b0
+Requires-Dist: opentelemetry-instrumentation-celery==0.65b0
+Requires-Dist: opentelemetry-instrumentation-click==0.65b0
+Requires-Dist: opentelemetry-instrumentation-confluent-kafka==0.65b0
+Requires-Dist: opentelemetry-instrumentation-dbapi==0.65b0
+Requires-Dist: opentelemetry-instrumentation-django==0.65b0
+Requires-Dist: opentelemetry-instrumentation-exceptions==0.65b0
+Requires-Dist: opentelemetry-instrumentation-falcon==0.65b0
+Requires-Dist: opentelemetry-instrumentation-fastapi==0.65b0
+Requires-Dist: opentelemetry-instrumentation-flask==0.65b0
+Requires-Dist: opentelemetry-instrumentation-grpc==0.65b0
+Requires-Dist: opentelemetry-instrumentation-httpx==0.65b0
+Requires-Dist: opentelemetry-instrumentation-jinja2==0.65b0
+Requires-Dist: opentelemetry-instrumentation-kafka-python==0.65b0
+Requires-Dist: opentelemetry-instrumentation-logging==0.65b0
+Requires-Dist: opentelemetry-instrumentation-mysql==0.65b0
+Requires-Dist: opentelemetry-instrumentation-mysqlclient==0.65b0
+Requires-Dist: opentelemetry-instrumentation-openai-v2==2.3b0
+Requires-Dist: opentelemetry-instrumentation-pika==0.65b0
+Requires-Dist: opentelemetry-instrumentation-psycopg2==0.65b0
+Requires-Dist: opentelemetry-instrumentation-psycopg==0.65b0
+Requires-Dist: opentelemetry-instrumentation-pymemcache==0.65b0
+Requires-Dist: opentelemetry-instrumentation-pymongo==0.65b0
+Requires-Dist: opentelemetry-instrumentation-pymssql==0.65b0
+Requires-Dist: opentelemetry-instrumentation-pymysql==0.65b0
+Requires-Dist: opentelemetry-instrumentation-pyramid==0.65b0
+Requires-Dist: opentelemetry-instrumentation-redis==0.65b0
+Requires-Dist: opentelemetry-instrumentation-remoulade==0.65b0
+Requires-Dist: opentelemetry-instrumentation-requests==0.65b0
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy==0.65b0
+Requires-Dist: opentelemetry-instrumentation-sqlite3==0.65b0
+Requires-Dist: opentelemetry-instrumentation-starlette==0.65b0
+Requires-Dist: opentelemetry-instrumentation-structlog==0.65b0
+Requires-Dist: opentelemetry-instrumentation-system-metrics==0.65b0
+Requires-Dist: opentelemetry-instrumentation-threading==0.65b0
+Requires-Dist: opentelemetry-instrumentation-tornado==0.65b0
+Requires-Dist: opentelemetry-instrumentation-tortoiseorm==0.65b0
+Requires-Dist: opentelemetry-instrumentation-urllib3==0.65b0
+Requires-Dist: opentelemetry-instrumentation-urllib==0.65b0
+Requires-Dist: opentelemetry-instrumentation-vertexai==2.2b0
+Requires-Dist: opentelemetry-instrumentation-wsgi==0.65b0
+Requires-Dist: opentelemetry-instrumentation==0.65b0
+Requires-Dist: opentelemetry-propagator-aws-xray==1.0.2
+Requires-Dist: opentelemetry-sdk==1.44.0
+Requires-Dist: opentelemetry-semantic-conventions==0.65b0
+Requires-Dist: opentelemetry-util-genai==0.2b0
+Requires-Dist: opentelemetry-util-http==0.65b0
+Requires-Dist: packaging==26.2
+Requires-Dist: psutil==7.2.2
+Requires-Dist: typing-extensions==4.16.0
+Requires-Dist: wrapt==1.17.3
+Description-Content-Type: text/x-rst
+
+===================
+dash0-opentelemetry
+===================
+
+The Dash0 OpenTelemetry distribution for Python. It is the Python counterpart of
+the Dash0 Node.js distribution (``@dash0/opentelemetry``), adapted to Python's
+distro/configurator machinery, and is meant to be injected into a process (for
+example by the OpenTelemetry injector) with no code changes.
+
+Entry points
+============
+
+``Dash0Distro`` (``opentelemetry_distro``)
+    Runs first, before the configurator. It:
+
+    * **Gates** the distribution: does nothing if ``DASH0_DISABLE=true`` or if
+      ``DASH0_OTEL_COLLECTOR_BASE_URL`` is unset (nowhere to send telemetry). In
+      either case it sets ``OTEL_SDK_DISABLED=true`` and skips instrumentation.
+    * Defaults all three signals to the pure-Python OTLP/HTTP exporter
+      (``otlp_proto_http``, ``http/protobuf``) and points
+      ``OTEL_EXPORTER_OTLP_ENDPOINT`` at ``DASH0_OTEL_COLLECTOR_BASE_URL``. The
+      pure-Python exporter has no native dependencies, which is what makes the
+      distribution safe to inject onto an arbitrary process' ``PYTHONPATH``.
+      When a signal's OTLP protocol does not match the transport the shared
+      endpoint targets — its port is the *other* protocol's conventional
+      default (``4317`` gRPC / ``4318`` HTTP) — a per-signal
+      ``OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT`` is derived by rewriting the
+      port (appending the ``v1/<signal>`` path for HTTP), so mixed-protocol
+      setups and a base URL on the "wrong" default port still export
+      correctly. Custom ports and explicit per-signal endpoints are always
+      left untouched.
+    * Injects detected **resource attributes** into ``OTEL_RESOURCE_ATTRIBUTES``/
+      ``OTEL_SERVICE_NAME`` (see below) so the SDK's Resource picks them up.
+    * Overrides ``load_instrumentor`` to activate each instrumentor
+      **defensively** — a disabled or failing instrumentor is skipped and logged
+      rather than aborting auto-instrumentation of the host process.
+
+``Dash0Configurator`` (``opentelemetry_configurator``)
+    Runs after the distro. Delegates to the standard OpenTelemetry SDK
+    configurator to build the providers/exporters/Resource from the environment,
+    then adds two behaviors from the Node.js distribution:
+
+    * an optional **bootstrap span** emitted once at startup
+      (``DASH0_BOOTSTRAP_SPAN=<name>``);
+    * optional **graceful flush** on ``SIGTERM``/``SIGINT``
+      (``DASH0_FLUSH_ON_SIGTERM_SIGINT=true``) — normal-exit flushing is already
+      handled by the SDK's ``atexit`` provider shutdown.
+
+Resource detectors (``opentelemetry_resource_detector``)
+    The detected resource attributes (see below) as standard SDK resource
+    detectors, one per concern so each can be used (or omitted) independently:
+
+    * ``dash0_distribution`` — ``telemetry.distro.name``/``telemetry.distro.version``;
+    * ``dash0_kubernetes`` — ``k8s.pod.uid``;
+    * ``dash0_service_name`` — wraps the upstream service detection (a
+      process-stable ``service.instance.id`` and ``service.name`` from
+      ``OTEL_SERVICE_NAME``) and adds the distro's entrypoint-derived
+      ``service.name`` fallback, so there is no need to also list the built-in
+      ``service`` detector.
+
+    They can be referenced via ``OTEL_EXPERIMENTAL_RESOURCE_DETECTORS``, or
+    explicitly in a declarative config file under
+    ``resource.detection/development.detectors``.
+
+Instrumentations
+================
+
+The distribution depends on the full upstream auto-instrumentation set — every
+package enumerated by the ``bootstrap_gen`` module of
+``opentelemetry-instrumentation`` (the list behind ``opentelemetry-bootstrap``)
+— pinned to a single contrib version, so injected processes need no bootstrap
+step. Instrumentations only activate when their target library is present,
+which makes carrying all of them safe.
+
+Deviations from the upstream list:
+
+* ``opentelemetry-propagator-aws-xray`` is shipped although upstream's
+  bootstrap list only covers instrumentations (the Dash0 operator's
+  instrumentation image always carried it).
+* ``opentelemetry-exporter-prometheus``,
+  ``opentelemetry-propagator-ot-trace``, and
+  ``opentelemetry-instrumentation-aws-lambda`` are deliberately not shipped.
+
+``tests/test_instrumentations.py`` cross-checks the dependency block against
+the installed upstream list, so a contrib version bump that adds or removes
+instrumentations fails CI until the block is re-synced. Dependabot keeps the
+pins themselves moving (all ``opentelemetry-*`` packages are grouped into one
+update, since the contrib instrumentations only resolve when they share one
+contrib version).
+
+Resource detection
+==================
+
+Ported from the Node.js distribution's custom detectors:
+
+* **Kubernetes pod UID** (``k8s.pod.uid``): confirms it is running in Kubernetes
+  (via ``/etc/hosts``), then extracts the pod UID from cgroup v1
+  (``/proc/self/mountinfo``) or cgroup v2 (``/proc/self/cgroup``).
+* **Service-name fallback**: if ``OTEL_SERVICE_NAME`` / ``service.name`` are not
+  set (and ``DASH0_AUTOMATIC_SERVICE_NAME`` is not ``false``), derives a name
+  from the entrypoint script. (Node.js reads ``package.json``; Python has no
+  universal equivalent, so this is a best-effort analog.)
+* **Distribution attributes**: ``telemetry.distro.name=dash0-python`` and
+  ``telemetry.distro.version``.
+
+Existing attributes are never overridden.
+
+Dependency policy
+=================
+
+The distribution ships a curated set of upstream OpenTelemetry packages, pinned
+exactly in its ``pyproject.toml``: each release is validated against precisely
+those versions, and the code assumes them. Version bumps are deliberate,
+standalone changes. The pins cover the *entire* installed tree: every package
+the distribution pulls in transitively is also declared directly with an exact
+pin, so no version is left to transitive resolution. CI enforces both rules via
+``scripts/check_pinned_dependencies.py`` (in-repo workspace members are exempt,
+as their version is fixed by the checkout).
+
+Injector bootstrap (``sitecustomize.py``)
+=========================================
+
+The wheel ships the bootstrap script used for ``PYTHONPATH``-based injection at
+``dash0/opentelemetry/injector/sitecustomize.py``. It is not meant to be
+imported from that location (importing it executes it); instead, a consumer
+building an injectable tree — such as the dash0-operator's instrumentation
+image —
+
+1. installs the distribution into a self-contained directory:
+   ``pip install --target <dir> dash0-opentelemetry``;
+2. copies the script to ``<dir>/sitecustomize.py``;
+3. generates ``<dir>/all-dependencies.txt``, a flattened list of every
+   requirement of the installed tree (one PEP 508 requirement per line).
+
+The `OpenTelemetry injector
+<https://github.com/open-telemetry/opentelemetry-injector>`_ then prepends
+``<dir>`` to the ``PYTHONPATH`` of the processes to instrument, so Python's
+``site`` machinery runs the script on interpreter startup. The script
+initializes the auto-instrumentation only after a set of safety checks —
+supported interpreter version, no OpenTelemetry packages already shipped with
+the application (double instrumentation), no version conflicts between the
+application's dependencies and ``all-dependencies.txt`` — and otherwise
+deactivates the injection gracefully, for the current process and its children.
+It also bridges ``OTEL_EXPORTER_OTLP_ENDPOINT`` to
+``DASH0_OTEL_COLLECTOR_BASE_URL`` when only the former is set. The script stays
+valid Python 2.7+ so it can self-deactivate instead of crashing on interpreters
+the distribution does not support.
+
+Environment variables
+=====================
+
+============================================  ====================================================
+Variable                                      Effect
+============================================  ====================================================
+``DASH0_OTEL_COLLECTOR_BASE_URL`` (required)  Collector base URL; also sets the OTLP endpoint.
+``DASH0_DISABLE``                             ``true`` disables the distribution entirely.
+``DASH0_AUTOMATIC_SERVICE_NAME``              ``false`` opts out of the service-name fallback.
+``DASH0_BOOTSTRAP_SPAN``                      Emit one span with this name at startup.
+``DASH0_FLUSH_ON_SIGTERM_SIGINT``             ``true`` flushes telemetry on SIGTERM/SIGINT.
+============================================  ====================================================
+
+Status
+======
+
+Prototype. The ``otlp_proto_http`` exporter is resolved from the in-repo pyproto
+workspace member, published as ``dash0-opentelemetry-exporter-otlp-pyproto-http``
+on the Dash0 package index and on public PyPI. Not yet done: the injector's
+per-``libc`` packaging and the integration/injection test matrix. Unit tests do
+not require a running collector.

dash0_opentelemetry-0.3.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+dash0/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dash0/opentelemetry/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dash0/opentelemetry/_environment_variables.py,sha256=o4MMVOrtvLifcznY-4MOMuRdcZfW1JHVuPfZ-JkuXsQ,1861
+dash0/opentelemetry/configurator.py,sha256=nCw8_EadlYWKoMRp3SFZ62qYJDKcQPtzbXW859VVc_8,3025
+dash0/opentelemetry/distro.py,sha256=wwTy3bMabxgGkHe0hgxIBy77Gd7FjwuGrk4ewSO9CZU,8901
+dash0/opentelemetry/resource.py,sha256=9SrSjhwIdUC1dUiFkVisI5KF2guI7gekDdiK2h76BAQ,8429
+dash0/opentelemetry/settings.py,sha256=Yxt55kicpAI5j24ENpBXh5p4Am6ePagRlHwlDSuN9gs,956
+dash0/opentelemetry/version.py,sha256=r4xAFihOf72W9TD-lpMi6ntWSTKTP2SlzKP1ytkjRbI,22
+dash0/opentelemetry/injector/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dash0/opentelemetry/injector/sitecustomize.py,sha256=bUM4ODkUpXmPnpLpMsuQD2z8DQW24UTg3KAecLshpsc,14681
+dash0_opentelemetry-0.3.1.dist-info/METADATA,sha256=puaYAfLg5AfhASuRq9W0rdju8TkUeXXHzK3cfdu0qHw,13388
+dash0_opentelemetry-0.3.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+dash0_opentelemetry-0.3.1.dist-info/entry_points.txt,sha256=LXwsgDWxHJdaSa3V5OMibCQPpiNVMmSwiS97DwEFNhA,441
+dash0_opentelemetry-0.3.1.dist-info/RECORD,,

dash0_opentelemetry-0.3.1.dist-info/WHEEL

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

dash0_opentelemetry-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,10 @@
+[opentelemetry_configurator]
+dash0 = dash0.opentelemetry.configurator:Dash0Configurator
+
+[opentelemetry_distro]
+dash0 = dash0.opentelemetry.distro:Dash0Distro
+
+[opentelemetry_resource_detector]
+dash0_distribution = dash0.opentelemetry.resource:Dash0DistributionResourceDetector
+dash0_kubernetes = dash0.opentelemetry.resource:Dash0KubernetesResourceDetector
+dash0_service_name = dash0.opentelemetry.resource:Dash0ServiceNameResourceDetector