Skip to main content

opentelemetry-resourcedetector-kubernetes

An OpenTelemetry package to populate Resource attributes for Kubernetes pods.

Usage

from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry_resourcedetector_kubernetes import KubernetesResourceDetector

...

resource = get_aggregated_resources([
    KubernetesResourceDetector(),
    SomeOtherResourceDetector()
])

... pass the returned `resource` to a TracerProvider, for example ...

The KubernetesResourceDetector is able to detect the basic identifying information for a Pod, returning as Resource with these attributes populated:

  • container.runtime - always the string "kubernetes"
  • container.id - the unique ID of the container (a string of hexadecimal characters)
  • k8s.pod.uid - the UUID of the pod where your container and code is running

This resource detector is the base class for the others in this package, and so you will always get these three attributes in your traces, using any of the more detailed detectors below.

Detecting more attributes with The "Downward API"

The Kubernetes "Downward API" is a safe way to to pass Kubernetes metadata about your pod to itself, as either:

For either of these methods to work, you will need to add the appropriate configuration to your Kubernetes manifests, and you'll configure the detector accordingly.

The opentelemetry_resourcedetector_kubernetes classes using the Downward API will only detect and populate attributes from the standard OpenTelemetry Kubernetes Resource Attribute that you choose to provide by configuring them in your manifests. These detectors will only report k8s.* and container.* OpenTelemetry attributes, and are not intended to be a general-purpose collection mechanism for other types of attributes.

The Downward API only supports a subset of all the possible attributes you could provide. Depending on your needs, you can also provide hard-coded environment variables following the same naming conventino in your Kubernetes manifest, or mix the environment and volume approaches to paint a more complete picture.

KubernetesDownwardAPIEnvironmentResourceDetector

For an example of using environment variables, you can pass a Pod's namespace and name:

apiVersion: v1
kind: Pod
metadata:
  namespace: cool-app
  name: example-pod
spec:
  containers:
  - name: a-container
    image: my-image:1.0.0
    command: ["run-my-cool-app"]
    env:
    - name: OTEL_RD_K8S_NAMESPACE_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.namespace
    - name: OTEL_RD_K8S_POD_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.name

Then, your running pod will see these environment variables populated:

OTEL_RD_K8S_NAMESPACE_NAME=cool-app
OTEL_RD_K8S_POD_NAME=example-pod

When configuring your telemetry, you'll establish a "contract" for the names of the environment variables, indicating that they will be prefixed with OTEL_RD. The prefix is up to you, but the default is OTEL_RD. From there, the resource detector will look for each environment variables prefixed with OTEL_RD_, and if the rest of its name matches a standard OpenTelemetry Kubernetes Resource Attribute, it will be used during resource detection.

from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry_resourcedetector_kubernetes import KubernetesDownwardAPIEnvironmentResourceDetector

...

resource = get_aggregated_resources([
    KubernetesDownwardAPIEnvironmentResourceDetector(prefix='OTEL_RD'),
    SomeOtherResourceDetector()
])

... pass the returned `resource` to a TracerProvider, for example ...

In this example, the Resource for all traces would include the attributes:

container.runtime = "kubernetes"
k8s.pod.uid = "...the UUID of the pod..."
container.id = "...the id of the container..."

k8s.namespace.name = "cool-app"
k8s.pod.name = "example-pod"

KubernetesDownwardAPIVolumeResourceDetector

For an example of using a Downward API volume, you can pass a Pod's namespace and name:

apiVersion: v1
kind: Pod
metadata:
  namespace: cool-app
  name: example-pod
spec:
  containers:
  - name: a-container
    image: my-image:1.0.0
    command: ["run-my-cool-app"]
    volumeMounts:  # this is at the *Container* level
    - name: otelrd
      mountPath: /etc/otelrd
  volumes:  # this is at the *Pod* level
    - name: otelrd
      downwardAPI:
        items:
        - path: k8s.namespace.name
          fieldRef:
            fieldPath: metadata.namespace
        - path: k8s.pod.name
          fieldRef:
            fieldPath: metadata.name

Then, your running pod will see these environment variables populated:

$ cat /etc/otelrd/k8s.namespace.name
cool-app
$ cat /etc/otelrd/k8s.pod.name
example-pod

When configuring your telemetry, you'll establish a "contract" by indicating the directory into which you are mounting the Downward API metadata files (/etc/otelrd by default). From there, the resource detector will look for files matching the names of standard OpenTelemetry Kubernetes Resource Attributes.

from opentelemetry.sdk.resources import get_aggregated_resources
from opentelemetry_resourcedetector_kubernetes import KubernetesDownwardAPIEnvironmentResourceDetector

...

resource = get_aggregated_resources([
    KubernetesDownwardAPIVolumeResourceDetector(directory='/etc/otelrd'),
    SomeOtherResourceDetector()
])

... pass the returned `resource` to a TracerProvider, for example ...

In this example, the Resource for all traces would include the attributes:

container.runtime = "kubernetes"
k8s.pod.uid = "...the UUID of the pod..."
container.id = "...the id of the container..."

k8s.namespace.name = "cool-app"
k8s.pod.name = "example-pod"

Metadata

Release files for opentelemetry-resourcedetector-kubernetes 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opentelemetry-resourcedetector-kubernetes 0.4.0
File Size Uploaded Provenance Actions
opentelemetry_resourcedetector_kubernetes-0.4.0.tar.gz 27.7 kB Without provenance Details for opentelemetry_resourcedetector_kubernetes-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for opentelemetry-resourcedetector-kubernetes 0.4.0
File Interpreter ABI Platform Actions
opentelemetry_resourcedetector_kubernetes-0.4.0-py3-none-any.whl Python 3 none any Details for opentelemetry_resourcedetector_kubernetes-0.4.0-py3-none-any.whl

Total release size: 33.7 kB

Release files / opentelemetry_resourcedetector_kubernetes-0.4.0.tar.gz

Download URL opentelemetry_resourcedetector_kubernetes-0.4.0.tar.gz
Size 27.7 kB
Tags Source
SHA-256 checksum
How to use checksums
e7a27696500ce9b77bccdef04490d64f26d76ebb1cd28adc6af1397bdd850f2f
BLAKE2b-256 checksum
How to use checksums
43e548a5756b30b37897fec382173bc3ddf6e9f7ab9b2da40824daafb98c65cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / opentelemetry_resourcedetector_kubernetes-0.4.0-py3-none-any.whl

Download URL opentelemetry_resourcedetector_kubernetes-0.4.0-py3-none-any.whl
Size 6.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
971d82ce7a9c0347ff422220a98a7a903f859afef36a63e86d9333981bf67c42
BLAKE2b-256 checksum
How to use checksums
4d1b7c97d0d8290dff706c24853dffc0890ed9b91a4cbc5ff6375f1979237f1e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for opentelemetry-resourcedetector-kubernetes 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page