Study guide
8.4 Zero-Code Agents: Configuration, Kubernetes Injection & Troubleshooting
OpenTelemetry Certified Associate OTCA
Track your progress as you read
Finished sections get a check mark.
1 Chapter 1: Exam Overview & Observability Foundations
1.1 OTCA Exam Structure & Observability Paradigms 1.2 Core Telemetry Signals: Traces, Metrics, Logs & Baggage 1.3 Telemetry Analysis, SLOs & High Cardinality
2 Chapter 2: Semantic Conventions & Instrumentation Strategy
2.1 OpenTelemetry Semantic Conventions & Namespaces 2.2 Resource Attributes & Entity Modeling 2.3 Zero-Code vs Code-Based Instrumentation
3 Chapter 3: OpenTelemetry Architecture & The Data Model
3.1 Architectural Separation of API and SDK 3.2 The Core Trace Model: Spans, SpanContext & Links 3.3 Span Events, Attributes & Status Codes 3.4 Composability & Extension: Plugin Interfaces, Distributions & Contrib
4 Chapter 4: Distributed Tracing & Context Propagation
4.1 In-Process & Cross-Process Context Propagation 4.2 W3C Trace Context Specification 4.3 W3C Baggage & Alternative Propagators
5 Chapter 5: OpenTelemetry Metrics API & Instruments
5.1 Synchronous Metric Instruments 5.2 Asynchronous (Observable) Metric Instruments 5.3 Metric Aggregations & Temporality
6 Chapter 6: Logs Data Model & Logging Bridge API
6.1 OpenTelemetry Logs Data Model & Architecture 6.2 The Logging Bridge API & Log Appenders
7 Chapter 7: SDK Pipelines, Processors & Exporters
7.1 Span Processors & Exporters 7.2 Metric Readers & Log Processors 7.3 Standard Exporters & OTLP Wire Protocols
8 Chapter 8: Sampling Strategies, SDK Configuration & Agents
8.1 Head-Based Sampling & Built-in Samplers 8.2 Tail-Based Sampling vs Head-Based Sampling 8.3 OpenTelemetry SDK Configuration & Environment Variables 8.4 Zero-Code Agents: Configuration, Kubernetes Injection & Troubleshooting
9 Chapter 9: OpenTelemetry Collector Architecture & Pipelines
9.1 Collector Core Architecture & Component Lifecycle 9.2 Collector Configuration Structure & Pipelines 9.3 Essential Collector Extensions
10 Chapter 10: Collector Components: Receivers, Processors & Exporters
10.1 Standard Receivers & Ingestion Protocols 10.2 Core Processors & Execution Order 10.3 Standard Exporters & Delivery Guarantees
11 Chapter 11: Data Transformation & The OpenTelemetry Transformation Language (OTTL)
11.1 OTTL Concepts & Syntax Grammar 11.2 Transform Processor In Action 11.3 Advanced Connectors
12 Chapter 12: Collector Deployment, Scaling & Resilience
12.1 Agent vs Gateway Deployment Topologies 12.2 Scaling, Load Balancing & High Availability 12.3 Resilience: Backpressure, Buffering & Persistent Queues
13 Chapter 13: Maintaining, Debugging & Schema Evolution
13.1 Debugging Collector Pipelines & Telemetry Health 13.2 Troubleshooting Broken Traces & Context Loss 13.3 Schema Management & Telemetry Evolution
8.4 Zero-Code Agents: Configuration, Kubernetes Injection & Troubleshooting
Key Takeaways Explain This Topic AI
An OpenTelemetry agent is a zero-code package attached to a process (Java agent JAR, Python opentelemetry-instrument, Node.js auto-instrumentations register module, .NET automatic instrumentation, or eBPF tools such as OBI) that bundles the SDK, instrumentations, and exporters.
Agents read the standard OTEL_* settings, and each language adds switches to disable individual instrumentations, such as Java's OTEL_INSTRUMENTATION_[NAME]_ENABLED and Python's OTEL_PYTHON_DISABLED_INSTRUMENTATIONS.
The OpenTelemetry Operator injects agents through an Instrumentation resource plus inject-java, inject-python, inject-nodejs, inject-dotnet, or inject-go pod annotations, and only at pod creation.
Go injection uses a privileged eBPF sidecar and requires the target executable path through the otel-go-auto-target-exe annotation or the Instrumentation resource.
When an agent is attached, application code should use only the OpenTelemetry API for custom spans; building a second SDK in code causes duplicate pipelines.
Last updated: September 2026
8.4 Zero-Code Agents: Configuration, Kubernetes Injection & Troubleshooting
Quick Answer: In the API and SDK domain, an agent is a zero-code instrumentation package attached to a running process: the Java agent JAR, Python's opentelemetry-instrument wrapper, Node.js's auto-instrumentations-node/register module, the .NET automatic instrumentation, or an eBPF instrumenter such as OBI. An agent bundles the SDK, instrumentation libraries, and exporters, and it reads the same OTEL_* settings as any SDK. In Kubernetes, the OpenTelemetry Operator injects agents through an Instrumentation resource and pod annotations. Do not confuse this with the Collector agent deployment pattern in Chapter 12.
Section 2.3 compared zero-code and code-based instrumentation as a strategy. This section covers the operational side of the Agents competency: how each agent is attached and configured, how to switch individual instrumentations on and off, how the Operator injects agents, and how to troubleshoot an agent that produces no data.
What an Agent Contains
An agent adds three things to a process that has no OpenTelemetry code of its own:
The API and an SDK , configured automatically from environment variables, system properties, or (where supported) a declarative configuration file.
Instrumentation libraries for supported frameworks and clients (HTTP servers and clients, database drivers, messaging clients, gRPC).
Exporters , usually OTLP, plus the standard propagators ( tracecontext,baggage by default).
Because the agent uses the standard configuration, the same variables work everywhere: OTEL_SERVICE_NAME , OTEL_RESOURCE_ATTRIBUTES , OTEL_EXPORTER_OTLP_ENDPOINT , OTEL_EXPORTER_OTLP_PROTOCOL , OTEL_TRACES_SAMPLER , and OTEL_PROPAGATORS .
Attaching and Configuring Agents by Language
Runtime How the agent is attached Selecting instrumentations Notes
Java -javaagent:/path/opentelemetry-javaagent.jar , or the same flag in JAVA_TOOL_OPTIONS OTEL_INSTRUMENTATION_[NAME]_ENABLED=false turns one library off; OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED=false turns all off so you can enable a few; OTEL_JAVAAGENT_ENABLED=false disables the agent Configuration sources, highest priority first: system properties, environment variables, a properties file ( otel.javaagent.configuration-file ), then customizer SPIs. Extensions load from otel.javaagent.extensions .
Python pip install opentelemetry-distro opentelemetry-exporter-otlp , then opentelemetry-bootstrap -a install , then run opentelemetry-instrument python app.py OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=redis,kafka opentelemetry-bootstrap installs instrumentation packages only for libraries already present in the environment; the instrumentors monkey-patch those libraries at startup.
Node.js node --require @opentelemetry/auto-instrumentations-node/register app.js , or the same flag in NODE_OPTIONS OTEL_NODE_ENABLED_INSTRUMENTATIONS="http,express" or OTEL_NODE_DISABLED_INSTRUMENTATIONS OTEL_NODE_RESOURCE_DETECTORS limits which resource detectors run.
.NET Run the installer script, then source instrument.sh , which sets the CLR profiler and startup-hook environment variables OTEL_DOTNET_AUTO_* settings Works with .NET and .NET Framework 4.6.2 or later.
Go and others (eBPF) Go auto-instrumentation or OpenTelemetry eBPF Instrumentation (OBI) runs beside the process with elevated Linux privileges Configured through the eBPF tool OBI observes Java, .NET, Go, Python, Ruby, Node.js, C, C++, and Rust workloads and produces spans and RED metrics without touching the code.
Adding Custom Telemetry on Top of an Agent
The agent does not stop you from writing code-based instrumentation. For Java, add the opentelemetry-api dependency and create spans or use the @WithSpan annotation; the agent connects those API calls to its own SDK. The common mistake is to also build and register a second SDK in application code, which produces duplicate or conflicting pipelines. When an agent is present, application code should only use the API.
Kubernetes Injection with the OpenTelemetry Operator
The Operator automates agent attachment in Kubernetes:
Create an Instrumentation custom resource that holds shared settings: the exporter endpoint, propagators, sampler, and per-language images.
Annotate a namespace or pod template with the language to inject, for example instrumentation.opentelemetry.io/inject-java: "true" . The other annotations are inject-python , inject-nodejs , inject-dotnet , inject-go , and inject-sdk (which only sets SDK environment variables).
When a pod is created , the Operator's mutating admission webhook adds an init container that copies the agent into the pod and sets the environment variables ( JAVA_TOOL_OPTIONS , OTEL_EXPORTER_OTLP_ENDPOINT , OTEL_SERVICE_NAME , resource attributes, and so on). 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"
Operational points to remember:
Injection happens only at pod creation. Annotating a Deployment that is already running does nothing until its pods are recreated (for example with a rollout restart).
Match the protocol to the port. The Operator's .NET instrumentation exports OTLP over http/protobuf by default, so its endpoint must be the Collector's HTTP port (4318); check each language's default before pointing it at 4317.
Go is different. Go injection adds an eBPF sidecar that needs elevated privileges ( privileged: true , running as root) and the target binary path, supplied with the instrumentation.opentelemetry.io/otel-go-auto-target-exe annotation or in the Instrumentation resource; without it, injection is aborted.
Troubleshooting an Agent That Produces No Data
Symptom Likely cause Check or fix
Service appears as unknown_service:java OTEL_SERVICE_NAME not set Set it in the pod spec or the Instrumentation resource
No spans from a Python framework Instrumentation package missing Re-run opentelemetry-bootstrap -a install after installing the framework
Spans exported nowhere Wrong endpoint or protocol/port mismatch Temporarily set OTEL_TRACES_EXPORTER=console to print spans locally; confirm 4317 is gRPC and 4318 is HTTP
Annotated pods show no agent Pods created before the annotation, or no matching Instrumentation resource Restart the workload; confirm the resource exists in the namespace
Too much overhead or noisy spans Every supported library is instrumented Disable specific instrumentations (Java OTEL_INSTRUMENTATION_[NAME]_ENABLED=false , Python OTEL_PYTHON_DISABLED_INSTRUMENTATIONS , Node.js OTEL_NODE_DISABLED_INSTRUMENTATIONS )
Duplicate spans Both an agent and a manually built SDK are active Keep only the agent's SDK; application code uses the API alone