Update syslog docs and add to changelog and readme

This commit is contained in:
Daniel Nelson 2018-05-25 14:33:57 -07:00
parent 54c59f8688
commit 8b92ed8663
3 changed files with 38 additions and 56 deletions

View File

@ -19,6 +19,7 @@
- [jti_openconfig_telemetry](./plugins/inputs/jti_openconfig_telemetry/README.md) - Contributed by @ajhai - [jti_openconfig_telemetry](./plugins/inputs/jti_openconfig_telemetry/README.md) - Contributed by @ajhai
- [mcrouter](./plugins/inputs/mcrouter/README.md) - Contributed by @cthayer - [mcrouter](./plugins/inputs/mcrouter/README.md) - Contributed by @cthayer
- [nvidia_smi](./plugins/inputs/nvidia_smi/README.md) - Contributed by @jackzampolin - [nvidia_smi](./plugins/inputs/nvidia_smi/README.md) - Contributed by @jackzampolin
- [syslog](./plugins/inputs/syslog/README.md) - Contributed by @influxdata
### New Processors ### New Processors
@ -57,7 +58,8 @@
- [#3969](https://github.com/influxdata/telegraf/pull/3969): Add option to unbound module to use threads as tags. - [#3969](https://github.com/influxdata/telegraf/pull/3969): Add option to unbound module to use threads as tags.
- [#4183](https://github.com/influxdata/telegraf/pull/4183): Add support for TLS and username/password auth to aerospike input. - [#4183](https://github.com/influxdata/telegraf/pull/4183): Add support for TLS and username/password auth to aerospike input.
- [#4190](https://github.com/influxdata/telegraf/pull/4190): Add special syslog timestamp parser to grok parser that uses current year. - [#4190](https://github.com/influxdata/telegraf/pull/4190): Add special syslog timestamp parser to grok parser that uses current year.
- - [#4181](https://github.com/influxdata/telegraf/pull/4181): Add syslog input plugin.
### Bugfixes ### Bugfixes
- [#4018](https://github.com/influxdata/telegraf/pull/4018): Write to working file outputs if any files are not writeable. - [#4018](https://github.com/influxdata/telegraf/pull/4018): Write to working file outputs if any files are not writeable.

View File

@ -211,6 +211,7 @@ configuration options.
* [snmp_legacy](./plugins/inputs/snmp_legacy) * [snmp_legacy](./plugins/inputs/snmp_legacy)
* [solr](./plugins/inputs/solr) * [solr](./plugins/inputs/solr)
* [sql server](./plugins/inputs/sqlserver) (microsoft) * [sql server](./plugins/inputs/sqlserver) (microsoft)
* [syslog](./plugins/inputs/syslog)
* [teamspeak](./plugins/inputs/teamspeak) * [teamspeak](./plugins/inputs/teamspeak)
* [tomcat](./plugins/inputs/tomcat) * [tomcat](./plugins/inputs/tomcat)
* [twemproxy](./plugins/inputs/twemproxy) * [twemproxy](./plugins/inputs/twemproxy)

View File

@ -1,10 +1,11 @@
# syslog input plugin # Syslog Input Plugin
Collects syslog messages as per RFC5425 or RFC5426. The syslog plugin listens for syslog messages transmitted over
[UDP](https://tools.ietf.org/html/rfc5426) or
[TCP](https://tools.ietf.org/html/rfc5425).
It can act as a syslog transport receiver over TLS (or TCP) - ie., RFC5425 - or over UDP - ie., RFC5426. Syslog messages should be formatted according to
[RFC 5424](https://tools.ietf.org/html/rfc5424).
This plugin listens for syslog messages following RFC5424 format. When received it parses them extracting metrics.
### Configuration ### Configuration
@ -48,72 +49,50 @@ This plugin listens for syslog messages following RFC5424 format. When received
# sdparam_separator = "_" # sdparam_separator = "_"
``` ```
#### Other configs #### Best Effort
Other available configurations are: The [`best_effort`](https://github.com/influxdata/go-syslog#best-effort-mode)
option instructs the parser to extract partial but valid info from syslog
- `keep_alive_period`, `max_connections` for stream sockets messages. If unset only full messages will be collected.
- `read_timeout`
- `best_effort` to tell the parser to work until it is able to do and extract partial but valid info (more [here](https://github.com/influxdata/go-syslog#best-effort-mode))
- `sdparam_separator` to choose how to separate structured data param name from its structured data identifier
### Metrics ### Metrics
- syslog - syslog
- fields
- **version** (`uint16`)
- **severity_code** (`int`)
- **facility_code** (`int`)
- timestamp (`int`)
- procid (`string`)
- msgid (`string`)
- *sdid* (`bool`)
- *sdid . sdparam_separator . sdparam_name* (`string`)
- tags - tags
- **severity** (`string`) - severity (string)
- **facility** (`string`) - facility (string)
- hostname (`string`) - hostname (string)
- appname (`string`) - appname (string)
- fields
- version (integer)
- severity_code (integer)
- facility_code (integer)
- timestamp (integer)
- procid (string)
- msgid (string)
- sdid (bool)
- *Structured Data* (string)
The name of fields in _italic_ corresponds to their runtime value. ### Rsyslog Integration
The fields/tags which name is in **bold** will always be present when a valid Syslog message has been received. Rsyslog can be configured to forward logging messages to Telegraf by configuring
[remote logging](https://www.rsyslog.com/doc/v8-stable/configuration/actions.html#remote-machine).
### RSYSLOG integration Most system are setup with a configuration split between `/etc/rsyslog.conf`
and the files in the `/etc/rsyslog.d/` directory, it is recommended to add the
The following instructions illustrate how to configure a syslog transport sender as per RFC5425 - ie., using the octect framing technique - via RSYSLOG. new configuration into the config directory to simplify updates to the main
config file.
Install `rsyslog`.
Give it a configuration - ie., `/etc/rsyslog.conf`.
Add the following lines to `/etc/rsyslog.d/50-telegraf.conf` making
adjustments to the target address as needed:
``` ```
$ModLoad imuxsock # provides support for local system logging
$ModLoad imklog # provides kernel logging support
$ModLoad immark # provides heart-beat logs
$FileOwner root
$FileGroup root
$FileCreateMode 0640
$DirCreateMode 0755
$Umask 0022
$WorkDirectory /var/spool/rsyslog # default location for work (spool) files
$ActionQueueType LinkedList # use asynchronous processing $ActionQueueType LinkedList # use asynchronous processing
$ActionQueueFileName srvrfwd # set file name, also enables disk mode $ActionQueueFileName srvrfwd # set file name, also enables disk mode
$ActionResumeRetryCount -1 # infinite retries on insert failure $ActionResumeRetryCount -1 # infinite retries on insert failure
$ActionQueueSaveOnShutdown on # save in-memory data if rsyslog shuts down $ActionQueueSaveOnShutdown on # save in-memory data if rsyslog shuts down
$IncludeConfig /etc/rsyslog.d/*.conf
```
Specify you want the octet framing technique enabled and the format of each syslog message to follow the RFC5424. # forward over tcp with octet framing according to RFC 5425
Create a file - eg., `/etc/rsyslog.d/50-default.conf` - containing:
```
*.* @@(o)127.0.0.1:6514;RSYSLOG_SyslogProtocol23Format *.* @@(o)127.0.0.1:6514;RSYSLOG_SyslogProtocol23Format
``` ```
To complete the TLS setup please refer to [rsyslog docs](https://www.rsyslog.com/doc/v8-stable/tutorials/tls.html). To complete TLS setup please refer to [rsyslog docs](https://www.rsyslog.com/doc/v8-stable/tutorials/tls.html).
Notice that this configuration tells `rsyslog` to broadcast messages to `127.0.0.1>6514`.
So you have to configure this plugin accordingly.