Study guide

2.3 Zero-Code vs Code-Based Instrumentation

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

2.3 Zero-Code vs Code-Based Instrumentation

Key Takeaways Explain This Topic AI

Zero-code (automatic) instrumentation provides rapid time-to-value by intercepting standard framework calls at runtime without requiring application source code changes

Code-based (manual) instrumentation utilizes the OpenTelemetry API directly to record custom spans, metrics, business attributes, and precise span lifecycles

Zero-code mechanisms vary by runtime: Java bytecode rewriting via javaagent, Python/Node.js dynamic monkey-patching, .NET CLR profiler hooks, and Go/Linux eBPF kernel probes

The OpenTelemetry Operator for Kubernetes automates zero-code agent injection into application pods using Mutating Admission Webhooks and custom resources

The recommended industry standard is a hybrid strategy: deploy zero-code instrumentation for comprehensive framework and transport telemetry, enriched with code-based API calls for critical business paths

Last updated: September 2026

Zero-Code vs Code-Based Instrumentation

A central strategic decision when adopting OpenTelemetry across an engineering organization is selecting the right instrumentation mechanism. Teams rarely possess the engineering bandwidth to manually instrument millions of lines of application code upfront. Conversely, relying purely on generic automated agents leaves organizations blind to critical business domain transactions.

OpenTelemetry accommodates both extremes by supporting two fundamental approaches to telemetry generation:

Zero-Code Instrumentation (also termed Automatic Instrumentation or Out-of-Box Instrumentation).

Code-Based Instrumentation (also termed Manual or Programmatic Instrumentation).

Understanding how each approach operates under the hood, their respective performance and maintenance trade-offs, and how to combine them into an optimal hybrid strategy is the core of the Instrumentation competency.

Zero-Code (Automatic) Instrumentation

Zero-code instrumentation injects telemetry hooks into an application runtime without requiring developers to modify or recompile the application source code. It targets standard, widely used frameworks and transport libraries—such as HTTP web servers, HTTP clients, SQL database drivers, Redis clients, gRPC stubs, and message queues.

How Zero-Code Instrumentation Operates by Runtime

Because programming languages execute differently, OpenTelemetry uses distinct runtime mechanisms to implement zero-code instrumentation:

Java: Leverages the Java Virtual Machine (JVM) javaagent mechanism ( -javaagent:opentelemetry-javaagent.jar ). Using runtime bytecode manipulation libraries (such as Byte Buddy), the Java agent intercepts class loading, injects tracing and context propagation logic directly into compiled .class bytecode of known libraries (Spring, Netty, OkHttp, JDBC), and begins recording spans before application logic runs.

Python: After pip install opentelemetry-distro opentelemetry-exporter-otlp , the opentelemetry-bootstrap -a install command installs instrumentation packages for the libraries it finds (for example opentelemetry-instrumentation-flask ). Launching the app with the opentelemetry-instrument wrapper configures the SDK at startup and activates those instrumentors, which monkey-patch libraries such as requests , flask , fastapi , or psycopg2 at runtime.

Node.js: Leverages module loading hooks (using --require @opentelemetry/auto-instrumentations-node/register ). It wraps core Node.js modules ( http , https ) and popular npm packages ( express , ioredis , pg ) upon require/import.

.NET (C#): The .NET automatic instrumentation combines a startup hook, which loads the OpenTelemetry .NET SDK and its instrumentation libraries, with a Common Language Runtime (CLR) profiler ( CORECLR_ENABLE_PROFILING=1 on .NET, COR_ENABLE_PROFILING=1 on .NET Framework) that rewrites Intermediate Language (IL) at JIT time for libraries that need bytecode instrumentation. An instrument.sh script sets the required environment variables.

Go: Unlike managed runtimes, Go compiles to a static, unmanaged native binary without a dynamic classloader or reflection hooks. Historically, Go required manual instrumentation. Zero-code Go instrumentation uses eBPF (Extended Berkeley Packet Filter) probes in the Linux kernel, through the Go auto-instrumentation project or the language-agnostic OpenTelemetry eBPF Instrumentation (OBI), to observe HTTP, gRPC, and other calls without code changes; compile-time instrumentation is a separate, newer approach.

Kubernetes Operator: In cloud-native environments, the OpenTelemetry Operator for Kubernetes automates zero-code agent injection. By deploying an Instrumentation Custom Resource (CRD) and annotating pod templates (e.g., instrumentation.opentelemetry.io/inject-java: "true" ), a Kubernetes Mutating Admission Webhook injects init-containers, mounts agent binaries, and sets required environment variables automatically upon pod creation.

Advantages of Zero-Code Instrumentation

Immediate Time-to-Value: Teams can observe hundreds of microservices in a single afternoon by updating startup scripts or Kubernetes pod annotations.

Zero Codebase Modifications: Developers do not need to add dependencies, learn the OpenTelemetry API, or refactor legacy codebases.

Comprehensive Framework Coverage: Ingress and egress HTTP calls, database queries, and downstream gRPC interactions are captured consistently.

Automatic Context Propagation: The agent automatically injects and extracts W3C traceparent headers across supported HTTP and gRPC network boundaries, ensuring end-to-end distributed trace continuity.

Limitations of Zero-Code Instrumentation

Lack of Domain/Business Insight: Auto-instrumentation has no understanding of business domain models. It cannot capture order amounts, customer tiers, cart checkout items, or internal state machine transitions.

Black-Box Semantics: Internal private methods, complex algorithms, and business calculations executed purely in memory are completely invisible to auto-agents.

Startup and Runtime Overhead: Bytecode manipulation, class scanning, and pervasive function wrapping can increase JVM startup latency, memory footprint, and CPU overhead in high-throughput workloads.

Code-Based (Manual) Instrumentation

Code-based instrumentation involves explicitly importing the OpenTelemetry API into application source code, manually defining span boundaries, recording custom application metrics, and capturing domain-specific attributes.

The OpenTelemetry API vs. SDK Separation

A critical tenet of code-based instrumentation is the architectural boundary between the API and the SDK :

OpenTelemetry API: Defines the interfaces, data models, context propagation contracts, and no-op default implementations. Application source code and third-party libraries MUST depend solely on the OpenTelemetry API .

OpenTelemetry SDK: The concrete implementation of the API, containing span processors, samplers, metric readers, queue buffers, and OTLP network exporters. The SDK is configured exclusively at the top-level application entry point or startup harness. # Practical Code-Based Instrumentation in Python (API only)

  • from opentelemetry import trace
  • from opentelemetry.trace import StatusCode

tracer = trace.get_tracer("checkout-service", "1.0.0")

def process_order(order):

# 1. Start a named business span

with tracer.start_as_current_span("process_order") as span:

try:

  • # 2. Attach domain-specific business attributes
  • span.set_attribute("order.id", order.id)
  • span.set_attribute("order.total_amount", order.total_amount)
  • span.set_attribute("customer.tier", order.customer.tier)
  • # 3. Record an in-span event
  • span.add_event("fraud_check_started", {"check_level": "strict"})
  • run_fraud_check(order)
  • # Execute payment
  • charge_customer(order)

except PaymentDeclinedException as e:

  • # 4. Mark span status as error
  • span.set_status(StatusCode.ERROR, "Payment authorization failed")
  • span.record_exception(e)
  • raise
  • Advantages of Code-Based Instrumentation

Granular Domain Visibility: Engineers can capture business metrics ( orders_placed_total ), custom timers, and domain dimensions ( payment_provider="stripe" ).

Precise Span Lifecycle: Spans can be created exactly where a critical transaction starts and ends, rather than adhering strictly to network boundary entry/exit points.

Span Events and Exception Tracking: Custom milestone events and sanitized exception stack traces can be recorded directly onto the active span.

Negligible Overhead: No runtime reflection scanning, monkey-patching, or dynamic bytecode transformation is required.

Limitations of Code-Based Instrumentation

High Engineering Effort: Developers must write, test, and maintain instrumentation code across every repository.

Code Clutter: Telemetry calls can obscure core domain business logic if not implemented with clean architectural separation.

Risk of Context Propagation Loss: If developers run background threads or asynchronous tasks without explicitly propagating Context , distributed traces will break.

The Hybrid Strategy: Industry Best Practice

In modern production architectures, the question is not whether to choose zero-code or code-based instrumentation, but how to combine both into a coherent hybrid strategy . +---------------------------------------------------------------+

  • | Application Process |
  • | |
  • | [ Zero-Code Agent Layer ] |
  • | - Intercepts incoming HTTP/gRPC requests |
  • | - Extracts W3C traceparent and starts root span |
  • | - Intercepts database calls (db.query.text) |
  • | - Injects W3C traceparent into downstream outbound calls |
  • | |
  • | [ Manual API Layer (Domain Enrichment) ] |
  • | - Obtains active span: trace.get_current_span() |
  • | - Appends business attributes: span.set_attribute(...) |
  • | - Records domain events and exceptions |
  • | - Creates inner child spans for slow business algorithms |
  • +---------------------------------------------------------------+

Recommended Two-Tier Workflow:

Tier 1 (Base Coverage via Zero-Code): Deploy the zero-code agent (via JVM -javaagent , Python wrapper, or OpenTelemetry Kubernetes Operator). This instantly guarantees end-to-end distributed context propagation, inbound server spans, database query spans, and outbound client calls.

Tier 2 (Domain Enrichment via OpenTelemetry API): In performance-critical microservices, application code imports the lightweight opentelemetry-api package. Developers grab the currently active span created by the agent ( trace.get_current_span() ), attach business attributes ( order.total_value , tenant.id ), and create targeted child spans around compute-heavy business methods.

Comparison Matrix: Zero-Code vs. Code-Based

  • Evaluation Dimension Zero-Code (Automatic) Code-Based (Manual) Hybrid Approach (Recommended)
  • Initial Setup Effort Minimal (Minutes/Hours) High (Weeks/Months) Moderate (Hours to start, ongoing refinement)
  • Application Code Changes None required Required across codebases None for base; minimal for business paths

Runtime Mechanisms Bytecode manipulation, monkey-patching, eBPF Direct API method invocation Agent bytecode + native API calls

Business Logic Visibility Zero (only network/I/O boundaries) Complete (any internal variable or state) Complete (standard I/O + domain attributes)

Context Propagation Automatic across standard protocols Developer must manage across threads Automatic via agent; manual across threads

Maintenance Overhead Kept in sync via agent version upgrades Code refactoring when conventions change Low maintenance; stable API interfaces

Supported Languages Java, Python, Node.js, .NET, Go (eBPF) All languages supporting OpenTelemetry API All primary managed cloud runtimes

Loading diagram... Hybrid Instrumentation Architecture