From 8b92ed86630e06597b6a7411f90471374774057a Mon Sep 17 00:00:00 2001 From: Daniel Nelson Date: Fri, 25 May 2018 14:33:57 -0700 Subject: [PATCH] Update syslog docs and add to changelog and readme --- CHANGELOG.md | 4 +- README.md | 1 + plugins/inputs/syslog/README.md | 89 +++++++++++++-------------------- 3 files changed, 38 insertions(+), 56 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c3388d8e9..cb30a56d2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ - [jti_openconfig_telemetry](./plugins/inputs/jti_openconfig_telemetry/README.md) - Contributed by @ajhai - [mcrouter](./plugins/inputs/mcrouter/README.md) - Contributed by @cthayer - [nvidia_smi](./plugins/inputs/nvidia_smi/README.md) - Contributed by @jackzampolin +- [syslog](./plugins/inputs/syslog/README.md) - Contributed by @influxdata ### New Processors @@ -57,7 +58,8 @@ - [#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. - [#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 - [#4018](https://github.com/influxdata/telegraf/pull/4018): Write to working file outputs if any files are not writeable. diff --git a/README.md b/README.md index 3b1355a4f..bf7084a49 100644 --- a/README.md +++ b/README.md @@ -211,6 +211,7 @@ configuration options. * [snmp_legacy](./plugins/inputs/snmp_legacy) * [solr](./plugins/inputs/solr) * [sql server](./plugins/inputs/sqlserver) (microsoft) +* [syslog](./plugins/inputs/syslog) * [teamspeak](./plugins/inputs/teamspeak) * [tomcat](./plugins/inputs/tomcat) * [twemproxy](./plugins/inputs/twemproxy) diff --git a/plugins/inputs/syslog/README.md b/plugins/inputs/syslog/README.md index 010dab60d..107727947 100644 --- a/plugins/inputs/syslog/README.md +++ b/plugins/inputs/syslog/README.md @@ -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. - -This plugin listens for syslog messages following RFC5424 format. When received it parses them extracting metrics. +Syslog messages should be formatted according to +[RFC 5424](https://tools.ietf.org/html/rfc5424). ### Configuration @@ -48,72 +49,50 @@ This plugin listens for syslog messages following RFC5424 format. When received # sdparam_separator = "_" ``` -#### Other configs +#### Best Effort -Other available configurations are: - -- `keep_alive_period`, `max_connections` for stream sockets -- `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 +The [`best_effort`](https://github.com/influxdata/go-syslog#best-effort-mode) +option instructs the parser to extract partial but valid info from syslog +messages. If unset only full messages will be collected. ### Metrics - 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 - - **severity** (`string`) - - **facility** (`string`) - - hostname (`string`) - - appname (`string`) + - severity (string) + - facility (string) + - hostname (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 - -The following instructions illustrate how to configure a syslog transport sender as per RFC5425 - ie., using the octect framing technique - via RSYSLOG. - -Install `rsyslog`. - -Give it a configuration - ie., `/etc/rsyslog.conf`. +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 +new configuration into the config directory to simplify updates to the main +config file. +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 $ActionQueueFileName srvrfwd # set file name, also enables disk mode $ActionResumeRetryCount -1 # infinite retries on insert failure $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. - -Create a file - eg., `/etc/rsyslog.d/50-default.conf` - containing: - -``` +# forward over tcp with octet framing according to RFC 5425 *.* @@(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). - -Notice that this configuration tells `rsyslog` to broadcast messages to `127.0.0.1>6514`. - -So you have to configure this plugin accordingly. \ No newline at end of file +To complete TLS setup please refer to [rsyslog docs](https://www.rsyslog.com/doc/v8-stable/tutorials/tls.html).