OpenTelemetry (gRPC) Input

The OpenTelemetry Google Remote Procedure Call (gRPC) input allows Graylog to ingest log data from OpenTelemetry-instrumented applications and services using the OpenTelemetry Protocol (OTLP) over gRPC.

By using this input, you can receive structured OpenTelemetry logs, map relevant fields to Graylog’s internal schema, and apply search, analysis, and alerting capabilities to their telemetry data.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

  • To send OpenTelemetry logs to Graylog, the Graylog server needs to be configured as a backend for logs. The following configuration snippets provide examples for configuring the OpenTelemetry Collector to send logs to Graylog; however, they do not represent a complete configuration of the collector.

    • Insecure, unauthenticated log exporting.

      Warning: This configuration is insecure and not recommended for production. Only use for testing!

      Copy 
      exporters:
        otlp/graylog:
          endpoint: "graylog.test:4317"
          tls:
            insecure: true

      service:
        pipelines:
          logs:
            exporters: [debug, otlp/graylog]

    • TLS, Bearer Token Authentication

      Copy 
      extensions:
        bearertokenauth/withscheme:
          scheme: "Bearer"
          token: "kst40ngmpq22oqej9ugughgh48i81n0vbm0tbuqnqk0oop5jl0h"

      exporters:
        otlp/graylog:
          endpoint: "graylog.test:4317"
          auth:
            authenticator: bearertokenauth/withscheme
          tls:
            ca_file: /tls/rootCA.pem

      service:
        extensions: [bearertokenauth/withscheme]
        pipelines:
          logs:
            exporters: [debug, otlp/graylog]

    • TLS, unauthenticated

      Copy 
      exporters:
        otlp/graylog:
          endpoint: "graylog.test:4317"
          tls:
            ca_file: /tls/rootCA.pem

      service:
        pipelines:
          logs:
            exporters: [debug, otlp/graylog]

    • Mutual TLS

Copy 
exporters:
  otlp/graylog:
    endpoint: "graylog.test:4317"
    tls:
      ca_file: /tls/rootCA.pem
      cert_file: /tls/client.pem
      key_file: /tls/client-key.pem

service:
  pipelines:
    logs:
      exporters: [debug, otlp/graylog]

Transport Layer Security (TLS)

To ensure secure communication, the OpenTelemetry (gRPC) input provides multiple authentication and encryption mechanisms, which can be used separately or combined for additional security. The OpenTelemetry (gRPC) Input provides flexibility in security configurations. It is possible to:

  • 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.

Graylog Input Configuration

When launching this input from the Graylog Inputs tab, configure the following field values:

  • Node: The node setting determines whether the input should run on a specific Graylog node or be available globally across all nodes. Click the Global checkbox to run the input across all nodes.

  • Title: Assign a title to the input for easy identification.

  • 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.

    Hint: The TLS-related settings that follow ensure that valid sources can send messages to the input securely.

  • 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.

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.