[chore][exporter/syslog] docs: describe default values, add examples (o…

…pen-telemetry#27831) Fixes open-telemetry#21242
scalyr · Oct 20, 2023 · 0ec2beb · 0ec2beb
1 parent d5994be
commit 0ec2beb
Showing 1 changed file with 118 additions and 8 deletions.
diff --git a/exporter/syslogexporter/README.md b/exporter/syslogexporter/README.md
@@ -11,12 +11,10 @@
 [development]: https://github.com/open-telemetry/opentelemetry-collector#development
 <!-- end autogenerated section -->
 
-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