OpenTelemetry (gRPC) Input

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

Input Type

This Input is a listener input type. See Inputs to learn about Input types.

Configuration Option	Description
Global	Select this check box to enable the input on all Graylog nodes, or keep it unchecked to enable the input on a specific node.
Node	Select the Graylog node this input will be associated with.
Title	Assign a unique title to the input. Example: OpTel Input for XYZ Source.
Bind Address	Enter an IP address for this input to listen on. The source system/data sends logs to this IP address/Input.
Port	By default, the input listens on 0.0.0.0, making it accessible on all network interfaces, and uses port 4317, which aligns with OpenTelemetry’s default for gRPC-based log ingestion.
Maximum size of gRPC inbound messages	The maximum message size of the message. The default value of 4194304 bytes (approximately 4 MB) should suffice but can be modified depending on message length.
Allow Throttling (checkbox)	If enabled, the input temporarily stops reading new messages if Graylog’s internal processing queue reaches its limit. Throttling prevents excessive memory usage and ensures system stability, particularly in high-throughput environments. To ensure that log data is not lost, implement appropriate retry behavior. The OpenTelemetry SDK and collector generally support retry mechanisms for transient failures, but you should verify that their configuration aligns with expected backoff and retry policies.
Required bearer token (optional)	In addition to TLS or as an alternative authentication method, the input supports Bearer Token Authentication. When a required Bearer Token is defined, all clients must include this token in the authorization header of their requests. This method allows for access control without requiring client-side certificates.
Allow Insecure Connections (checkbox)	Disable TLS encryption to allow insecure connections to the server.
TLS Server Certificate Chain (optional)	TLS encryption can be enabled to protect log data in transit. To activate TLS, you must provide a TLS Server Certificate Chain, which includes a PEM-encoded certificate used to authenticate the input.
TLS Server Private Key (optional)	This method is required to support encrypted communication. If the certificate is signed by a trusted Certificate Authority (CA), clients can establish secure connections without further configuration.
TLS Client Certificate Chain (optional)	For stronger authentication, mutual TLS (mTLS) can be enabled by specifying a TLS Client Certificate Chain. This method ensures that only clients with valid certificates issued by a trusted authority can send logs to Graylog. If mTLS is configured, the input rejects connections from unauthorized clients.
Override source (optional)	By default, the source is a hostname derived from the received packet. You can override the default value with a custom string. This option allows you to optimize the source for your specific needs.

Transport Layer Security (TLS)

The OpenTelemetry (gRPC) input offers a variety of authentication and encryption options, which can be used individually or combined for enhanced protection. This flexibility allows you to tailor security settings to your needs. You can:

• Use TLS only, where the data is encrypted but no client authentication is enforced.

• Enable mTLS, ensuring that only trusted clients with valid certificates can connect.

• Use Bearer Token Authentication as an alternative to mTLS, requiring clients to authenticate via a token.

Mapping OpenTelemetry Log Fields to Graylog Fields

Once logs are received, Graylog maps key OpenTelemetry log fields to its internal schema for efficient indexing and querying. Because Graylog does not support nested fields in messages, the structure of the incoming log signals, as specified in the OpenTelemetry Protobuf Specification, cannot be mapped exactly to Graylog log messages. When mapping OpenTelemetry logs to Graylog messages, a number of rules are applied.

Hint: As a general rule, Graylog automatically replaces dots (.) in incoming message field names with underscores (_).

The following sections highlight how OpenTelemetry log messages are translated into Graylog messages.

Core Graylog Message Fields Mapping

These fields represent how core Graylog message fields are mapped from incoming OpenTelemetry log records.

• source: The address of the remote party that initiated the connection to the input.
  
  

• timestamp: Uses time_unix_nano from OpenTelemetry logs if available, otherwise observed_time_unix_nano, or the received timestamp of the record at the input as a fallback.
  
  

• message: Content of the OpenTelemetry log record body field.

First-Level Field Mapping

OpenTelemetry Field	Graylog Field
trace_id	otel_trace_id
span_id	otel_span_id
flags	otel_trace_flags
severity_text	otel_severity_text
severity_number	otel_severity_number
time_unix_nano	otel_time_unix_nano
observed_time_unix_nano	otel_observed_time_unix_nano

Resource and Attributes Mapping

• Resource Attributes: Prefixed with otel_resource_attributes_ and converted to Graylog fields.

• Resource Schema URL: Mapped to otel_resource_schema_url.

• Log Attributes: Prefixed with otel_attributes_.

• Log Schema URL: Mapped to otel_schema_url.

• Instrumentation Scope:

• otel_scope_name

• otel_scope_version

• otel_scope_attributes_*

Value Handling

• Primitive Types (string, boolean, integer, double): Directly converted.

• Bytes: Base64 encoded.

• Lists:

  • Single-type primitives: Converted to a list.

  • Mixed primitives: Converted to a list of strings.

  • Nested arrays/maps: Serialized as JSON.

• Maps: Flattened into individual fields, using _ as a separator.

Considerations and Limitations

While this input enables Graylog’s support for OpenTelemetry, there are a few important considerations to keep in mind. First, only log data is supported. Metrics and traces transmitted over OTLP/gRPC are not ingested by this input. Additionally, OTLP over HTTP is not supported; the input exclusively accepts data over the gRPC transport. If you are running Graylog behind a load balancer, it is essential to ensure that the required ports are open and that TLS/mTLS configurations are properly forwarded to maintain secure and uninterrupted communication.

Next Steps

After you complete input setup, visit Input Diagnosis for testing and validation of the new input. Use this functionality to help troubleshoot any connection issues.