[exporter/syslogexporter] Add support for Unix sockets (open-telemetry#40740)

#### Description

If the collector is running on the same system as the syslog endpoint,
being able to export the logs to a socket means not having to open an
extra port.

The `network` configuration now accepts `"unix"` as a valid option in
addition to `"tcp"` and `"udp"`. When `network` is set to `"unix"`, the
`endpoint` must be a valid Unix socket file path, and `port` is ignored.

#### Testing
Manual testing by building the collector, configuring a Unix socket as
endpoint, sending logs to the collector endpoint and verifying the logs
are received via the socket.
Also adjusted existing tests.

#### Documentation
Adjusted README.

---------

Co-authored-by: Antoine Toulme <[email protected]>
Co-authored-by: Andrzej Stencel <[email protected]>

Author: 3 people

.chloggen/syslogexporter-unix-socket-support.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: syslogexporter
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add support for Unix sockets
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [40740]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: The `network` configuration now accepts `"unix"` as a valid option in addition to `"tcp"` and `"udp"`. When `network` is set to `"unix"`, the `endpoint` must be a valid Unix socket file path, and `port` is ignored.
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

exporter/syslogexporter/README.md

@@ -14,7 +14,7 @@
 <!-- end autogenerated section -->
 
 The Syslog exporter sends logs in [syslog][syslog_wikipedia] format to a remote syslog server.
-It supports syslog protocols [RFC5424][RFC5424] and [RFC3164][RFC3164] and can send data over `TCP` or `UDP`.
+It supports syslog protocols [RFC5424][RFC5424] and [RFC3164][RFC3164] and can send data over `TCP`, `UDP` or Unix sockets.
 The exporter aims to be compatible with the [Syslog receiver][syslog_receiver].
 This means that syslog messages received via the Syslog receiver and exported via the Syslog exporter should be unchanged.
 
@@ -23,8 +23,8 @@ This means that syslog messages received via the Syslog receiver and exported vi
 **The following configuration options are available**:
 
 - `endpoint` - (required) syslog endpoint
-- `network` - (default = `tcp`) tcp/udp
-- `port` - (default = `514`) A syslog port
+- `network` - (default = `tcp`) tcp/udp/unix
+- `port` - (default = `514`) A syslog port, ignored when `network` is set to `unix`
 - `protocol` - (default = `rfc5424`) rfc5424/rfc3164
   - `rfc5424` - Expects the syslog messages to be rfc5424 compliant
   - `rfc3164` - Expects the syslog messages to be rfc3164 compliant

exporter/syslogexporter/config.go

@@ -16,7 +16,7 @@ import (
 var (
 	errUnsupportedPort     = errors.New("unsupported port: port is required, must be in the range 1-65535")
 	errInvalidEndpoint     = errors.New("invalid endpoint: endpoint is required but it is not configured")
-	errUnsupportedNetwork  = errors.New("unsupported network: network is required, only tcp/udp supported")
+	errUnsupportedNetwork  = errors.New("unsupported network: network is required, only tcp/udp/unix supported")
 	errUnsupportedProtocol = errors.New("unsupported protocol: Only rfc5424 and rfc3164 supported")
 	errOctetCounting       = errors.New("octet counting is only supported for rfc5424 protocol")
 )
@@ -25,10 +25,10 @@ var (
 type Config struct {
 	// Syslog server address
 	Endpoint string `mapstructure:"endpoint"`
-	// Syslog server port
+	// Syslog server port (ignored for Unix sockets)
 	Port int `mapstructure:"port"`
 	// Network for syslog communication
-	// options: tcp, udp
+	// options: tcp, udp, unix
 	Network string `mapstructure:"network"`
 	// Protocol of syslog messages
 	// options: rfc5424, rfc3164
@@ -48,19 +48,22 @@ type Config struct {
 // Validate the configuration for errors. This is required by component.Config.
 func (cfg *Config) Validate() error {
 	invalidFields := []error{}
-	if cfg.Port < 1 || cfg.Port > 65535 {
-		invalidFields = append(invalidFields, errUnsupportedPort)
+
+	cfg.Network = strings.ToLower(cfg.Network)
+	switch cfg.Network {
+	case string(confignet.TransportTypeTCP), string(confignet.TransportTypeUDP):
+		if cfg.Port < 1 || cfg.Port > 65535 {
+			invalidFields = append(invalidFields, errUnsupportedPort)
+		}
+	case string(confignet.TransportTypeUnix):
+	default:
+		invalidFields = append(invalidFields, errUnsupportedNetwork)
 	}
 
 	if cfg.Endpoint == "" {
 		invalidFields = append(invalidFields, errInvalidEndpoint)
 	}
 
-	cfg.Network = strings.ToLower(cfg.Network)
-	if cfg.Network != string(confignet.TransportTypeTCP) && cfg.Network != string(confignet.TransportTypeUDP) {
-		invalidFields = append(invalidFields, errUnsupportedNetwork)
-	}
-
 	switch cfg.Protocol {
 	case protocolRFC3164Str:
 	case protocolRFC5424Str:

exporter/syslogexporter/config_test.go

@@ -44,7 +44,7 @@ func TestValidate(t *testing.T) {
 				Protocol: "rfc5424",
 				Network:  "ftp",
 			},
-			err: "unsupported network: network is required, only tcp/udp supported",
+			err: "unsupported network: network is required, only tcp/udp/unix supported",
 		},
 		{
 			name: "Unsupported Protocol",
@@ -56,6 +56,15 @@ func TestValidate(t *testing.T) {
 			},
 			err: "unsupported protocol: Only rfc5424 and rfc3164 supported",
 		},
+		{
+			name: "invalid Unix Socket",
+			cfg: &Config{
+				Endpoint: "",
+				Network:  "unix",
+				Protocol: "rfc5424",
+			},
+			err: "invalid endpoint: endpoint is required but it is not configured",
+		},
 	}
 	for _, testInstance := range tests {
 		t.Run(testInstance.name, func(t *testing.T) {

exporter/syslogexporter/examples/config_with_syslog_receiver_network_unix.yaml

@@ -0,0 +1,63 @@
+extensions:
+  file_storage/syslog:
+    directory: /tmp/otc
+    timeout: 10s
+
+exporters:
+  syslog:
+    network: unix
+    endpoint: /var/run/my-socket.sock
+    protocol: rfc5424
+
+    # for below described queueing and retry related configuration please refer to:
+    # https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/exporterhelper/README.md#configuration
+    retry_on_failure:
+      # default = true
+      enabled: true
+      # time to wait after the first failure before retrying;
+      # ignored if enabled is false, default = 5s
+      initial_interval: 10s
+      # is the upper bound on backoff; ignored if enabled is false, default = 30s
+      max_interval: 40s
+      # is the maximum amount of time spent trying to send a batch;
+      # ignored if enabled is false, default = 120s
+      max_elapsed_time: 150s
+
+    sending_queue:
+      # default = false
+      enabled: true
+      # number of consumers that dequeue batches; ignored if enabled is false,
+      # default = 10
+      num_consumers: 20
+      # when set, enables persistence and uses the component specified as a storage extension for the persistent queue
+      # make sure to configure and add a `file_storage` extension in `service.extensions`.
+      # default = None
+      storage: file_storage/syslog
+      # maximum number of batches kept in memory before data;
+      # ignored if enabled is false, default = 5000
+      #
+      # 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.
+      queue_size: 10000
+    # Time to wait per individual attempt to send data to a backend
+    # default = 5s
+    timeout: 1s
+receivers:
+  syslog: 
+    tcp: 
+      listen_address: "0.0.0.0:6514"
+    protocol: rfc5424
+
+service:
+  telemetry:
+      logs:
+        level: "debug"
+  extensions:
+    - file_storage/syslog
+  pipelines:
+    logs:
+      receivers:
+        - syslog
+      exporters:
+        - syslog