> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Auto Instrumentation Using the OpenTelemetry Operator
> Explains using the OpenTelemetry Operator to auto-instrument Kubernetes workloads, centralizing instrumentation configuration and injecting language agents via Instrumentation custom resources and annotations.
This article explains how auto-instrumentation works with the OpenTelemetry Operator and how it simplifies collecting telemetry from applications running in Kubernetes. While manual instrumentation remains an option, operator-based auto-instrumentation lets you collect traces, metrics, and logs with minimal code changes.
Auto-instrumentation is ideal when you need quick visibility into running workloads or when you want consistent observability settings across many deployments and namespaces.
Why use auto-instrumentation?
* Fast path to visibility when you lack instrumentation in running workloads.
* Centralized configuration reduces duplication and human error.
* Operator ensures consistent agent injection and environment configuration across pods.
What the Operator does
* Injects language-specific instrumentation libraries or agents into targeted pods.
* Sets environment variables and runtime flags required by those agents.
* Routes telemetry to a configured OpenTelemetry Collector or exporter endpoint.
Instrumentation custom resources (CRs)
A Kubernetes Custom Resource Definition (CRD) extends the API with new kinds. The OpenTelemetry Operator defines an Instrumentation custom resource that centralizes shared observability settings—exporter endpoints, propagators, samplers, and more—so you don't repeat them in every Deployment or Pod.
When an Instrumentation CR exists in a namespace, workloads can opt in via annotations. This model is particularly useful at scale (many namespaces or clusters) for enforcing consistent telemetry configuration.
Example Instrumentation CR
This example creates an Instrumentation CR that directs the operator to export OTLP to a collector and configures propagators and sampling:
```yaml theme={null}
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
name: demo-instrumentation
spec:
exporter:
endpoint: http://demo-collector:4318
propagators:
- tracecontext
- baggage
sampler:
type: parentbased_traceidratio
argument: "1"
```
Exam-style recall question
What is the Kubernetes kind that automatically instruments applications in Kubernetes?
Answer: Instrumentation
How the CR maps to injected environment variables
The Operator translates the Instrumentation spec into environment variables and agent-specific settings inside the injected pod. Common mappings include:
* `spec.exporter.endpoint` → `OTEL_EXPORTER_OTLP_ENDPOINT` (or agent-specific equivalent).
* `spec.propagators` → `OTEL_PROPAGATORS` with comma-separated values.
* `spec.sampler` → `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG` (or similar).
Illustrative example of injected env vars in a Pod:
```yaml theme={null}
# Example injected env vars in a Pod (illustrative)
env:
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: "http://demo-collector:4318"
- name: OTEL_PROPAGATORS
value: "tracecontext,baggage"
- name: OTEL_TRACES_SAMPLER
value: "parentbased_traceidratio"
- name: OTEL_TRACES_SAMPLER_ARG
value: "1"
```
Sampling options
You control sampling behavior from the Instrumentation CR. The snippet below shows sampler configuration and common choices:
```yaml theme={null}
# In the Instrumentation CR
spec:
sampler:
type: parentbased_traceidratio
argument: "1" # 1 = 100%; 0.25 = 25%; 0 = 0%
```
Common sampler types:
| Sampler type | Behavior |
| -------------------------- | ------------------------------------------------------------------------------ |
| `always_on` | Sample all traces |
| `always_off` | Sample no traces |
| `traceidratio` | Sample approximately the fraction set by `argument` (e.g., `"0.2"` = 20%) |
| `parentbased_traceidratio` | Parent-based sampling; when no parent exists, `argument` controls the fraction |
Enabling auto-instrumentation for workloads
Workloads opt in by adding annotations on the Pod template. Each runtime has a specific annotation key.
Pod template annotations example:
```yaml theme={null}
spec:
template:
metadata:
annotations:
instrumentation.opentelemetry.io/inject-java: "true"
instrumentation.opentelemetry.io/inject-python: "true"
instrumentation.opentelemetry.io/inject-nodejs: "true"
instrumentation.opentelemetry.io/inject-dotnet: "true"
```
Patch an existing Deployment to enable Python auto-instrumentation:
```bash theme={null}
kubectl -n appns patch deploy web --type merge -p '
{
"spec": {"template": {"metadata": {"annotations": {
"instrumentation.opentelemetry.io/inject-python": "true"
}}}}
}'
```
Annotation values and semantics
| Annotation value | Meaning |
| ---------------- | --------------------------------------------------------------------------- |
| `"true"` | Use the default Instrumentation CR in the same namespace |
| `"name"` | Use an Instrumentation CR in the same namespace by name |
| `"ns/name"` | Use an Instrumentation CR from another namespace (useful for shared config) |
| `"false"` | Explicitly opt out of injection for this workload |
Namespace-level opt-in
Instead of annotating individual pod templates, you can annotate a Namespace to enable injection for all pods in that namespace:
```yaml theme={null}
# Opt-in at Namespace level (affects all Pods in the namespace)
apiVersion: v1
kind: Namespace
metadata:
name: appns
annotations:
instrumentation.opentelemetry.io/inject-python: "true"
```
Use namespace-level injection with care. It will affect all pods in the namespace, including system, test, or utility pods that may not need instrumentation.
Supported languages
The Operator supports injecting language-specific agents and setting the appropriate environment variables. Commonly supported runtimes include Java, .NET, Node.js, Python, and Go.
Key takeaways
* The OpenTelemetry Operator centralizes observability settings through the Instrumentation custom resource.
* Instrumentation CRs define exporters, propagators, samplers, and other shared configuration to avoid per-deployment duplication.
* Workloads opt in to auto-instrumentation via pod annotations or namespace annotations; annotations can reference Instrumentation CRs across namespaces.
* Apply namespace-level injection carefully to prevent unintentional agent injection.
Links and references
* OpenTelemetry: [https://opentelemetry.io/](https://opentelemetry.io/)
* OpenTelemetry Operator (GitHub): [https://github.com/open-telemetry/opentelemetry-operator](https://github.com/open-telemetry/opentelemetry-operator)
* OpenTelemetry Collector: [https://opentelemetry.io/docs/collector/](https://opentelemetry.io/docs/collector/)
That covers the essentials of OpenTelemetry auto-instrumentation using the Operator.