OpenTelemetry Kubernetes Resource Detector

0.3.0 · active · verified Sat Apr 11

This OpenTelemetry package is designed to automatically populate resource attributes for Kubernetes pods. It enriches telemetry data (traces, metrics, and logs) with essential metadata about the Kubernetes environment, such as pod names, namespaces, and container IDs, providing crucial context for observability. The current version is 0.3.0.

Warnings

gotcha The `KubernetesDownwardAPIEnvironmentResourceDetector` and `KubernetesDownwardAPIVolumeResourceDetector` require explicit configuration in your Kubernetes manifests (e.g., defining environment variables or volume mounts) to populate additional attributes. Without this, they will only provide basic pod UID and container ID information.
Fix: Ensure your Kubernetes pod manifests are configured with the necessary Downward API environment variables or volume mounts as per OpenTelemetry documentation for the attributes you wish to collect.
gotcha The Downward API detectors are designed specifically for `k8s.*` and `container.*` OpenTelemetry attributes and are not a general-purpose mechanism for collecting arbitrary metadata.
Fix: Use other resource detectors or custom attributes for non-Kubernetes or non-container related metadata.
gotcha Resource detection, particularly when aggregating multiple detectors or interacting with external services (like cloud metadata), can introduce startup latency.
Fix: In production environments, consider explicitly enabling only the necessary detectors using the `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS` environment variable to minimize overhead. For example, `export OTEL_EXPERIMENTAL_RESOURCE_DETECTORS="kubernetes,env,host"`.
deprecated OpenTelemetry Kubernetes semantic conventions are actively evolving and have recently been promoted to release candidate status. While this library aims to adhere to these conventions, future updates could potentially introduce changes to attribute names or structures, which might impact existing monitoring dashboards or correlation logic.
Fix: Stay informed about OpenTelemetry semantic convention updates and be prepared to adapt your telemetry consumption or dashboard configurations if attribute names change. Regularly review the `opentelemetry-semantic-conventions` repository.

Install

pip install opentelemetry-resourcedetector-kubernetes Install latest version

Imports

KubernetesResourceDetector

from opentelemetry_resourcedetector_kubernetes import KubernetesResourceDetector

KubernetesDownwardAPIEnvironmentResourceDetector

from opentelemetry_resourcedetector_kubernetes import KubernetesDownwardAPIEnvironmentResourceDetector

KubernetesDownwardAPIVolumeResourceDetector

from opentelemetry_resourcedetector_kubernetes import KubernetesDownwardAPIVolumeResourceDetector

get_aggregated_resources

from opentelemetry.sdk.resources import get_aggregated_resources

Resource

from opentelemetry.sdk.resources import Resource

Quickstart

This quickstart demonstrates how to instantiate and use the `KubernetesResourceDetector` to gather Kubernetes-specific resource attributes. The detected attributes are then printed. In a full OpenTelemetry setup, this `resource` object would be passed to a `TracerProvider`, `MeterProvider`, or `LoggerProvider` to enrich all emitted telemetry.

import os
from opentelemetry.sdk.resources import get_aggregated_resources, Resource
from opentelemetry_resourcedetector_kubernetes import KubernetesResourceDetector

# Create a base resource (optional, but good practice for service name)
base_resource = Resource.create({
    "service.name": os.environ.get("OTEL_SERVICE_NAME", "my-kubernetes-app"),
    "service.version": "0.1.0"
})

# Aggregate resources from the Kubernetes detector and other potential detectors
# In a real Kubernetes environment, this will detect k8s.pod.uid, container.id, etc.
resource = get_aggregated_resources([
    KubernetesResourceDetector(),
    # Add other detectors here if needed, e.g., HostDetector(), OSDetector()
], initial_resource=base_resource)

print("Detected Resource Attributes:")
for key, value in resource.attributes.items():
    print(f"  {key}: {value}")

# The 'resource' object is then passed to a TracerProvider, MeterProvider, or LoggerProvider
# Example (conceptual, requires OpenTelemetry SDK tracing/metrics packages):
# from opentelemetry.sdk.trace import TracerProvider
# tracer_provider = TracerProvider(resource=resource)

view raw JSON →