syslogexporter

README

Syslog Exporter

Status
Stability	alpha: logs
Distributions	contrib
Issues
Code Owners	@kasia-kujawa, @rnishtala-sumo, @andrzej-stencel

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
• enable_octet_counting (default = false) - Whether or not to enable rfc6587 octet counting
• tls - configuration for TLS/mTLS (applied only when network is set to tcp)
  • 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.

Documentation

Index

• Constants
• func NewFactory() exporter.Factory
• type Config
  • func (cfg *Config) Validate() error

Constants

const (
	// Syslog Network
	DefaultNetwork = string(confignet.TransportTypeTCP)
	// Syslog Port
	DefaultPort = 514
	// Syslog Protocol
	DefaultProtocol = "rfc5424"
)

Functions

func NewFactory

func NewFactory() exporter.Factory

NewFactory returns a new factory for the syslog exporter.

Types

type Config

type Config struct {
	// Syslog server address
	Endpoint string `mapstructure:"endpoint"`
	// Syslog server port
	Port int `mapstructure:"port"`
	// Network for syslog communication
	// options: tcp, udp
	Network string `mapstructure:"network"`
	// Protocol of syslog messages
	// options: rfc5424, rfc3164
	Protocol string `mapstructure:"protocol"`

	// Wether or not to enable RFC 6587 Octet Counting.
	EnableOctetCounting bool `mapstructure:"enable_octet_counting"`

	// TLSSetting struct exposes TLS client configuration.
	TLSSetting configtls.ClientConfig `mapstructure:"tls"`

	QueueSettings             exporterhelper.QueueConfig `mapstructure:"sending_queue"`
	configretry.BackOffConfig `mapstructure:"retry_on_failure"`
	TimeoutSettings           exporterhelper.TimeoutConfig `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct
}

Config defines configuration for Syslog exporter.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate the configuration for errors. This is required by component.Config.