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

…pen-telemetry#27831)

Fixes
open-telemetry#21242

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