Study guide
9.3 Essential Collector Extensions
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
9.3 Essential Collector Extensions
Key Takeaways Explain This Topic AI
Extensions provide auxiliary runtime, diagnostic, and security capabilities for the Collector without participating in or modifying telemetry in the pipeline data path.
The health_check extension listens on localhost:13133 with path / by default; for Kubernetes probes, bind it to 0.0.0.0 or the pod IP and optionally set a path such as /healthz.
The pprof extension exposes Go runtime profiling endpoints on default port 1777 to diagnose CPU hotspots, heap memory churn, and goroutine leaks under production load.
The zpages extension serves in-process diagnostic pages on port 55679 (such as /debug/servicez, /debug/pipelinez, and /debug/tracez), showing pipeline composition and latency-bucketed internal spans without external tooling.
The historical memory_ballast extension is deprecated in modern OpenTelemetry Collector versions, replaced by the native Go GOMEMLIMIT environment variable coupled with the memory_limiter processor.
Last updated: September 2026
9.3 Essential Collector Extensions
Quick Answer: Collector extensions provide auxiliary runtime, diagnostic, and security capabilities without processing telemetry directly in the pipeline data path. Key operational extensions include health_check (HTTP port 13133 for Kubernetes liveness/readiness probes), pprof (port 1777 for Go CPU and memory profiling), zpages (port 55679 for live in-process pipeline diagnostics), and authentication extensions ( oidc , basicauth , bearertokenauth ). Extensions are declared under extensions: and must be explicitly activated in service.extensions: [...] . Note that the legacy memory_ballast extension is deprecated in favor of Go's native GOMEMLIMIT environment variable.
While receivers, processors, and exporters handle the direct ingestion, transformation, and delivery of telemetry data, running an OpenTelemetry Collector reliably in production requires operational infrastructure support. The Collector needs to report its readiness to container orchestrators, expose runtime profiling to engineers troubleshooting memory leaks, and authenticate incoming microservice connections. These auxiliary capabilities are provided by Extensions .
What are Collector Extensions?
Extensions are standalone components within the Collector runtime that provide auxiliary services, environment management, and diagnostics. Unlike processors or exporters, extensions never touch telemetry data directly :
They do not receive pdata instances.
They do not sit inside service.pipelines .
They do not mutate or route spans, metrics, or logs.
Instead, extensions hook into the Collector's startup and shutdown lifecycle events to host HTTP/gRPC management servers, background monitors, or authentication providers. +-------------------------------------------------------------------------+
- | OpenTelemetry Collector |
- | |
- | +-----------------------------------------------------------------+ |
- | | Data Pipelines (In-Path) | |
- | | [Receivers] ===> [Processors] ===> [Exporters] | |
- | +-----------------------------------------------------------------+ |
- | ^ |
- | | Uses Auth / Lifecycle Events |
- | +----------------------------+------------------------------------+ |
- | | Extensions (Out-of-Path) | |
- | | [health_check :13133] [pprof :1777] [zpages :55679] [auth] | |
- | +-----------------------------------------------------------------+ |
- +-------------------------------------------------------------------------+
- | | | |
- v v v v
- [K8s Kubelet Probes] [Go Profiler CLI] [Web Browser] [IdP / JWT]
- Activating Extensions
Like all Collector components, declaring an extension under the top-level extensions block only configures its parameters. To instantiate and run an extension, it must be explicitly added to the service.extensions array: extensions:
health_check:
endpoint: 0.0.0.0:13133
pprof:
endpoint: 0.0.0.0:1777
zpages:
endpoint: 0.0.0.0:55679
service:
extensions: [health_check, pprof, zpages] # Activates and starts extensions
pipelines:
traces:
- receivers: [otlp]
- processors: [batch]
- exporters: [otlp]
If an extension is omitted from service.extensions , its network listeners will not open, and dependent probes or authenticators will fail.
Key Operational Extensions
Four operational extensions matter most day to day. Know their default ports and diagnostic roles:
1. health_check Extension
The health_check extension provides an HTTP endpoint indicating whether the Collector process is operational. It is the primary mechanism used by Kubernetes liveness probes and readiness probes .
Default Endpoint : localhost:13133 with path / . Because the default binds only to localhost, a Kubernetes probe (which calls the pod IP) needs endpoint: 0.0.0.0:13133 or the pod IP, and you may set path: /healthz .
HTTP Status Codes :
200 OK : Returned when the Collector has successfully completed initialization and all configured pipelines, receivers, processors, and exporters are operational.
503 Service Unavailable : Returned if the Collector is still booting, if a fatal runtime error has disabled a core component, or if the Collector has entered its graceful shutdown sequence. extensions:
health_check:
- endpoint: 0.0.0.0:13133
- path: "/healthz"
- # Do not rely on check_collector_pipeline: its README warns that it is not
# working as expected. The newer healthcheckv2 extension reports per-component status.
Kubernetes Integration Example livenessProbe:
httpGet:
- path: /healthz
- port: 13133
- initialDelaySeconds: 5
- periodSeconds: 10
readinessProbe:
httpGet:
- path: /healthz
- port: 13133
- initialDelaySeconds: 3
- periodSeconds: 5
- 2. pprof Extension (Performance Profiling)
The pprof extension exposes Go runtime profiling data using Go's built-in net/http/pprof package. When high-throughput Collectors experience CPU saturation, thread starvation, or memory growth, pprof allows engineers to inspect runtime internals without restarting the process.
- Default Port : 1777
- Base Endpoint : /debug/pprof/
Diagnostic Sub-Endpoints :
/debug/pprof/profile : Triggers a 30-second CPU sampling profile to identify CPU hotspots (such as aggressive regex matching or JSON serialization).
/debug/pprof/heap : Captures heap memory allocations to locate memory leaks and excessive memory allocation churn.
/debug/pprof/goroutine : Dumps stack traces of all active goroutines to detect blocked network calls or deadlocked channels.
/debug/pprof/allocs : Displays all past memory allocations since process startup. # Inspecting a live Collector's heap using the Go pprof CLI
go tool pprof http://localhost:1777/debug/pprof/heap
Warning
Production security best practice: The pprof extension exposes internal runtime stack traces, memory layouts, and server paths. It should never be exposed to public networks . Always bind pprof to localhost:1777 or restrict access using Kubernetes network policies.
3. zpages Extension (In-Process Web Diagnostics)
Originating from internal diagnostic infrastructure at Google, zpages serves live, in-process HTML diagnostic pages directly from the Collector memory space. It allows operators to debug pipeline issues instantly using a web browser without requiring external Prometheus servers or APM dashboards.
Default Port : 55679
Key Diagnostic Pages :
http://<host>:55679/debug/servicez : An overview of the Collector build and links to the other pages.
http://<host>:55679/debug/pipelinez : Each running pipeline's type, whether it mutates data, and its receivers, processors, and exporters. It shows composition, not throughput counters; use the internal metrics (Section 13.1) for counts.
http://<host>:55679/debug/extensionz : The active extensions.
http://<host>:55679/debug/featurez : The feature gates and their current status.
http://<host>:55679/debug/tracez : Spans created inside the Collector, grouped into latency buckets (such as 0–10 µs, 10–100 µs, up to 1 minute) with sampled error spans. extensions:
zpages:
- endpoint: 0.0.0.0:55679
- 4. memory_ballast (DEPRECATED) vs Modern GOMEMLIMIT
Older configurations still contain the historical memory_ballast extension, so know its modern replacement:
The Historical Problem : In Go runtimes prior to Go 1.19, the garbage collector (GC) triggered whenever the live heap doubled in size relative to the previous GC baseline. In a Collector with a small live heap (e.g., 50MB), allocating another 50MB would trigger a GC cycle, causing frequent CPU thrashing under high telemetry ingestion rates.
The Ballast Hack : The memory_ballast extension pre-allocated a large, contiguous virtual memory slice (e.g., 1GB) on startup that was never written to. This artificially raised the GC baseline, delaying GC cycles until an additional 1GB was allocated and drastically reducing CPU usage.
Modern Deprecation : Go 1.19 introduced the native GOMEMLIMIT environment variable. With GOMEMLIMIT , the Go runtime scheduler monitors the exact container memory boundary and dynamically tunes GC pacing to maximize throughput while preventing out-of-memory crashes. Consequently, the memory_ballast extension was deprecated and then removed in Collector v0.109.0 .
Important
memory_ballast is gone. Modern deployments achieve memory stability with the GOMEMLIMIT environment variable, which the memory_limiter README recommends setting to about 80% of the Collector's hard memory limit (e.g., GOMEMLIMIT=1638MiB for a 2 GiB container), together with the memory_limiter processor.
Authentication Extensions
When Collectors are deployed as shared gateways or multi-tenant proxies, they must authenticate incoming telemetry requests from microservices and authenticate outgoing requests to remote backends. Authentication extensions provide this security capability by attaching directly to receivers and exporters. [Client Microservice]
- |
- | (HTTP/gRPC with 'Authorization: Bearer <JWT>')
- v
- [otlp receiver] <==== Validates Token ====> [oidc extension]
- | |
- | (Approved Telemetry) v
- [Data Pipeline] [Identity Provider (IdP)]
- |
- v
- [otlp exporter] <==== Injects Basic Auth === [basicauth extension]
- |
- v (HTTP with 'Authorization: Basic <Creds>')
- [Remote Secure Backend]
- 1. oidc (OIDC Authenticator)
The oidc extension (from Contrib) validates incoming Bearer JWT tokens against an OpenID Connect (OIDC) identity provider (such as Keycloak, Okta, Microsoft Entra ID, or Google Cloud IAM). It verifies token signatures, expiration timestamps ( exp ), allowed issuers ( iss ), and target audience claims ( aud ). extensions:
oidc:
- issuer_url: https://auth.production.example.com
- audience: otel-collector-gateway
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
auth:
authenticator: oidc # Binds OIDC validation to OTLP gRPC
http:
endpoint: 0.0.0.0:4318
auth:
authenticator: oidc # Binds OIDC validation to OTLP HTTP
service:
- extensions: [oidc]
- 2. basicauth and bearertokenauth
basicauth : Supports HTTP Basic authentication ( username and password ). It can function as a server authenticator on receivers (validating incoming credentials) or as a client authenticator on exporters (injecting credentials into outgoing requests).
bearertokenauth : Injects static or file-based Bearer tokens into outgoing exporter headers, commonly used for authenticating to SaaS observability backends.
Top Collector Extensions Summary Table
The following table summarizes the most common OpenTelemetry Collector extensions, their default ports, primary endpoints, and production best practices:
Extension Name Primary Purpose Default Port Primary Endpoints Production Best Practice
health_check Liveness and readiness probes 13133 / , /healthz Mandatory in Kubernetes; configure readinessProbe to prevent traffic drops during rollout.
pprof Go runtime CPU/memory profiling 1777 /debug/pprof/ Restrict to localhost or internal cluster network; never expose to public ingress.
zpages In-process pipeline & trace diagnostics 55679 /debug/pipelinez , /debug/tracez Enable in staging or edge gateways for immediate visual debugging without external APM.
oidc Validates JWT tokens against OIDC IdP N/A (In-memory) Ingress auth handler Enforce on internet-facing or cross-team gateway Collectors for zero-trust security.
basicauth HTTP Basic auth validation / injection N/A (In-memory) Ingress/Egress auth Use with TLS encryption when connecting to legacy telemetry ingest proxies.
bearertokenauth Static bearer token injection N/A (In-memory) Egress auth handler Store tokens in Kubernetes Secrets and reference via environment variable substitution.
memory_ballast Historical Go GC tuning (Removed in v0.109.0) N/A (In-memory) None Do not use in modern deployments; replace with GOMEMLIMIT environment variable.