From 8d733496aa1a7d0bef2eb47f84c1e07b3701ffb0 Mon Sep 17 00:00:00 2001 From: Andrzej Stencel Date: Wed, 18 Oct 2023 10:36:33 +0200 Subject: [PATCH] [chore][exporter/syslog] docs: describe default values, add examples --- exporter/syslogexporter/README.md | 126 ++++++++++++++++++++++++++++-- 1 file changed, 118 insertions(+), 8 deletions(-) diff --git a/exporter/syslogexporter/README.md b/exporter/syslogexporter/README.md index d68c1af15723..02de6fbf9d3b 100644 --- a/exporter/syslogexporter/README.md +++ b/exporter/syslogexporter/README.md @@ -11,12 +11,10 @@ [development]: https://github.com/open-telemetry/opentelemetry-collector#development -The syslog exporter supports sending messages to a remote syslog server. - -- This exporter can forward syslog messages to syslog server using [RFC5424][RFC5424] and [RFC3164][RFC3164]. -- It is recommended that this syslog exporter be used with the [syslog receiver][syslog_receiver] or with [filelog receiver][filelog_receiver] along with [syslog_parser][syslog_parser] configured in the receiver, please see [examples](./examples/) - This ensures that all the syslog message headers are populated with the expected values. -- Not using the `syslog_parser` will result in the syslog message being populated with default header values. +The Syslog exporter sends logs in [syslog][syslog_wikipedia] format to a remote syslog server. +It supports syslog protocols [RFC5424][RFC5424] and [RFC3164][RFC3164] and can send data over `TCP` or `UDP`. +The exporter aims to be compatible with the [Syslog receiver][syslog_receiver]. +This means that syslog messages received via the Syslog receiver and exported via the Syslog exporter should be unchanged. ## Configuration @@ -52,12 +50,124 @@ The syslog exporter supports sending messages to a remote syslog server. - `storage` (default = `none`): When set, enables persistence and uses the component specified as a storage extension for the [persistent queue][persistent_queue] - `timeout` (default = 5s) Time to wait per individual attempt to send data to a backend +## Examples + +### RFC5424 + +When configured with `protocol: rfc5424`, the exporter creates one syslog message for each log record, +based on the following record-level attributes of the log. +If an attribute is missing, the default value is used. +The log's timestamp field is used for the syslog message's time. + +| Attribute name | Type | Default value | +| ----------------- | ------ | -------------- | +| `appname` | string | `-` | +| `hostname` | string | `-` | +| `message` | string | empty string | +| `msg_id` | string | `-` | +| `priority` | int | `165` | +| `proc_id` | string | `-` | +| `structured_data` | map | `-` | +| `version` | int | `1` | + +Here's a simplified representation of an input log record: + +```json +{ + "body": "", + "timeUnixNano": 1065903255003000000, + "attributes": + { + "appname": "su", + "hostname": "mymachine.example.com", + "message": "'su root' failed for lonvick on /dev/pts/8", + "priority": 34, + } +} +``` + +And here's the output message based on the above log record: + +```console +<34>1 2003-10-11T22:14:15.003Z mymachine.example.com su - - - 'su root' failed for lonvick on /dev/pts/8 +``` + +Here'a another example, this includes the structured data and other attributes: + +```json +{ + "body": "", + "timeUnixNano": 1438811939693012000, + "attributes": + { + "appname": "SecureAuth0", + "hostname": "192.168.2.132", + "message": "Found the user for retrieving user's profile", + "msg_id": "ID52020", + "priority": 86, + "proc_id": "23108", + "structured_data": + { + "SecureAuth@27389": + { + "UserHostAddress":"192.168.2.132", + "Realm":"SecureAuth0", + "UserID":"Tester2", + "PEN":"27389" + } + }, + "version": 1 + } +} +``` + +Output: + +```console +<86>1 2015-08-05T21:58:59.693012Z 192.168.2.132 SecureAuth0 23108 ID52020 [SecureAuth@27389 UserHostAddress="192.168.2.132" Realm="SecureAuth0" UserID="Tester2" PEN="27389"] Found the user for retrieving user's profile +``` + +### RFC3164 + +When configured with `protocol: rfc3164`, the exporter creates one syslog message for each log record, +based on the following record-level attributes of the log. +If an attribute is missing, the default value is used. +The log's timestamp field is used for the syslog message's time. + +| Attribute name | Type | Default value | +| ----------------- | ------ | -------------- | +| `appname` | string | empty string | +| `hostname` | string | `-` | +| `message` | string | empty string | +| `priority` | int | `165` | + +Here's a simplified representation of an input log record: + +```json +{ + "body": "", + "timeUnixNano": 1697062455000000000, + "attributes": + { + "appname": "su", + "hostname": "mymachine", + "message": "'su root' failed for lonvick on /dev/pts/8", + "priority": 34 + } +} +``` + +Output: + +```console +<34>Oct 11 22:14:15 mymachine su: 'su root' failed for lonvick on /dev/pts/8 +``` + Please see [example configurations](./examples/). +[syslog_wikipedia]: https://en.wikipedia.org/wiki/Syslog [RFC5424]: https://www.rfc-editor.org/rfc/rfc5424 [RFC3164]: https://www.rfc-editor.org/rfc/rfc3164 -[syslog_parser]: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/pkg/stanza/docs/operators/syslog_parser.md [syslog_receiver]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/syslogreceiver -[filelog_receiver]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/filelogreceiver [cryptoTLS]: https://github.com/golang/go/blob/518889b35cb07f3e71963f2ccfc0f96ee26a51ce/src/crypto/tls/common.go#L706-L709 [persistent_queue]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/exporterhelper/README.md#persistent-queue