OpenTelemetry Docker Resource Detector

Warnings

• gotcha The `DockerResourceDetector` requires read access to the Docker daemon socket (typically `/var/run/docker.sock` on Linux) to retrieve container metadata. Running applications or the OpenTelemetry Collector inside a container as a non-root user often necessitates explicit volume mounts and permissions (`--group-add <docker-gid>` or `runAsGroup` in Kubernetes) for the socket.
  Fix: Ensure the user running the application has read permissions for the Docker socket. Mount the Docker socket into the container (e.g., `-v /var/run/docker.sock:/var/run/docker.sock`) and configure appropriate user/group permissions.
• gotcha The Docker detector may not function as expected on macOS due to the virtualization layer of Docker Desktop, which can abstract the Docker socket access. The OpenTelemetry Collector's `resourcedetection` processor explicitly states that its Docker detector does not work on macOS.
  Fix: Consider alternatives like manually setting `OTEL_RESOURCE_ATTRIBUTES` or using other detectors that might be available for macOS container environments if Docker-specific attributes are crucial.
• gotcha If the application cannot access the Docker daemon (e.g., due to the daemon not running, an incorrect socket path, or blocked network access), the `DockerResourceDetector` will fail to populate Docker-related resource attributes. This can lead to missing contextual information in your telemetry.
  Fix: Verify that the Docker daemon is running and accessible from the application's environment. Check logs for connection errors (e.g., 'connect ETIMEDOUT') and ensure proper socket configuration.
• gotcha When combining `DockerResourceDetector` with other resource detectors using `get_aggregated_resources`, if multiple detectors try to set the same resource attribute key, the value from the detector listed later in the `get_aggregated_resources` array will typically override values from earlier detectors.
  Fix: Be mindful of the order of detectors when aggregating resources. If conflicts are observed, adjust the order or explicitly set desired attributes through other means (e.g., `OTEL_RESOURCE_ATTRIBUTES` environment variable, which takes precedence over code-based attributes).

Install

• pip install opentelemetry-resourcedetector-docker Install package

Imports

• DockerResourceDetector

  from opentelemetry_resourcedetector_docker import DockerResourceDetector

  Main class for Docker resource detection.
• get_aggregated_resources

  from opentelemetry.sdk.resources import get_aggregated_resources

  Required to combine multiple resource detectors.

Quickstart

This quickstart demonstrates how to initialize the OpenTelemetry SDK with the `DockerResourceDetector` to automatically gather Docker-related resource attributes. The collected attributes are then used by a `TracerProvider` and printed to the console via a `ConsoleSpanExporter`. Ensure Docker is running and the application has permissions to access the Docker socket for successful detection.

import os
from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry_resourcedetector_docker import DockerResourceDetector
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

# Configure the resource detector. DockerResourceDetector requires access to the Docker socket.
# Ensure your application has read access to /var/run/docker.sock (Linux) or similar.
# For demonstration, we'll try to detect, but actual attributes depend on Docker environment.
resource = get_aggregated_resources([
    DockerResourceDetector()
])

# Optional: Add a service name if not detected by environment variables or other detectors
if not resource.attributes.get('service.name'):
    resource = resource.merge(Resource({'service.name': 'my-docker-app'}))

# Set up a TracerProvider with the detected resource
provider = TracerProvider(resource=resource)

# Configure a simple console exporter for demonstration
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(span_processor)

# Set the global tracer provider
from opentelemetry import trace
trace.set_tracer_provider(provider)

# Get a tracer and create a span
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("my-docker-operation") as span:
    span.set_attribute("environment", os.environ.get('APP_ENV', 'development'))
    print(f"Span created with resource attributes: {resource.attributes}")
    print("Look for 'container.id' or other Docker-related attributes in the output.")