ob-col/exporter/syslogexporter

Syslog Exporter

Status
Stability	alpha: logs
Distributions	contrib
Issues
Code Owners	@kkujawa-sumo, @rnishtala-sumo, @astencel-sumo

The Syslog exporter sends logs in syslog format to a remote syslog server. It supports syslog protocols RFC5424 and RFC3164 and can send data over TCP or UDP. The exporter aims to be compatible with the Syslog receiver. This means that syslog messages received via the Syslog receiver and exported via the Syslog exporter should be unchanged.

Configuration

The following configuration options are available:

• endpoint - (required) syslog endpoint
• network - (default = tcp) tcp/udp
• port - (default = 514) A syslog port
• protocol - (default = rfc5424) rfc5424/rfc3164
  • rfc5424 - Expects the syslog messages to be rfc5424 compliant
  • rfc3164 - Expects the syslog messages to be rfc3164 compliant
• tls - configuration for TLS/mTLS
  • insecure (default = false) whether to enable client transport security, by default, TLS is enabled.
  • cert_file - Path to the TLS cert to use for TLS required connections. Should only be used if insecure is set to false.
  • key_file - Path to the TLS key to use for TLS required connections. Should only be used if insecure is set to false.
  • ca_file - Path to the CA cert. For a client this verifies the server certificate. For a server this verifies client certificates. If empty uses system root CA. Should only be used if insecure is set to false.
  • insecure_skip_verify - (default = false) whether to skip verifying the certificate or not.
  • min_version (default = 1.2) Minimum acceptable TLS version
  • max_version (default = "" handled by crypto/tls - currently TLS 1.3) Maximum acceptable TLS version.
  • reload_interval - Specifies the duration after which the certificate will be reloaded. If not set, it will never be reloaded.
• retry_on_failure
  • enabled (default = true)
  • initial_interval (default = 5s): Time to wait after the first failure before retrying; ignored if enabled is false
  • max_interval (default = 30s): Is the upper bound on backoff; ignored if enabled is false
  • max_elapsed_time (default = 120s): Is the maximum amount of time spent trying to send a batch; ignored if enabled is false
• sending_queue
  • enabled (default = false)
  • num_consumers (default = 10): Number of consumers that dequeue batches; ignored if enabled is false
  • queue_size (default = 5000): Maximum number of batches kept in memory before data; ignored if enabled is false; User should calculate this as num_seconds * requests_per_second where:
  • num_seconds is the number of seconds to buffer in case of a backend outage
  • requests_per_second is the average number of requests per seconds.
  • storage (default = none): When set, enables persistence and uses the component specified as a storage extension for the 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:

{
  "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:

<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:

{
  "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:

<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:

{
  "body": "",
  "timeUnixNano": 1697062455000000000,
  "attributes":
  {
    "appname": "su",
    "hostname": "mymachine",
    "message": "'su root' failed for lonvick on /dev/pts/8",
    "priority": 34
  }
}

Output:

<34>Oct 11 22:14:15 mymachine su: 'su root' failed for lonvick on /dev/pts/8

Please see example configurations.