
[[ga-events-sources-syslog]]
= Syslog Messages
:description: All about events and syslog messages in {page-component-title}: parsers and RadixTreeSyslogParser parameters and tokens.

Syslog messages sent over the network to {page-component-title} can be transformed into events according to preconfigured rules.

IMPORTANT: xref:reference:daemons/daemon-config-files/syslogd.adoc[Syslogd], which enables {page-component-title} to receive syslog messages over the network, must be enabled for this functionality to work.
This daemon is disabled by default.

IMPORTANT: {page-component-title} works natively with UDP syslog reception. If you need TCP syslog reception then receiving the data with a TCP compatible syslog receiver such as rsyslog and forwarding them to {page-component-title} as UDP is possible but may require the use of the xref:operation:deep-dive/events/event-translator.adoc[Event Translator] to assign events to the correct host.

== Parsers

You can use parsers to convert syslog message fields into {page-component-title} event fields.

[caption=]
.Syslog message parsers
[options="autowidth"]
|===
| Parser | Description

| org.opennms.netmgt.syslogd.CustomSyslogParser
| Uses a regex statement to parse the syslog header.

| org.opennms.netmgt.syslogd.RadixTreeSyslogParser
| Uses an internal list of Grok-style statements to parse the syslog header.

| org.opennms.netmgt.syslogd.SyslogNGParser
| Strictly parses messages in the default pattern of syslog-ng.

| org.opennms.netmgt.syslogd.Rfc5424SyslogParser
| Strictly parses the RFC 5424 format for syslog messages.
|===

=== RadixTreeSyslogParser

The `RadixTreeSyslogParser` normally uses a set of internally defined patterns to parse multiple syslog message formats.
To customize the set of patterns, modify `$\{OPENNMS_HOME}/etc/syslogd-grok-patterns.txt`.

The patterns are defined in Grok-style statements where each token is defined by a `%{PATTERN:semantic}` clause.
Whitespace in the pattern will match `0...n` whitespace characters, and character literals in the pattern will match the corresponding characters.
The `%` character literal must be escaped by using a backslash (for example, `\%`).

NOTE: The `RadixTreeSyslogParser` Grok implementation supports only a limited number of pattern types.
However, these patterns should be sufficient to parse any syslog message format.

Arrange the patterns in the file from most specific to least specific, since the first pattern to successfully match the syslog message will be used to construct the {page-component-title} event.

[caption=]
.`RadixTreeSyslogParser` parameter patterns
[options="autowidth"]
|===
| Pattern | Description

| HOSTNAME
| String containing only valid hostname characters (alphanumeric plus '.', '-' and '_').

| HOSTNAMEORIP
| String containing only valid hostname characters or IP address characters (IPv4 or IPv6).

| INT
| Positive integer

| IPADDRESS
| String containing only valid IP address characters (IPv4 or IPv6).

| MONTH
| Three-character English abbreviation of the month.

| NOSPACE
| String that contains no whitespace.

| STRING
| String.
Because this matches any character, it must be followed by a delimiter in the pattern string.

| WHITESPACE
| String that contains only whitespace (spaces and tabs).
|===

[caption=]
.`RadixTreeSyslogParser` semantic tokens
[cols="1,3"]
|===
| Semantic Token | Description

| day
| Two-digit day of month (01-31)

| facilityPriority
| Facility-priority integer

| hostname
| String hostname (unqualified or FQDN), IPv4 address, or IPv6 address.

| hour
| Two-digit hour of day (00-23)

| message
| Remaining string message.

| messageId
| String message ID

| minute
| Two-digit minute (0-59)

| month
| Two-digit month (01-12)

| parm*
| Generic string parameter where the parameter's key is the identifier following "parm" in the semantic token (for example, `parmComponentId` maps to a string parameter with key "ComponentId").

| processId
| String process ID

| processName
| String process name

| second
| Two-digit second (00-59)

| secondFraction
| One- to six-digit fractional second value as a string.

| timezone
| String timezone value

| version
| Version

| year
| Four-digit year
|===

== Examples

There are some sample syslog event parsing definitions in `$\{OPENNMS_HOME}/etc/syslog` you can use as a base for customizing your own event parsing.

=== Discard messages

If there are syslog messages you do not want to keep, you can set the UEI to `DISCARD-MATCHING-MESSAGES`.
This will flag the message as `donotpersist` so it will be dropped and not written to the database.

[source, xml]
----
<ueiMatch>
    <match type="regex" expression="^.*(\[api-status-warning\].*deprecated).*$" />
    <uei>DISCARD-MATCHING-MESSAGES</uei>
</ueiMatch>
----

=== Facility/Severity filtering

If you have similar messages coming in with different syslog facility or severity flags, but only want to capture events that match a specific value, you can specify a filter in the syslogd configuration.

[source, xml]
----
<ueiMatch>
    <facility>local0</facility>
    <severity>Warning</severity>
    <match type="regex" expression="^.*Certificate (.*) expired on (.*)$" />
    <uei>uei.opennms.org/custom/syslog/certExpired</uei>
    <parameter-assignment matching-group="1" parameter-name="certName" />
    <parameter-assignment matching-group="2" parameter-name="expireDate" />
</ueiMatch>
----
