OpenTelemetry Collector (otel-collector)
Receives OTLP traces, metrics and logs, tags them with the cluster resource attributes and exports them to OpenSearch or the Elasticsearch of the client (logs), Jaeger (traces), Prometheus and optionally Opik (LLM traces).
Generated from catalog/services/otel-collector.yaml: do not edit by hand.
Summary
| Version | 0.130.0 |
| Use | install and configure, configure and connect |
| Layer | functional (AI catalog) |
| Category | Observability |
| Installation methods | binary, podman |
| External connection | no |
| Sandbox only | no |
Licence
| SPDX identifier | Apache-2.0 |
| Licence policy | core licence (MIT or Apache-2.0) |
| Licence exception | - |
| Platform component | otel-collector |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
| Kind | Package | Version | Licence | Details |
|---|---|---|---|---|
| container image | docker.io/otel/opentelemetry-collector-contrib | 0.130.0 | Apache-2.0 | image key otelcol-contrib, used by otel-collector, digest sha256:867d1074c2f750936fb9358ec9eefa009308053cf156b2c7ca1761ba5ef78452 |
| binary archive | otelcol-contrib_0.130.0_linux_amd64.tar.gz | 0.130.0 | Apache-2.0 | https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.130.0/otelcol-contrib_0.130.0_linux_amd64.tar.gz, x86_64, checksum sha256 |
Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|---|---|
binary | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64 (architecture of the artifacts of the descriptor) |
podman | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64, aarch64 (not restricted by the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
The descriptor declares no host preflight check.
Programs the commands and checks of the service start on the host, outside the managed roots: add them to allowed_commands of the agent (see Security of the Navin agent), else the agent refuses them with command_not_allowed: /usr/bin/curl.
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|---|---|---|
otel-collector | otlp_grpc | 4317/tcp | yes |
otel-collector | otlp_http | 4318/tcp | yes |
otel-collector | metrics | 8888/tcp | yes |
otel-collector | health | 13133/tcp | no |
otel-collector | zpages | 55679/tcp | no |
Services and connections needed
opensearch:opensearch(optional).elasticsearch:elasticsearch(optional).jaeger:jaeger(optional).prometheus:prometheus(optional).llm_tracing:opik(optional).
Details and resolution: see Dependencies.
Installation methods and modes
| Method | Default | What the method uses |
|---|---|---|
binary | yes | the binary archives of the descriptor, unpacked under the service directory |
podman | - | the container images of the descriptor, run by Podman under systemd |
Components
| Component | Kind | Installation methods | Ports |
|---|---|---|---|
Collector (otel-collector) | master | binary, podman | 4317/tcp, 4318/tcp, 8888/tcp, 13133/tcp, 55679/tcp |
Agent (agent) (default)
One collector on each host sending to the backends.
What the mode deploys:
| Component | Placement |
|---|---|
otel-collector | min 1, recommended 3 |
Gateway (gateway)
Replicated stateless collectors behind the load balancer.
What the mode deploys:
| Component | Placement |
|---|---|
otel-collector | min 2, recommended 2 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select OpenTelemetry Collector. The card shows the licence
Apache-2.0and the dependencies the installation needs. Pick the Method amongbinary,podman(defaultbinary). -
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode:
agent(default),gateway. Each mode deploys the components listed in Installation methods and modes. -
Bind the dependencies. On the Bindings step, choose for each dependency (
opensearch,elasticsearch,jaeger,prometheus,llm_tracing) Install with the platform or Use an existing connection; an optional dependency can stay on No binding. -
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
Connect an existing service
| Schemes | https, http |
| Default port | 4317 |
| Authentication | optional |
| Health check | health_url + / |
| Authentication method | Fields | Description |
|---|---|---|
none | - | OTLP receiver without an authenticator. |
bearer | token | bearertokenauth extension of the OTLP receiver: the collector checks the token only when data arrives, the Manager cannot test it beforehand. |
basic | username, password | basicauth extension (htpasswd) of the OTLP receiver, checked by the collector when data arrives only. |
Official documentation: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/bearertokenauthextension
| Field | Type | Default | Description | Notes |
|---|---|---|---|---|
Health endpoint URL (health_url) | url | - | Health endpoint URL of the existing service. | required |
High availability
| Cluster | replicas (replication) |
| High availability | external (external) |
| Failover | load balancer (load-balancer) |
| Replication | none (none) |
| Quorum | none (none) |
| Discovery | none (none) |
| Entry point | load balancer (load-balancer) |
| Official documentation | https://opentelemetry.io/docs/collector/deploy/gateway/ |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|---|---|---|---|---|
agent | ha (ha) | per host (per-host) | - | - | One agent on every host: each host covers itself, the loss of a host only loses its own coverage. |
gateway | ha (ha) | active-active (active-active) | - | 2 | Replicated stateless collectors behind the load balancer. |
Notes
- A collector keeps the data in progress in memory: a crash loses what was not yet exported. The backends (OpenSearch, Jaeger, Prometheus) need their own high availability.
Configuration parameters
General
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
OTLP gRPC port (grpc_port) | port | 4317 | - | no | no | no | Port of the OTLP gRPC receiver. |
OTLP HTTP port (http_port) | port | 4318 | - | no | no | no | Port of the OTLP HTTP receiver. |
Self metrics port (metrics_port) | port | 8888 | - | no | no | no | Port of the collector own metrics. |
zPages port (zpages_port) | port | 55679 | - | no | no | no | Port of the zPages debug pages, bound to localhost. |
Health port (health_port) | port | 13133 | - | no | no | no | Port of the health check extension. |
TLS (tls_enabled) | bool | false | - | no | no | yes | Serve the OTLP gRPC and HTTP receivers and the own metrics over TLS with a certificate issued by the manager CA. |
Internal metrics port (self_metrics_port) | port | 4319 | - | no | no | no | Loopback port receiving the collector own metrics when TLS is on, before they are served in TLS on the self metrics port (the built-in Prometheus reader has no TLS). (advanced) |
Memory limit (memory_limit_mib) | int | 1024 | min 128, max 65536, MiB | no | no | no | Limit of the memory_limiter processor. |
Environment (environment) | string | production | - | no | no | no | Value of deployment.environment added by the resource processor. |
Dependencies
For each active dependency the Manager takes the first of: the binding chosen in the wizard; a service of the same installation that provides it; a service already installed in the cluster; the only connection of the expected type. Otherwise an optional dependency stays unbound, and a required one is added to the installation in its default mode (the column below names the catalog service added).
| Binding | Provided by | Connection type | Endpoint | Optional | When nothing is bound | Description |
|---|---|---|---|---|---|---|
opensearch | opensearch | - | http | yes | stays unbound (optional) | OpenSearch receiving the logs (index eai-logs-*). |
elasticsearch | - (versions >= 8.12, < 9) | elasticsearch | - | yes | stays unbound (optional) | Elasticsearch the client already runs, declared as a connection and never installed by Navin: it receives the logs in the data stream logs-eai.otel-default (OpenTelemetry mapping, Elasticsearch 8.12 or a later 8.x), next to OpenSearch when both are bound. |
jaeger | jaeger | - | otlp_grpc | yes | stays unbound (optional) | Jaeger receiving the traces (OTLP gRPC). |
prometheus | prometheus | - | http | yes | stays unbound (optional) | Prometheus receiving the metrics (remote write). |
llm_tracing | opik | - | api | yes | stays unbound (optional) | Opik backend receiving the LLM traces (OTLP over HTTP, /v1/private/otel). |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|---|---|---|---|---|---|---|---|
otlp_grpc | grpc | otel-collector | 4317 (grpc_port) | - | tls_enabled | tls | - | - |
otlp_http | http | otel-collector | 4318 (http_port) | - | tls_enabled | - | - | - |
Commands
| Command | Component | Target | Description |
|---|---|---|---|
Pipeline status (zPages) (zpages) | otel-collector | every host | Reads the pipelines page of the zPages extension. |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|---|---|
otel-collector | HTTP http://127.0.0.1:{{ config.health_port }}/ | Expected 200; 30 retries; interval 1 s; timeout 3 s |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|---|---|---|---|
grpc_free | port_free {"param": "grpc_port"} | port 4317 free on the host | blocking | every component |
http_free | port_free {"param": "http_port"} | port 4318 free on the host | blocking | every component |
Uninstall
Paths removed when the data is purged: {{ paths.log }}.
Quick links
- zPages (from the host only):
http://127.0.0.1:{{ config.zpages_port }}/debug/servicez
Upstream documentation
- Homepage: https://opentelemetry.io
- Source: https://github.com/open-telemetry/opentelemetry-collector-contrib
- High availability: https://opentelemetry.io/docs/collector/deploy/gateway/
- Authentication: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/bearertokenauthextension