33. Syslog Support

Spring Integration 2.2 introduced the syslog transformer: SyslogToMapTransformer.

You need to include this dependency into your project:

Maven. 

<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-syslog</artifactId>
    <version>5.1.0.RELEASE</version>
</dependency>

Gradle. 

compile "org.springframework.integration:spring-integration-syslog:5.1.0.RELEASE"

This transformer, together with a UDP or TCP inbound adapter, could be used to receive and analyze syslog records from other hosts. The transformer creates a message payload that contains a map of the elements from the syslog message.

Spring Integration 3.0 introduced convenient namespace support for configuring a syslog inbound adapter in a single element.

Starting with version 4.1.1, the framework now supports the extended syslog format, as specified in RFC 5424>. In addition, when using TCP and RFC5424, both octet counting and non-transparent framing described in RFC 6587 are supported.

33.1 Syslog Inbound Channel Adapter

This element encompasses a UDP or TCP inbound channel adapter and a MessageConverter to convert the syslog message to a Spring Integration message. The DefaultMessageConverter delegates to the SyslogToMapTransformer, creating a message with its payload being the Map of syslog fields. In addition, all fields except the message are also made available as headers in the message and are prefixed with syslog_. In this mode, only RFC 3164 (BSD) syslogs are supported.

Since version 4.1, the DefaultMessageConverter has a property called asMap (the default is true). When it is false, the converter leaves the message payload as the original complete syslog message (in a byte[]) while still setting the headers.

Since version 4.1.1, RFC 5424 is also supported, by using the RFC5424MessageConverter. In this case, the fields are not copied as headers, unless asMap is set to false, in which case the original message is the payload and the decoded fields are headers.

[Important]Important

To use RFC 5424 with a TCP transport, you must provide additional configuration to enable the different framing techniques described in RFC 6587. The adapter needs a TCP connection factory that is configured with a RFC6587SyslogDeserializer. By default, this deserializer handles octet counting and non-transparent framing by using a linefeed (LF) to delimit syslog messages. It uses a ByteArrayLfSerializer when octet counting is not detected. To use different non-transparent framing, you can provide it with some other deserializer. While the deserializer can support both octet counting and non-transparent framing, only one form of the latter is supported. If asMap is false on the converter, you must set the retainOriginal constructor argument in the RFC6587SyslogDeserializer.

33.1.1 Example Configuration

The following example defines a UDP adapter that sends messages to the syslogIn channel (the adapter bean name is syslogIn.adapter):

<int-syslog:inbound-channel-adapter id="syslogIn" port="1514" />

The adapter listens on port 1514.

The following example defines a UDP adapter that sends messages to the fromSyslog channel (the adapter bean name is syslogIn):

<int-syslog:inbound-channel-adapter id="syslogIn"
	channel="fromSyslog" port="1514" />

The adapter listens on port 1514.

The following example defines a TCP adapter that sends messages to channel syslogIn (the adapter bean name is syslogIn.adapter):

<int-syslog:inbound-channel-adapter id="bar" protocol="tcp" port="1514" />

The adapter listens on port 1514.

Note the addition of the protocol attribute. This attribute can contain udp or tcp. It defaults to udp.

The following example shows a UDP adapter that sends messages to channel fromSyslog:

<int-syslog:inbound-channel-adapter id="udpSyslog"
	channel="fromSyslog"
	auto-startup="false"
	phase="10000"
	converter="converter"
	send-timeout="1000"
	error-channel="errors">
		<int-syslog:udp-attributes port="1514" lookup-host="false" />
</int-syslog:inbound-channel-adapter>

The preceding example also shows two SmartLifecycle attributes: auto-startup and phase. It has a reference to a custom org.springframework.integration.syslog.MessageConverter with an ID of converter and an error-channel. Also notice the udp-attributes child element. You can set various UDP attributes here, as defined in Table 34.2, “UDP Inbound Channel Adapter Attributes”.

[Note]Note

When you use the udp-attributes element, you must provide the port attribute there rather than on the inbound-channel-adapter element itself.

The following example shows a TCP adapter that sends messages to channel fromSyslog:

<int-syslog:inbound-channel-adapter id="TcpSyslog"
	protocol="tcp"
	channel="fromSyslog"
	connection-factory="cf" />

<int-ip:tcp-connection-factory id="cf" type="server" port="1514" />

It also shows how to reference an externally defined connection factory, which can be used for advanced configuration (socket keep-alive and other uses). For more information, see Section 34.3, “TCP Connection Factories”.

[Note]Note

The externally configured connection-factory must be of type server, and the port is defined there rather than on the inbound-channel-adapter element itself.

The following example shows a TCP adapter that sends messages to channel fromSyslog:

<int-syslog:inbound-channel-adapter id="rfc5424Tcp"
	protocol="tcp"
	channel="fromSyslog"
	connection-factory="cf"
	converter="rfc5424" />

<int-ip:tcp-connection-factory id="cf"
	using-nio="true"
	type="server"
	port="1514"
	deserializer="rfc6587" />

<bean id="rfc5424" class="org.springframework.integration.syslog.RFC5424MessageConverter" />

<bean id="rfc6587" class="org.springframework.integration.syslog.inbound.RFC6587SyslogDeserializer" />

The preceding example is configured to use the RFC 5424 converter and is configured with a reference to an externally defined connection factory with the RFC 6587 deserializer (required for RFC 5424).