OpenTelemetry Protocol (OTLP)

Network

Synopsis

Receives OpenTelemetry logs, metrics, and traces over OTLP/gRPC (default port 4317) and OTLP/HTTP (default port 4318) concurrently. Supports per-signal and per-transport enable/disable toggles, basic and bearer authentication, server TLS and mutual TLS, and configurable worker fan-out via SO_REUSEPORT.

To forward telemetry to an external OTLP-compatible receiver instead, see the OTLP target.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: otel
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    otlp_grpc_status: <boolean>
    otlp_grpc_port: <numeric>
    otlp_http_status: <boolean>
    otlp_http_port: <numeric>
    otlp_logs_status: <boolean>
    otlp_metrics_status: <boolean>
    otlp_traces_status: <boolean>
    otlp_logs_http_path: <string>
    otlp_metrics_http_path: <string>
    otlp_traces_http_path: <string>
    otlp_max_recv_msg_mib: <numeric>
    authentication:
      type: <string>
      username: <string>
      password: <string>
    tokens: <string[]>
    tls:
      status: <boolean>
      cert_name: <string>
      key_name: <string>
      min_version: <string>
      insecure_skip_verify: <boolean>
      client_ca_name: <string>
      client_auth_required: <boolean>
    reuse: <boolean>
    workers: <numeric>
    timezone: <string>
    otel_resource_attributes: <string>

Configuration

Device

Field	Required	Default	Description
id	Y	-	Unique numeric identifier
name	Y	-	Device name
description	N	-	Optional description
type	Y	-	Must be otel
tags	N	-	Optional tags
pipelines	N	-	Optional pre-processor pipelines
status	N	true	Enable/disable the device
address	N	0.0.0.0	Listen address applied to both transports

Transports

Both transports run concurrently and are individually toggleable. At least one transport must be enabled. The gRPC and HTTP ports must be distinct.

gRPC

Field	Required	Default	Description
otlp_grpc_status	N	true	Enable the OTLP/gRPC endpoint
otlp_grpc_port	N	4317	gRPC listen port

HTTP

Field	Required	Default	Description
otlp_http_status	N	true	Enable the OTLP/HTTP endpoint
otlp_http_port	N	4318	HTTP listen port

Signals

Logs, metrics, and traces are individually toggleable. At least one signal must be enabled. HTTP paths apply to the OTLP/HTTP transport only.

Field	Required	Default	Description
otlp_logs_status	N	true	Enable the logs signal
otlp_metrics_status	N	true	Enable the metrics signal
otlp_traces_status	N	true	Enable the traces signal
otlp_logs_http_path	N	/v1/logs	HTTP path for the logs signal
otlp_metrics_http_path	N	/v1/metrics	HTTP path for the metrics signal
otlp_traces_http_path	N	/v1/traces	HTTP path for the traces signal

Authentication

An optional header/metadata authentication layer applied identically to both transports. none disables authentication enforcement.

Field	Required	Default	Description
authentication.type	N	none	Auth scheme: none, basic, or bearer
authentication.username	Y*	-	Basic-auth username
authentication.password	Y*	-	Basic-auth password
tokens	Y**	-	Array of accepted bearer tokens (bare or Bearer-prefixed)

* = Required when authentication.type is basic.

** = Required when authentication.type is bearer.

TLS

Field	Required	Default	Description
tls.status	N	false	Enable TLS for both transports
tls.cert_name	Y*	cert.pem	Server certificate. File name (resolved relative to the service root) or inline PEM content (when the value starts with -----BEGIN).
tls.key_name	Y*	key.pem	Server private key. Same value semantics as tls.cert_name.
tls.min_version	N	-	Minimum accepted TLS version (e.g., 1.2, 1.3)
tls.insecure_skip_verify	N	false	Skip peer certificate verification
tls.client_ca_name	N	-	CA bundle used to verify client certificates (mTLS)
tls.client_auth_required	N**	false	Require and verify a client certificate (mTLS)

* = tls.cert_name and tls.key_name are required when tls.status is true.

** = tls.client_auth_required requires tls.client_ca_name to be set.

Performance and Advanced

Field	Required	Default	Description
otlp_max_recv_msg_mib	N	4	Maximum per-RPC gRPC receive size in MiB (floored at 1). Applies to gRPC only.
reuse	N	true	Enable socket address reuse (SO_REUSEPORT) for worker fan-out
workers	N	CPU cores	Concurrent processing workers per transport (default: min(NumCPU, 8))
timezone	N	-	Per-device timestamp offset adjustment
otel_resource_attributes	N	-	Comma-separated key=value resource attributes (currently a no-op — see warning below)

warning

otel_resource_attributes is parsed and validated but is currently a no-op — the raw-bytes ingest path does not apply resource-attribute upserts. Setting it emits a startup warning and does not modify emitted records.

Details

Transports and Ports

The gRPC endpoint (default port 4317) and HTTP endpoint (default port 4318) start concurrently. Each is independently toggleable via otlp_grpc_status and otlp_http_status. Disabling both transports is rejected at config load. The two transports must bind distinct ports — sharing a port between gRPC and HTTP is not supported.

The gRPC listener negotiates h2 (ALPN) and the HTTP listener uses http/1.1. A top-level port or protocol field on the device is forced internally per-transport and has no effect; use otlp_grpc_port and otlp_http_port to set ports.

Signals

Logs, metrics, and traces are individually toggleable. Disabling all three signals is rejected at config load. The per-signal HTTP paths (otlp_logs_http_path, otlp_metrics_http_path, otlp_traces_http_path) apply to the OTLP/HTTP transport; gRPC routes by OTLP service method and the path fields have no effect on it.

Authentication

Three schemes are available: none (open, no credentials required), basic (HTTP Basic Auth using authentication.username and authentication.password), and bearer (token matching against the tokens array). Bearer token matching accepts both bare tokens and Bearer -prefixed values. The authentication layer is applied identically to both transports — gRPC metadata and HTTP headers are checked with the same logic.

TLS and mTLS

Server TLS is enabled via tls.status together with tls.cert_name and tls.key_name. Mutual TLS is configured independently by setting tls.client_ca_name (CA bundle for client certificate verification) and tls.client_auth_required: true. The mTLS layer operates independently of the header/token authentication layer — both can be active simultaneously.

Message Size Limits

otlp_max_recv_msg_mib caps the per-RPC payload size on the gRPC transport (value is converted from MiB to bytes; floored at 1 MiB). The HTTP transport is not bound by this setting.

Performance and Workers

workers sets the per-transport concurrent processing fan-out. The default is min(NumCPU, 8). reuse enables SO_REUSEPORT so multiple workers can accept on the same socket address without lock contention. Both settings apply to each transport independently.

Configuration Reload

Changing any of the following restarts the listener: transport enable flags, port assignments, signal enable flags, HTTP signal paths, TLS material, authentication credentials, worker count, or otlp_max_recv_msg_mib.

note

The device type for this listener is otel, not otlp. The OTLP target uses type: otlp; this device uses type: otel. Using the wrong type string will cause the device to fail to load.

Examples

The following are commonly used configuration types.

Basic

A minimal OTLP device using default ports and all signals enabled:

Creating an OTLP listener accepting logs, metrics, and traces on default ports...

devices: - id: 1 name: basic_otel type: otel

Logs-Only on Custom Ports

Receiving only log signals on non-default gRPC and HTTP ports:

Restricting to logs and moving transports off the default OTLP ports...

devices: - id: 2 name: logs_only_otel type: otel properties: otlp_grpc_port: 14317 otlp_http_port: 14318 otlp_metrics_status: false otlp_traces_status: false

HTTP-Only with Custom Paths

Disabling gRPC and overriding the default OTLP/HTTP signal paths:

Running only the HTTP transport with application-specific path prefixes...

devices: - id: 3 name: http_only_otel type: otel properties: otlp_grpc_status: false otlp_logs_http_path: /ingest/v1/logs otlp_metrics_http_path: /ingest/v1/metrics otlp_traces_http_path: /ingest/v1/traces

TLS

Enabling server-side TLS on both transports:

Securing the OTLP listener with a server certificate and minimum TLS version...

devices: - id: 4 name: tls_otel type: otel properties: tls: status: true cert_name: otel.crt key_name: otel.key min_version: "1.2"

mTLS with Bearer Authentication

Requiring mutual TLS client certificates and bearer token authentication:

Combining mTLS client verification with bearer token enforcement for zero-trust ingestion...

devices: - id: 5 name: mtls_bearer_otel type: otel properties: tls: status: true cert_name: otel.crt key_name: otel.key min_version: "1.3" client_ca_name: ca-bundle.pem client_auth_required: true authentication: type: bearer tokens: - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 - prod-collector-token-abc123

High-Volume Tuning

Optimizing for large telemetry volumes with increased workers, message size, and pipeline pre-processing:

Scaling worker fan-out and gRPC message limits for high-throughput environments...

devices: - id: 6 name: highvol_otel type: otel pipelines: - otel_normalizer - resource_enricher properties: workers: 16 reuse: true otlp_max_recv_msg_mib: 32