{"id":4668,"library":"opentelemetry-container-distro","title":"OpenTelemetry Container Distro for Python","description":"An OpenTelemetry distro which automatically discovers container attributes from the environment. This distribution extends the standard `opentelemetry-distro` to automatically include additional resource detectors tailored for container environments, such as Docker or Kubernetes. It aims to simplify OpenTelemetry setup by providing automatic configuration, while largely preserving the behavior of `opentelemetry-distro`. The current version is 0.2.0, released on September 18, 2022, indicating a slower release cadence compared to core OpenTelemetry components.","status":"active","version":"0.2.0","language":"en","source_language":"en","source_url":"https://github.com/chrisguidry/opentelemetry-container-distro","tags":["opentelemetry","observability","tracing","metrics","containers","docker","kubernetes","distro","python"],"install":[{"cmd":"pip install opentelemetry-container-distro","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This package builds upon and extends the core OpenTelemetry Python distribution, inheriting its setup and default configurations.","package":"opentelemetry-distro"},{"reason":"Fundamental OpenTelemetry SDK components for tracing and metrics, including resource detection.","package":"opentelemetry-sdk"}],"imports":[{"note":"To retrieve the automatically populated resource attributes, including container-specific ones.","symbol":"get_resource","correct":"from opentelemetry.sdk.resources import get_resource"},{"note":"Standard OpenTelemetry API for interacting with the tracing system, which is configured by the distro.","symbol":"trace","correct":"from opentelemetry import trace"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import get_resource\n\n# Ensure an OTLP collector is available if you want to export traces.\n# For example, by running 'docker run -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector:latest'\n# or configure your OTLP endpoint via environment variables like OTEL_EXPORTER_OTLP_ENDPOINT.\n\n# The distro is installed and auto-configures the tracer provider and resource detectors.\n# We can directly get the tracer and retrieve the resource.\n\ntracer = trace.get_tracer(\"my-container-app\")\n\nwith tracer.start_as_current_span(\"my-container-operation\"):\n    print(\"Performing an operation within a container context...\")\n\n# Retrieve the resource and print its attributes to show container detection\nresource = get_resource()\nprint(\"\\nDetected Resource Attributes (should include container.* if running in a container):\")\nfor key, value in resource.attributes.items():\n    print(f\"  {key}: {value}\")\n\nprint(\"\\nTrace generated. Check your OTLP collector for exported data.\")","lang":"python","description":"This quickstart demonstrates how to use the `opentelemetry-container-distro` by simply installing it and then interacting with the standard OpenTelemetry Python API. The key takeaway is how to retrieve and inspect the resource attributes, which should automatically include container-specific metadata if the application is running within a recognized container environment (e.g., Docker, Kubernetes). An OpenTelemetry Collector is typically needed to receive and export telemetry data."},"warnings":[{"fix":"Ensure an OpenTelemetry Collector is running and correctly configured to receive OTLP data (gRPC default on port 4317, HTTP on 4318). Regularly check Collector release notes for breaking changes and update image references (e.g., from `otel/opentelemetry-collector-contrib` to `ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib`).","message":"This distro, like `opentelemetry-distro`, primarily configures an OTLP SpanExporter, which typically sends data to a running OpenTelemetry Collector. Users must ensure a Collector is deployed and accessible to actually receive and process the telemetry. The Collector itself has frequent breaking changes and its Docker image registry moved from DockerHub to GitHub Container Registry, requiring updates to deployment configurations.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When running in a container, ensure the Docker socket is mounted (e.g., `-v /var/run/docker.sock:/var/run/docker.sock`) or that the execution environment grants the necessary permissions and access to container metadata APIs (e.g., ECS task metadata endpoint for AWS ECS). ","message":"For automatic container attribute detection to work, the application or the underlying OpenTelemetry SDK components need appropriate access to the container runtime's information, typically via the Docker socket (`/var/run/docker.sock`) or similar mechanisms for other container runtimes. Without this access, container attributes will not be automatically populated.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor the project's GitHub repository for new releases. If using the latest OpenTelemetry SDK features is critical, users might need to manually configure resource detectors or consider a more actively maintained OpenTelemetry distribution, or contribute to updating this distro.","message":"The `opentelemetry-container-distro` has seen infrequent updates (last release 0.2.0 in September 2022). In contrast, the upstream OpenTelemetry Python SDK and `opentelemetry-distro` are under active and rapid development (e.g., `opentelemetry-distro 0.62b0` in April 2026). This disparity means that `opentelemetry-container-distro` might depend on older versions of the SDK, potentially missing out on newer features, performance improvements, or important bug fixes available in more recent OpenTelemetry releases.","severity":"gotcha","affected_versions":"<0.3.0"},{"fix":"Understand that the distro's role is to pre-configure the global OpenTelemetry SDK components. After installation, applications should interact with OpenTelemetry using its standard APIs (e.g., `from opentelemetry import trace`). Refer to the `opentelemetry-distro` documentation for general usage patterns if explicit configuration is needed beyond defaults.","message":"The core concept of an OpenTelemetry 'distro' is to provide auto-configuration, meaning much of the setup happens implicitly upon installation and application startup. New users might expect explicit `init()` or `configure()` calls directly on the distro package, but the primary interaction remains through the standard `opentelemetry` API (e.g., `opentelemetry.trace`).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}