Registry / observability / opentelemetry-resourcedetector-docker

opentelemetry-resourcedetector-docker

JSON →
library0.4.0pypypi✓ verified 23d ago

opentelemetry-resourcedetector-docker is a Python package for OpenTelemetry that automatically enriches telemetry data with resource attributes derived from the Docker container environment where the application is running. Currently at version 0.4.0, it is actively maintained with releases as needed to align with OpenTelemetry Python SDK and address Docker-related detection specifics.

pip install opentelemetry-resourcedetector-docker
INSTALL
IMPORT
SIG · OPENTELEMETRY-RESO
O
opentelemetry-resourcedetector-docker
observabilitypythonv0.4.0
Install
2.0s avg
Import
186ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.188s · 21.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.0s · import 0.184s · 22MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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.")
Debug
Known issues
gotchaThe `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.
affects: All
gotchaThe 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.
affects: All
gotchaIf 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.
affects: All
gotchaWhen 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).
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'opentelemetry_resourcedetector_docker'
The `opentelemetry-resourcedetector-docker` package is not installed or is not accessible in the current Python environment.
fix
Ensure the package is installed using pip: `pip install opentelemetry-resourcedetector-docker`. If running in a Docker container or virtual environment, verify that pip installs into the correct environment, potentially by using `python -m pip install opentelemetry-resourcedetector-docker`.
from opentelemetry_resourcedetector_docker import DockerResourceDetector
While this import is generally correct, users might search for it if they are unsure of the exact module path or if it fails due to the package not being installed or other environmental issues. This can also be searched if they are trying to find where `DockerResourceDetector` lives after a `ModuleNotFoundError` for a different (incorrect) import path.
fix
Ensure the `opentelemetry-resourcedetector-docker` package is installed (`pip install opentelemetry-resourcedetector-docker`) and that `DockerResourceDetector` is correctly passed to `get_aggregated_resources` or `TracerProvider` initialization.
Container ID Detection Failed
The `opentelemetry-resourcedetector-docker` cannot correctly identify the Docker container ID. This often happens due to insufficient permissions to access the Docker socket (`/var/run/docker.sock`), the `/proc` filesystem not being mounted, or running in a restricted container environment that prevents access to cgroup information.
fix
Ensure the OpenTelemetry Collector or the application running the detector has read permissions to the Docker socket by mounting it as read-only: `-v /var/run/docker.sock:/var/run/docker.sock:ro`. Also, ensure the `/proc` filesystem is mounted if in a restricted container: `-v /proc:/host/proc:ro`.
Error response from daemon: No such container
This error can occur in the OpenTelemetry Collector's `resourcedetection/docker` processor when `network_mode: host` is used in Docker Compose, causing the container's hostname to match the host's. The detector then incorrectly tries to look up a container by the host's name instead of the actual container name, leading to a 'No such container' error.
fix
Avoid using `network_mode: host` with resource detection that relies on container names, or ensure the container's hostname is distinct from the host's. For host metrics, consider using the `system` detector instead of `docker` detector if container-specific details are not strictly required, or ensure proper container naming and lookup mechanisms.
Upgrade
Version history
0.4.0latest on PyPI · released Sep 18, 2022
Audit
Dependencies

No dependency data recorded yet.

Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
1
Resources
opentelemetry-resourcedetector-docker — pip install opentelemetry-resourcedetector-docker · libregistry