write_syslog plugin¶

See this section in the full configuration reference

The write_syslog plugin writes data in syslog format log messages. It implements the basic syslog protocol, RFC 5424, extends it with content-based filtering, rich filtering capabilities, flexible configuration options and adds features such as using TCP for transport. The plugin can connect to a Syslog daemon, like syslog-ng and rsyslog, that will ingest metrics, transform and ship them to the specified output. The plugin uses TCP over the "line based" protocol with a default port 44514. The data will be sent in blocks of at most 1428 bytes to minimize the number of network packets.

Synopsis:

<Plugin write_syslog>
  ResolveInterval 60
  ResolveJitter 60
  <Node "example">
    Host "syslog-1.my.domain"
    Port "44514"
    Prefix "collectd"
    MessageFormat "human"
    HostTags ""
  </Node>
</Plugin>

The configuration consists of one or more <Node Name> blocks and global directives.

Global directives are:

ResolveInterval seconds

ResolveJitter seconds

When collectd connects to a syslog node, it will request the hostname from DNS. This can become a problem if the syslog node is unavailable or badly configured because collectd will request DNS in order to reconnect for every metric, which can flood your DNS. So you can cache the last value for ResolveInterval seconds. Defaults to the Interval of the write_syslog plugin, e.g. 10E<nbsp>seconds.

You can also define a jitter, a random interval to wait in addition to ResolveInterval. This prevents all your collectd servers to resolve the hostname at the same time when the connection fails. Defaults to the Interval of the write_syslog plugin, e.g. 10E<nbsp>seconds.

Note: If the DNS resolution has already been successful when the socket closes, the plugin will try to reconnect immediately with the cached information. DNS is queried only when the socket is closed for a longer than ResolveInterval + ResolveJitter seconds.

Inside the Node blocks, the following options are recognized:

Host Address

Hostname or address to connect to. Defaults to localhost.

Port Service

Service name or port number to connect to. Defaults to 44514.

HostTags String

When set, HostTags is added to the end of the metric. It is intended to be used for adding additional metadata to tag the metric with. Dots and whitespace are not escaped in this string.

Examples:

When MessageFormat is set to "human".

["prefix1" "example1"="example1_v"]["prefix2" "example2"="example2_v"]"

When MessageFormat is set to "JSON", text should be in JSON format. Escaping the quotation marks is required.

HostTags "\"prefix1\": {\"example1\":\"example1_v\",\"example2\":\"example2_v\"}"

MessageFormat String

MessageFormat selects the format in which messages are sent to the syslog deamon, human or JSON. Defaults to human.

Syslog message format:

<priority>VERSION ISOTIMESTAMP HOSTNAME APPLICATION PID MESSAGEID STRUCTURED-DATA MSG

The difference between the message formats are in the STRUCTURED-DATA and MSG parts.

Human format:

<166>1 ISOTIMESTAMP HOSTNAME collectd PID MESSAGEID
["collectd" "value": "v1" "plugin"="plugin_v" "plugin_instance"="plugin_instance_v"
"type_instance"="type_instance_v" "type"="type_v" "ds_name"="ds_name_v" "interval"="interval_v" ]
"host_tag_example"="host_tag_example_v" plugin_v.type_v.ds_name_v="v1"

JSON format:

<166>1 ISOTIMESTAMP HOSTNAME collectd PID MESSAGEID STRUCTURED-DATA
{
  "collectd": {
  "time": time_as_epoch, "interval": interval_v, "plugin": "plugin_v",
  "plugin_instance": "plugin_instance_v", "type":"type_v",
  "type_instance": "type_instance_v", "plugin_v": {"type_v": v1}
  } , "host":"host_v", "host_tag_example": "host_tag_example_v"
}

StoreRates false|true

If set to true, convert counter values to rates. If set to false (the default) counter values are stored as is, as an increasing integer number.

AlwaysAppendDS false|true

If set to true, append the name of the Data Source (DS) to the "metric" identifier. If set to false (the default), this is only done when there is more than one DS.

Prefix String

When set, Prefix is added to all metrics names as a prefix. It is intended in case you want to be able to define the source of the specific metric. Dots and whitespace are not escaped in this string.