This is documentation for the next version of Alloy. For the latest stable release, go to the latest version.

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. The stability.level flag must be set to public-preview or below to use the component.

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 are not the same between the two protocols. Refer to the OpenTelemetry documentation for the exporter for more details.

Arguments

otelcol.exporter.syslog supports the following arguments:

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

The following blocks are supported inside the definition of otelcol.exporter.syslog:

tls block

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 reload_interval is set 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.

sending_queue block

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

The following arguments are supported:

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

retry_on_failure block

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.

debug_metrics block

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

level is the Alloy equivalent to the telemetry.metrics.level feature gate in the OpenTelemetry Collector. Possible values are "none", "basic", "normal" and "detailed".

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