|
| 1 | +--- |
| 2 | +canonical: https://grafana.com/docs/alloy/latest/reference/components/otelcol/otelcol.exporter.syslog/ |
| 3 | +description: Learn about otelcol.exporter.syslog |
| 4 | +title: otelcol.exporter.syslog |
| 5 | +--- |
| 6 | + |
| 7 | +# otelcol.exporter.syslog |
| 8 | + |
| 9 | +{{< docs/shared lookup="stability/public_preview.md" source="alloy" version="<ALLOY_VERSION>" >}} |
| 10 | + |
| 11 | +`otelcol.exporter.syslog` accepts logs from other `otelcol` components and writes them over the network using the syslog protocol. |
| 12 | +It supports syslog protocols [RFC5424][] and [RFC3164][] and can send data over `TCP` or `UDP`. |
| 13 | + |
| 14 | +{{< admonition type="note" >}} |
| 15 | +`otelcol.exporter.syslog` is a wrapper over the upstream OpenTelemetry Collector `syslog` exporter. |
| 16 | +Bug reports or feature requests will be redirected to the upstream repository, if necessary. |
| 17 | +{{< /admonition >}} |
| 18 | + |
| 19 | +You can specify multiple `otelcol.exporter.syslog` components by giving them different labels. |
| 20 | + |
| 21 | +[RFC5424]: https://www.rfc-editor.org/rfc/rfc5424 |
| 22 | +[RFC3164]: https://www.rfc-editor.org/rfc/rfc3164 |
| 23 | + |
| 24 | +## Usage |
| 25 | + |
| 26 | +```alloy |
| 27 | +otelcol.exporter.syslog "LABEL" { |
| 28 | + endpoint = "HOST" |
| 29 | +} |
| 30 | +``` |
| 31 | + |
| 32 | +### Supported Attributes |
| 33 | + |
| 34 | +The exporter creates one syslog message for each log record based on the following attributes of the log record. |
| 35 | +If an attribute is missing, the default value is used. The log's timestamp field is used for the syslog message's time. |
| 36 | +RFC3164 only supports a subset of the attributes supported by RFC5424, and the default values are not the same between |
| 37 | +the two protocols. Refer to the [OpenTelemetry documentation][upstream_readme] for the exporter for more details. |
| 38 | + |
| 39 | +| Attribute name | Type | RFC5424 Default value | RFC3164 supported | RFC3164 Default value |
| 40 | +| ----------------- | ------ | ---------------------- |------------------ | ---------------------- |
| 41 | +| `appname` | string | `-` | yes | empty string |
| 42 | +| `hostname` | string | `-` | yes | `-` |
| 43 | +| `message` | string | empty string | yes | empty string |
| 44 | +| `msg_id` | string | `-` | no | |
| 45 | +| `priority` | int | `165` | yes | `165` |
| 46 | +| `proc_id` | string | `-` | no | |
| 47 | +| `structured_data` | map | `-` | no | |
| 48 | +| `version` | int | `1` | no | |
| 49 | + |
| 50 | +[upstream_readme]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/<OTEL_VERSION>/exporter/syslogexporter |
| 51 | + |
| 52 | +## Arguments |
| 53 | + |
| 54 | +`otelcol.exporter.syslog` supports the following arguments: |
| 55 | + |
| 56 | +| Name | Type | Description | Default | Required | |
| 57 | +|------------------------|-----------|---------------------------------------------------------------------------|-----------------------------------|----------| |
| 58 | +| `endpoint` | `string` | The endpoint to send syslog formatted logs to. | | yes | |
| 59 | +| `network` | `string` | The type of network connection to use to send logs. | tcp | no | |
| 60 | +| `port` | `int` | The port where the syslog server accepts connections. | 514 | no | |
| 61 | +| `protocol` | `string` | The syslog protocol that the syslog server supports. | rfc5424 | no | |
| 62 | +| `enable_octet_counting`| `bool` | Whether to enable rfc6587 octet counting. | false | no | |
| 63 | +| `timeout` | `duration`| Time to wait before marking a request as failed. | 5s | no | |
| 64 | + |
| 65 | +The `network` argument specifies if the syslog endpoint is using the TCP or UDP protocol. |
| 66 | +`network` must be one of `tcp`, `udp` |
| 67 | + |
| 68 | +The `protocol` argument specifies the syslog format supported by the endpoint. |
| 69 | +`protocol` must be one of `rfc5424`, `rfc3164` |
| 70 | + |
| 71 | +## Blocks |
| 72 | + |
| 73 | +The following blocks are supported inside the definition of `otelcol.exporter.syslog`: |
| 74 | + |
| 75 | +| Hierarchy | Block | Description | Required | |
| 76 | +|------------------|----------------------|----------------------------------------------------------------------------|----------| |
| 77 | +| tls | [tls][] | Configures TLS for a TCP connection. | no | |
| 78 | +| sending_queue | [sending_queue][] | Configures batching of data before sending. | no | |
| 79 | +| retry_on_failure | [retry_on_failure][] | Configures retry mechanism for failed requests. | no | |
| 80 | +| debug_metrics | [debug_metrics][] | Configures the metrics that this component generates to monitor its state. | no | |
| 81 | + |
| 82 | +[tls]: #tls-block |
| 83 | +[sending_queue]: #sending_queue-block |
| 84 | +[retry_on_failure]: #retry_on_failure-block |
| 85 | +[debug_metrics]: #debug_metrics-block |
| 86 | + |
| 87 | +### tls block |
| 88 | + |
| 89 | +The `tls` block configures TLS settings used for a connection to a TCP syslog server. |
| 90 | + |
| 91 | +{{< docs/shared lookup="reference/components/otelcol-tls-client-block.md" source="alloy" version="<ALLOY_VERSION>" >}} |
| 92 | + |
| 93 | +### sending_queue block |
| 94 | + |
| 95 | +The `sending_queue` block configures an in-memory buffer of batches before data is sent to the syslog server. |
| 96 | + |
| 97 | +{{< docs/shared lookup="reference/components/otelcol-queue-block.md" source="alloy" version="<ALLOY_VERSION>" >}} |
| 98 | + |
| 99 | +### retry_on_failure block |
| 100 | + |
| 101 | +The `retry_on_failure` block configures how failed requests to the syslog server are retried. |
| 102 | + |
| 103 | +{{< docs/shared lookup="reference/components/otelcol-retry-block.md" source="alloy" version="<ALLOY_VERSION>" >}} |
| 104 | + |
| 105 | +### debug_metrics block |
| 106 | + |
| 107 | +{{< docs/shared lookup="reference/components/otelcol-debug-metrics-block.md" source="alloy" version="<ALLOY_VERSION>" >}} |
| 108 | + |
| 109 | +## Exported fields |
| 110 | + |
| 111 | +The following fields are exported and can be referenced by other components: |
| 112 | + |
| 113 | +| Name | Type | Description |
| 114 | +|--------|--------------------|----------------------------------------------------------------- |
| 115 | +|`input` | `otelcol.Consumer` | A value that other components can use to send telemetry data to. |
| 116 | + |
| 117 | +`input` accepts `otelcol.Consumer` data for logs. Other telemetry signals are ignored. |
| 118 | + |
| 119 | +## Component health |
| 120 | + |
| 121 | +`otelcol.exporter.syslog` is only reported as unhealthy if given an invalid configuration. |
| 122 | + |
| 123 | +## Debug information |
| 124 | + |
| 125 | +`otelcol.exporter.syslog` doesn't expose any component-specific debug information. |
| 126 | + |
| 127 | +## Examples |
| 128 | + |
| 129 | +### TCP endpoint without TLS |
| 130 | + |
| 131 | +This example creates an exporter to send data to a syslog server expecting RFC5424-compliant messages over TCP without TLS: |
| 132 | + |
| 133 | +```alloy |
| 134 | +otelcol.exporter.syslog "default" { |
| 135 | + endpoint = "localhost" |
| 136 | + tls { |
| 137 | + insecure = true |
| 138 | + insecure_skip_verify = true |
| 139 | + } |
| 140 | +} |
| 141 | +``` |
| 142 | + |
| 143 | +### Use the `otelcol.processor.transform` component to format logs from `loki.source.syslog` |
| 144 | + |
| 145 | +This example shows one of the methods for annotating your loki messages into the format expected |
| 146 | +by the exporter using a `otelcol.receiver.loki` component in addition to the `otelcol.processor.transform` |
| 147 | +component. This example assumes that the log messages being parsed have come from a `loki.source.syslog` |
| 148 | +component. This is just an example of some of the techniques that can be applied, and not a fully functioning |
| 149 | +example for a specific incoming log. |
| 150 | + |
| 151 | +```alloy |
| 152 | +otelcol.receiver.loki "default" { |
| 153 | + output { |
| 154 | + logs = [otelcol.processor.transform.syslog.input] |
| 155 | + } |
| 156 | +} |
| 157 | +
|
| 158 | +otelcol.processor.transform "syslog" { |
| 159 | + error_mode = "ignore" |
| 160 | +
|
| 161 | + log_statements { |
| 162 | + context = "log" |
| 163 | +
|
| 164 | + statements = [ |
| 165 | + `set(attributes["message"], attributes["__syslog_message"])`, |
| 166 | + `set(attributes["appname"], attributes["__syslog_appname"])`, |
| 167 | + `set(attributes["hostname"], attributes["__syslog_hostname"])`, |
| 168 | +
|
| 169 | + // To set structured data you can chain index ([]) operations. |
| 170 | + `set(attributes["structured_data"]["auth@32473"]["user"], attributes["__syslog_message_sd_auth_32473_user"])`, |
| 171 | + `set(attributes["structured_data"]["auth@32473"]["user_host"], attributes["__syslog_message_sd_auth_32473_user_host"])`, |
| 172 | + `set(attributes["structured_data"]["auth@32473"]["valid"], attributes["__syslog_message_sd_auth_32473_authenticated"])`, |
| 173 | + ] |
| 174 | + } |
| 175 | +
|
| 176 | + output { |
| 177 | + metrics = [] |
| 178 | + logs = [otelcol.exporter.syslog.default.input] |
| 179 | + traces = [] |
| 180 | + } |
| 181 | +} |
| 182 | +``` |
| 183 | + |
| 184 | +### Use the `otelcol.processor.transform` component to format OpenTelemetry logs |
| 185 | + |
| 186 | +This example shows one of the methods for annotating your messages in the OpenTelemetry log format into the format expected |
| 187 | +by the exporter using an `otelcol.processor.transform` component. This example assumes that the log messages being |
| 188 | +parsed have come from another OpenTelemetry receiver in JSON format (or have been transformed to OpenTelemetry logs using |
| 189 | +an `otelcol.receiver.loki` component). This is just an example of some of the techniques that can be applied, and not a |
| 190 | +fully functioning example for a specific incoming log format. |
| 191 | + |
| 192 | +```alloy |
| 193 | +otelcol.processor.transform "syslog" { |
| 194 | + error_mode = "ignore" |
| 195 | +
|
| 196 | + log_statements { |
| 197 | + context = "log" |
| 198 | +
|
| 199 | + statements = [ |
| 200 | + // Parse body as JSON and merge the resulting map with the cache map, ignoring non-json bodies. |
| 201 | + // cache is a field exposed by OTTL that is a temporary storage place for complex operations. |
| 202 | + `merge_maps(cache, ParseJSON(body), "upsert") where IsMatch(body, "^\\{")`, |
| 203 | +
|
| 204 | + // Set some example syslog attributes using the values from a JSON message body |
| 205 | + // If the attribute doesn't exist in cache then nothing happens. |
| 206 | + `set(attributes["message"], cache["log"])`, |
| 207 | + `set(attributes["appname"], cache["application"])`, |
| 208 | + `set(attributes["hostname"], cache["source"])`, |
| 209 | +
|
| 210 | + // To set structured data you can chain index ([]) operations. |
| 211 | + `set(attributes["structured_data"]["auth@32473"]["user"], attributes["user"])`, |
| 212 | + `set(attributes["structured_data"]["auth@32473"]["user_host"], cache["source"])`, |
| 213 | + `set(attributes["structured_data"]["auth@32473"]["valid"], cache["authenticated"])`, |
| 214 | +
|
| 215 | + // Example priority setting, using facility 1 (user messages) and default to Info |
| 216 | + `set(attributes["priority"], 14)`, |
| 217 | + `set(attributes["priority"], 12) where severity_number == SEVERITY_NUMBER_WARN`, |
| 218 | + `set(attributes["priority"], 11) where severity_number == SEVERITY_NUMBER_ERROR`, |
| 219 | + `set(attributes["priority"], 10) where severity_number == SEVERITY_NUMBER_FATAL`, |
| 220 | + ] |
| 221 | + } |
| 222 | +
|
| 223 | + output { |
| 224 | + metrics = [] |
| 225 | + logs = [otelcol.exporter.syslog.default.input] |
| 226 | + traces = [] |
| 227 | + } |
| 228 | +} |
| 229 | +``` |
| 230 | + |
| 231 | +<!-- START GENERATED COMPATIBLE COMPONENTS --> |
| 232 | + |
| 233 | +## Compatible components |
| 234 | + |
| 235 | +`otelcol.exporter.syslog` has exports that can be consumed by the following components: |
| 236 | + |
| 237 | +- Components that consume [OpenTelemetry `otelcol.Consumer`](../../../compatibility/#opentelemetry-otelcolconsumer-consumers) |
| 238 | + |
| 239 | +{{< admonition type="note" >}} |
| 240 | +Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. |
| 241 | +Refer to the linked documentation for more details. |
| 242 | +{{< /admonition >}} |
| 243 | + |
| 244 | +<!-- END GENERATED COMPATIBLE COMPONENTS --> |
0 commit comments