OpenTelemetry Container Distro for Python

Warnings

• gotcha 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.
  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`).
• gotcha 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.
  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).
• gotcha 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.
  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.
• gotcha 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`).
  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.

Install

• pip install opentelemetry-container-distro Install latest version

Imports

• get_resource

  from opentelemetry.sdk.resources import get_resource

  To retrieve the automatically populated resource attributes, including container-specific ones.
• trace

  from opentelemetry import trace

  Standard OpenTelemetry API for interacting with the tracing system, which is configured by the distro.

Quickstart

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.

import os
from opentelemetry import trace
from opentelemetry.sdk.resources import get_resource

# Ensure an OTLP collector is available if you want to export traces.
# For example, by running 'docker run -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector:latest'
# or configure your OTLP endpoint via environment variables like OTEL_EXPORTER_OTLP_ENDPOINT.

# The distro is installed and auto-configures the tracer provider and resource detectors.
# We can directly get the tracer and retrieve the resource.

tracer = trace.get_tracer("my-container-app")

with tracer.start_as_current_span("my-container-operation"):
    print("Performing an operation within a container context...")

# Retrieve the resource and print its attributes to show container detection
resource = get_resource()
print("\nDetected Resource Attributes (should include container.* if running in a container):")
for key, value in resource.attributes.items():
    print(f"  {key}: {value}")

print("\nTrace generated. Check your OTLP collector for exported data.")