Documentation Grafana Alloy Reference Components otelcol otelcol.exporter.syslog

otelcol.exporter.syslog

Public preview: This is a public preview component. Public preview components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case. To enable and use a public preview component, you must set the stability.level flag to public-preview or below.

otelcol.exporter.syslog accepts logs from other otelcol components and writes them over the network using the syslog protocol. It supports syslog protocols RFC5424 and RFC3164 and can send data over TCP or UDP.

You can specify multiple otelcol.exporter.syslog components by giving them different labels.

Usage

alloy Copy

otelcol.exporter.syslog "LABEL" {
  endpoint = "HOST"
}

Supported Attributes

The exporter creates one syslog message for each log record based on the following attributes of the log record. If an attribute is missing, the default value is used. The log’s timestamp field is used for the syslog message’s time. RFC3164 only supports a subset of the attributes supported by RFC5424, and the default values aren’t the same between the two protocols. Refer to the OpenTelemetry documentation for the exporter for more details.

Arguments

You can use the following arguments with otelcol.exporter.syslog:

The network argument specifies if the syslog endpoint is using the TCP or UDP protocol. network must be one of tcp, udp.

The protocol argument specifies the syslog format supported by the endpoint. protocol must be one of rfc5424, rfc3164.

Blocks

You can use the following blocks with otelcol.exporter.syslog:

debug_metrics

The debug_metrics block configures the metrics that this component generates to monitor its state.

The following arguments are supported:

disable_high_cardinality_metrics is the Alloy equivalent to the telemetry.disableHighCardinalityMetrics feature gate in the OpenTelemetry Collector. It removes attributes that could cause high cardinality metrics. For example, attributes with IP addresses and port numbers in metrics about HTTP and gRPC connections are removed.

retry_on_failure

The retry_on_failure block configures how failed requests to the syslog server are retried.

The following arguments are supported:

When enabled is true, failed batches are retried after a given interval. The initial_interval argument specifies how long to wait before the first retry attempt. If requests continue to fail, the time to wait before retrying increases by the factor specified by the multiplier argument, which must be greater than 1.0. The max_interval argument specifies the upper bound of how long to wait between retries.

The randomization_factor argument is useful for adding jitter between retrying Alloy instances. If randomization_factor is greater than 0, the wait time before retries is multiplied by a random factor in the range [ I - randomization_factor * I, I + randomization_factor * I], where I is the current interval.

If a batch hasn’t been sent successfully, it’s discarded after the time specified by max_elapsed_time elapses. If max_elapsed_time is set to "0s", failed requests are retried forever until they succeed.

sending_queue

The sending_queue block configures an in-memory buffer of batches before data is sent to the syslog server.

The following arguments are supported:

The blocking argument is deprecated in favor of the block_on_overflow argument.

When block_on_overflow is true, the component will wait for space. Otherwise, operations will immediately return a retryable error.

When enabled is true, data is first written to an in-memory buffer before sending it to the configured server. Batches sent to the component’s input exported field are added to the buffer as long as the number of unsent batches doesn’t exceed the configured queue_size.

queue_size determines how long an endpoint outage is tolerated. Assuming 100 requests/second, the default queue size 1000 provides about 10 seconds of outage tolerance. To calculate the correct value for queue_size, multiply the average number of outgoing requests per second by the time in seconds that outages are tolerated. A very high value can cause Out Of Memory (OOM) kills.

The sizer argument could be set to:

• requests: number of incoming batches of metrics, logs, traces (the most performant option).
• items: number of the smallest parts of each signal (spans, metric data points, log records).
• bytes: the size of serialized data in bytes (the least performant option).

The num_consumers argument controls how many readers read from the buffer and send data in parallel. Larger values of num_consumers allow data to be sent more quickly at the expense of increased network traffic.

If an otelcol.storage.* component is configured and provided in the queue’s storage argument, the queue uses the provided storage extension to provide a persistent queue and the queue is no longer stored in memory. Any data persisted will be processed on startup if Alloy is killed or restarted. Refer to the exporterhelper documentation in the OpenTelemetry Collector repository for more details.

tls

The tls block configures TLS settings used for a connection to a TCP syslog server.

The following arguments are supported:

If the server doesn’t support TLS, you must set the insecure argument to true.

To disable tls for connections to the server, set the insecure argument to true.

If you set reload_interval to "0s", the certificate never reloaded.

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

• ca_pem and ca_file
• cert_pem and cert_file
• key_pem and key_file

If cipher_suites is left blank, a safe default list is used. Refer to the Go TLS documentation for a list of supported cipher suites.

The curve_preferences argument determines the set of elliptic curves to prefer during a handshake in preference order. If not provided, a default list is used. The set of elliptic curves available are X25519, P521, P256, and P384.

Exported fields

The following fields are exported and can be referenced by other components:

input accepts otelcol.Consumer data for logs. Other telemetry signals are ignored.

Component health

otelcol.exporter.syslog is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.syslog doesn’t expose any component-specific debug information.

Examples

TCP endpoint without TLS

This example creates an exporter to send data to a syslog server expecting RFC5424-compliant messages over TCP without TLS:

alloy Copy

otelcol.exporter.syslog "default" {
  endpoint = "localhost"
  tls {
      insecure             = true
      insecure_skip_verify = true
  }
}

Use the otelcol.processor.transform component to format logs from loki.source.syslog

This example shows one of the methods for annotating your Loki messages into the format expected by the exporter using a otelcol.receiver.loki component in addition to the otelcol.processor.transform component. This example assumes that the log messages being parsed have come from a loki.source.syslog component. This is just an example of some of the techniques that can be applied, and not a fully functioning example for a specific incoming log.

alloy Copy

otelcol.receiver.loki "default" {
  output {
    logs = [otelcol.processor.transform.syslog.input]
  }
}

otelcol.processor.transform "syslog" {
  error_mode = "ignore"

  log_statements {
    context = "log"

    statements = [
      `set(attributes["message"], attributes["__syslog_message"])`,
      `set(attributes["appname"], attributes["__syslog_appname"])`,
      `set(attributes["hostname"], attributes["__syslog_hostname"])`,

      // To set structured data you can chain index ([]) operations.
      `set(attributes["structured_data"]["auth@32473"]["user"], attributes["__syslog_message_sd_auth_32473_user"])`,
      `set(attributes["structured_data"]["auth@32473"]["user_host"], attributes["__syslog_message_sd_auth_32473_user_host"])`,
      `set(attributes["structured_data"]["auth@32473"]["valid"], attributes["__syslog_message_sd_auth_32473_authenticated"])`,
    ]
  }

  output {
    metrics = []
    logs    = [otelcol.exporter.syslog.default.input]
    traces  = []
  }
}

Use the otelcol.processor.transform component to format OpenTelemetry logs

This example shows one of the methods for annotating your messages in the OpenTelemetry log format into the format expected by the exporter using an otelcol.processor.transform component. This example assumes that the log messages being parsed have come from another OpenTelemetry receiver in JSON format (or have been transformed to OpenTelemetry logs using an otelcol.receiver.loki component). This is just an example of some of the techniques that can be applied, and not a fully functioning example for a specific incoming log format.

alloy Copy

otelcol.processor.transform "syslog" {
  error_mode = "ignore"

  log_statements {
    context = "log"

    statements = [
      // Parse body as JSON and merge the resulting map with the cache map, ignoring non-json bodies.
      // cache is a field exposed by OTTL that is a temporary storage place for complex operations.
      `merge_maps(cache, ParseJSON(body), "upsert") where IsMatch(body, "^\\{")`,

      // Set some example syslog attributes using the values from a JSON message body
      // If the attribute doesn't exist in cache then nothing happens.
      `set(attributes["message"], cache["log"])`,
      `set(attributes["appname"], cache["application"])`,
      `set(attributes["hostname"], cache["source"])`,

      // To set structured data you can chain index ([]) operations.
      `set(attributes["structured_data"]["auth@32473"]["user"], attributes["user"])`,
      `set(attributes["structured_data"]["auth@32473"]["user_host"], cache["source"])`,
      `set(attributes["structured_data"]["auth@32473"]["valid"], cache["authenticated"])`,

      // Example priority setting, using facility 1 (user messages) and default to Info
      `set(attributes["priority"], 14)`,
      `set(attributes["priority"], 12) where severity_number == SEVERITY_NUMBER_WARN`,
      `set(attributes["priority"], 11) where severity_number == SEVERITY_NUMBER_ERROR`,
      `set(attributes["priority"], 10) where severity_number == SEVERITY_NUMBER_FATAL`,
    ]
  }

  output {
    metrics = []
    logs    = [otelcol.exporter.syslog.default.input]
    traces  = []
  }
}

Compatible components

otelcol.exporter.syslog has exports that can be consumed by the following components:

• Components that consume OpenTelemetry otelcol.Consumer