Skip to content

Commit b517424

Browse files
andrzej-stencelandrzej-stencel
authored
[chore][exporter/syslog] docs: describe default values, add examples (#27831)
Fixes #21242
1 parent 4117a4c commit b517424

File tree

1 file changed

+118
-8
lines changed

1 file changed

+118
-8
lines changed

‎exporter/syslogexporter/README.md

Lines changed: 118 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,10 @@
1111
[development]: https://github.com/open-telemetry/opentelemetry-collector#development
1212
<!-- end autogenerated section -->
1313

14-
The syslog exporter supports sending messages to a remote syslog server.
15-
16-
- This exporter can forward syslog messages to syslog server using [RFC5424][RFC5424] and [RFC3164][RFC3164].
17-
- 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/)
18-
This ensures that all the syslog message headers are populated with the expected values.
19-
- Not using the `syslog_parser` will result in the syslog message being populated with default header values.
14+
The Syslog exporter sends logs in [syslog][syslog_wikipedia] format to a remote syslog server.
15+
It supports syslog protocols [RFC5424][RFC5424] and [RFC3164][RFC3164] and can send data over `TCP` or `UDP`.
16+
The exporter aims to be compatible with the [Syslog receiver][syslog_receiver].
17+
This means that syslog messages received via the Syslog receiver and exported via the Syslog exporter should be unchanged.
2018

2119
## Configuration
2220

@@ -52,12 +50,124 @@ The syslog exporter supports sending messages to a remote syslog server.
5250
- `storage` (default = `none`): When set, enables persistence and uses the component specified as a storage extension for the [persistent queue][persistent_queue]
5351
- `timeout` (default = 5s) Time to wait per individual attempt to send data to a backend
5452

53+
## Examples
54+
55+
### RFC5424
56+
57+
When configured with `protocol: rfc5424`, the exporter creates one syslog message for each log record,
58+
based on the following record-level attributes of the log.
59+
If an attribute is missing, the default value is used.
60+
The log's timestamp field is used for the syslog message's time.
61+
62+
| Attribute name | Type | Default value |
63+
| ----------------- | ------ | -------------- |
64+
| `appname` | string | `-` |
65+
| `hostname` | string | `-` |
66+
| `message` | string | empty string |
67+
| `msg_id` | string | `-` |
68+
| `priority` | int | `165` |
69+
| `proc_id` | string | `-` |
70+
| `structured_data` | map | `-` |
71+
| `version` | int | `1` |
72+
73+
Here's a simplified representation of an input log record:
74+
75+
```json
76+
{
77+
"body": "",
78+
"timeUnixNano": 1065903255003000000,
79+
"attributes":
80+
{
81+
"appname": "su",
82+
"hostname": "mymachine.example.com",
83+
"message": "'su root' failed for lonvick on /dev/pts/8",
84+
"priority": 34,
85+
}
86+
}
87+
```
88+
89+
And here's the output message based on the above log record:
90+
91+
```console
92+
<34>1 2003-10-11T22:14:15.003Z mymachine.example.com su - - - 'su root' failed for lonvick on /dev/pts/8
93+
```
94+
95+
Here'a another example, this includes the structured data and other attributes:
96+
97+
```json
98+
{
99+
"body": "",
100+
"timeUnixNano": 1438811939693012000,
101+
"attributes":
102+
{
103+
"appname": "SecureAuth0",
104+
"hostname": "192.168.2.132",
105+
"message": "Found the user for retrieving user's profile",
106+
"msg_id": "ID52020",
107+
"priority": 86,
108+
"proc_id": "23108",
109+
"structured_data":
110+
{
111+
"SecureAuth@27389":
112+
{
113+
"UserHostAddress":"192.168.2.132",
114+
"Realm":"SecureAuth0",
115+
"UserID":"Tester2",
116+
"PEN":"27389"
117+
}
118+
},
119+
"version": 1
120+
}
121+
}
122+
```
123+
124+
Output:
125+
126+
```console
127+
<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
128+
```
129+
130+
### RFC3164
131+
132+
When configured with `protocol: rfc3164`, the exporter creates one syslog message for each log record,
133+
based on the following record-level attributes of the log.
134+
If an attribute is missing, the default value is used.
135+
The log's timestamp field is used for the syslog message's time.
136+
137+
| Attribute name | Type | Default value |
138+
| ----------------- | ------ | -------------- |
139+
| `appname` | string | empty string |
140+
| `hostname` | string | `-` |
141+
| `message` | string | empty string |
142+
| `priority` | int | `165` |
143+
144+
Here's a simplified representation of an input log record:
145+
146+
```json
147+
{
148+
"body": "",
149+
"timeUnixNano": 1697062455000000000,
150+
"attributes":
151+
{
152+
"appname": "su",
153+
"hostname": "mymachine",
154+
"message": "'su root' failed for lonvick on /dev/pts/8",
155+
"priority": 34
156+
}
157+
}
158+
```
159+
160+
Output:
161+
162+
```console
163+
<34>Oct 11 22:14:15 mymachine su: 'su root' failed for lonvick on /dev/pts/8
164+
```
165+
55166
Please see [example configurations](./examples/).
56167

168+
[syslog_wikipedia]: https://en.wikipedia.org/wiki/Syslog
57169
[RFC5424]: https://www.rfc-editor.org/rfc/rfc5424
58170
[RFC3164]: https://www.rfc-editor.org/rfc/rfc3164
59-
[syslog_parser]: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/pkg/stanza/docs/operators/syslog_parser.md
60171
[syslog_receiver]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/syslogreceiver
61-
[filelog_receiver]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/filelogreceiver
62172
[cryptoTLS]: https://github.com/golang/go/blob/518889b35cb07f3e71963f2ccfc0f96ee26a51ce/src/crypto/tls/common.go#L706-L709
63173
[persistent_queue]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/exporterhelper/README.md#persistent-queue

0 commit comments

Comments
 (0)