{"id":3724,"library":"opentelemetry-resourcedetector-kubernetes","title":"OpenTelemetry Kubernetes Resource Detector","description":"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.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/chrisguidry/opentelemetry-resourcedetector-kubernetes","tags":["opentelemetry","kubernetes","resource-detector","observability","telemetry","python"],"install":[{"cmd":"pip install opentelemetry-resourcedetector-kubernetes","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for core OpenTelemetry SDK functionalities like `get_aggregated_resources` and `Resource`.","package":"opentelemetry-sdk"}],"imports":[{"symbol":"KubernetesResourceDetector","correct":"from opentelemetry_resourcedetector_kubernetes import KubernetesResourceDetector"},{"symbol":"KubernetesDownwardAPIEnvironmentResourceDetector","correct":"from opentelemetry_resourcedetector_kubernetes import KubernetesDownwardAPIEnvironmentResourceDetector"},{"symbol":"KubernetesDownwardAPIVolumeResourceDetector","correct":"from opentelemetry_resourcedetector_kubernetes import KubernetesDownwardAPIVolumeResourceDetector"},{"symbol":"get_aggregated_resources","correct":"from opentelemetry.sdk.resources import get_aggregated_resources"},{"symbol":"Resource","correct":"from opentelemetry.sdk.resources import Resource"}],"quickstart":{"code":"import os\nfrom opentelemetry.sdk.resources import get_aggregated_resources, Resource\nfrom opentelemetry_resourcedetector_kubernetes import KubernetesResourceDetector\n\n# Create a base resource (optional, but good practice for service name)\nbase_resource = Resource.create({\n    \"service.name\": os.environ.get(\"OTEL_SERVICE_NAME\", \"my-kubernetes-app\"),\n    \"service.version\": \"0.1.0\"\n})\n\n# Aggregate resources from the Kubernetes detector and other potential detectors\n# In a real Kubernetes environment, this will detect k8s.pod.uid, container.id, etc.\nresource = get_aggregated_resources([\n    KubernetesResourceDetector(),\n    # Add other detectors here if needed, e.g., HostDetector(), OSDetector()\n], initial_resource=base_resource)\n\nprint(\"Detected Resource Attributes:\")\nfor key, value in resource.attributes.items():\n    print(f\"  {key}: {value}\")\n\n# The 'resource' object is then passed to a TracerProvider, MeterProvider, or LoggerProvider\n# Example (conceptual, requires OpenTelemetry SDK tracing/metrics packages):\n# from opentelemetry.sdk.trace import TracerProvider\n# tracer_provider = TracerProvider(resource=resource)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use other resource detectors or custom attributes for non-Kubernetes or non-container related metadata.","message":"The Downward API detectors are designed specifically for `k8s.*` and `container.*` OpenTelemetry attributes and are not a general-purpose mechanism for collecting arbitrary metadata.","severity":"gotcha","affected_versions":"All versions"},{"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\"`.","message":"Resource detection, particularly when aggregating multiple detectors or interacting with external services (like cloud metadata), can introduce startup latency.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"Potentially future versions (from 0.3.0 onwards as conventions stabilize)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}