Syslog

The Syslog destination writes syslog messages to a Syslog server.

For example, you might have network devices that write log messages to flat files. You need to send these flat files to a centralized Syslog server, but the messages first must be converted to syslog messages. You design a pipeline that reads the flat files, performs some processing on the data, and then uses a Syslog destination that formats the data into syslog messages and writes the messages to the Syslog server.

When you configure the Syslog destination, you define the host name and port number of the Syslog server. You also define whether to use the UDP or TCP protocol to send messages to the server. If using the TCP protocol, you can optionally enable SSL/TLS for the destination.

You construct the syslog message content by specifying expressions that evaluate to the message values - such as the timestamp, facility code, severity level, message ID, and the log message itself.

You'll typically want to write the log message using the text data format. However, if needed, you can configure the Syslog destination to use a different data format for the log message.

Protocol

You configure the Syslog destination to use one of the following protocols to send messages to the Syslog server:
UDP protocol
When the destination uses the UDP protocol, you select the syslog message format that the destination uses. Choose one of the following formats:
TCP protocol
When the destination uses the TCP protocol, the destination uses the RFC 6587 message format.
When using the TCP protocol, you can also enable SSL/TLS for the destination.

Enabling SSL/TLS

If you configure the Syslog destination to use the TCP protocol, you can enable the destination to use SSL/TLS to connect to the Syslog server.

  1. In the Syslog Connection tab, select the Enable SSL property.
  2. If the Syslog server certificate is signed by a private CA or not trusted by the default Java truststore, create a custom truststore file or modify a copy of the default Java truststore file to add the CA to the file. Then configure Data Collector to use the modified truststore file.

    By default, Data Collector uses the Java truststore file located in $JAVA_HOME/jre/lib/security/cacerts. If your certificate is signed by a CA that is included in the default Java truststore file, you do not need to create a truststore file and can skip this step.

    In these steps, we show how to modify the default truststore file to add an additional CA to the list of trusted CAs. If you prefer to create a custom truststore file, see the keytool documentation.
    Note: If Data Collector is already configured to use a custom truststore file to enable HTTPS or for secure connections to an LDAP server, then simply add this additional CA to the same modified truststore file.
    1. Use the following command to set the JAVA_HOME environment variable:
      export JAVA_HOME=<Java home directory>
    2. Use the following command to set the SDC_CONF environment variable:
      export SDC_CONF=<Data Collector configuration directory>
      For example, for an RPM installation use:
      export SDC_CONF=/etc/sdc
    3. Use the following command to copy the default Java truststore file to the Data Collector configuration directory:
      cp "${JAVA_HOME}/jre/lib/security/cacerts" "${SDC_CONF}/truststore.jks"
    4. Use the following keytool command to import the CA certificate into the truststore file:
      keytool -import -file <Syslog certificate> -trustcacerts -noprompt -alias <Syslog alias> -storepass <password> -keystore "${SDC_CONF}/truststore.jks"
      For example:
      keytool -import -file  mySyslogServer.pem -trustcacerts -noprompt -alias MySyslogServer -storepass changeit -keystore "${SDC_CONF}/truststore.jks"
    5. Define the following options in the SDC_JAVA_OPTS environment variable:
      • javax.net.ssl.trustStore - Path to the truststore file on the Data Collector machine.
      • javax.net.ssl.trustStorePassword - Truststore password.

      Modify environment variables using the method required by your installation type.

      For example, define the options as follows:
      export SDC_JAVA_OPTS="-Djavax.net.ssl.trustStore=/etc/sdc/truststore.jks -Djavax.net.ssl.trustStorePassword=mypassword -Xmx1024m -Xms1024m -server -XX:-OmitStackTraceInFastThrow ${SDC_JAVA_OPTS}"

      Or to avoid saving the password in the export command, save the password in a text file and then define the truststore password option as follows: -Djavax.net.ssl.trustStorePassword=$(cat passwordfile.txt)

      Then ensure that the password file is readable only by the user executing the export command.

    6. Restart Data Collector to enable the changes to the environment variable.

Message Content

A syslog message includes fields such as a timestamp, facility code, severity level, message ID, and the log message itself. You construct the syslog message content by specifying the message values or expressions that evaluate to the message values.

You'll typically want to write the log message using the text data format. However, if needed, you can configure the Syslog destination to use a different data format for the log message.

Use the Message tab to configure the destination to write the log message in one of the following formats:

Text message

To write the log message as text, clear the Use Non-text Message Format property on the Message tab, and then for the Message Text property, define an expression that evaluates to the log message.

For example, if a field named log_msg contains the message, define the following expression:

${record:value('/log_msg')}

Enter values or expressions for the remaining message properties. In most cases, you'll want to define expressions to call fields in the record that contain the message values.

For example, the following image shows a Syslog destination configured to use the text data format for the log message. The image also shows a few of the remaining message properties, including the timestamp and host name defined with expressions and the severity level set to the default value of 6:

Non-text message

To write the log message using a different data format, select the Use Non-text Message Format property on the Message tab and then configure the data format on the Data Format tab.

When you use a non-text message format, the data used for the log message field in the syslog message depends on the chosen data format on the Data Format tab. For the Binary data format, the destination writes data from a single field in the record to the log message field. For the remaining data formats, the destination writes data from all fields in the record to the log message field.

Enter values or expressions for the remaining message properties. In most cases, you'll want to define expressions to call fields in the record that contain the message values.

For example, the following image shows a Syslog destination configured to use a non-text message format. The chosen data format is configured on the Data Format tab:

Data Formats

If you choose to write messages using a non-text format, you can use the following data formats:

Avro
The destination writes records based on the Avro schema. You can use one of the following methods to specify the location of the Avro schema definition:
  • In Pipeline Configuration - Use the schema that you provide in the stage configuration.
  • In Record Header - Use the schema included in the avroSchema record header attribute.
  • Confluent Schema Registry - Retrieve the schema from Confluent Schema Registry. The Confluent Schema Registry is a distributed storage layer for Avro schemas. You can configure the destination to look up the schema in the Confluent Schema Registry by the schema ID or subject.

    If using the Avro schema in the stage or in the record header attribute, you can optionally configure the destination to register the Avro schema with the Confluent Schema Registry. You can also optionally include the schema definition in the message. Omitting the schema definition can improve performance, but requires the appropriate schema management to avoid losing track of the schema associated with the data.

You can compress data with an Avro-supported compression codec. When using Avro compression, avoid using any other compression properties in the destination.
Binary
The destination writes binary data from a single field in the record.
Delimited
The destination writes records as delimited data. When you use this data format, the root field must be list or list-map.
You can use the following delimited format types:
  • Default CSV - File that includes comma-separated values. Ignores empty lines in the file.
  • RFC4180 CSV - Comma-separated file that strictly follows RFC4180 guidelines.
  • MS Excel CSV - Microsoft Excel comma-separated file.
  • MySQL CSV - MySQL comma-separated file.
  • PostgreSQL CSV - PostgreSQL comma-separated file.
  • PostgreSQL Text - PostgreSQL text file.
  • Tab-Separated Values - File that includes tab-separated values.
  • Custom - File that uses user-defined delimiter, escape, and quote characters.
JSON
The destination writes records as JSON data. You can use one of the following formats:
  • Array - Each file includes a single array. In the array, each element is a JSON representation of each record.
  • Multiple objects - Each file includes multiple JSON objects. Each object is a JSON representation of a record.
Protobuf
Writes one record in a message. Uses the user-defined message type and the definition of the message type in the descriptor file to generate the message.
For information about generating the descriptor file, see Protobuf Data Format Prerequisites.
SDC Record
The destination writes records in the SDC Record data format.
XML
The destination creates a valid XML document for each record. The destination requires the record to have a single root field that contains the rest of the record data. For details and suggestions for how to accomplish this, see Record Structure Requirement.

The destination can include indentation to produce human-readable documents. It can also validate that the generated XML conforms to the specified schema definition. Records with invalid schemas are handled based on the error handling configured for the destination.

Configuring a Syslog Destination

Configure a Syslog destination to write syslog messages to a Syslog server.

  1. In the Properties panel, on the General tab, configure the following properties:
    General Property Description
    Name Stage name.
    Description Optional description.
    Required Fields Fields that must include data for the record to be passed into the stage.
    Tip: You might include fields that the stage uses.

    Records that do not include all required fields are processed based on the error handling configured for the pipeline.

    Preconditions Conditions that must evaluate to TRUE to allow a record to enter the stage for processing. Click Add to create additional preconditions.

    Records that do not meet all preconditions are processed based on the error handling configured for the stage.

    On Record Error Error record handling for the stage:
    • Discard - Discards the record.
    • Send to Error - Sends the record to the pipeline for error handling.
    • Stop Pipeline - Stops the pipeline. Not valid for cluster pipelines.
  2. On the Syslog Connection tab, configure the following properties:
    Syslog Connection Property Description
    Protocol Protocol to send messages to the Syslog server:
    • UDP
    • TCP
    Syslog Host Syslog server hostname.
    Syslog Port Syslog server port number.
    Message Format For the UDP protocol, syslog message format to use:
    • RFC 5424
    • RFC 3164

    If using the TCP protocol, the destination uses the RFC 6587 message format.

    Socket Connection Timeout (ms) For the TCP protocol, maximum time in milliseconds to wait for a socket connection.
    TCP Connection Retries For the TCP protocol, maximum number of times to retry a TCP connection.
    Enable SSL For the TCP protocol, enables SSL/TLS between Data Collector and the Syslog server.

    If the Syslog server certificate is signed by a private CA or not trusted by the default Java truststore, you also must define the truststore file and password in the SDC_JAVA_OPTS environment variable, as described in Enabling SSL/TLS.

  3. On the Message tab, configure the following properties:
    Message Property Description
    Use Non-Text Message Format Use a non-text data format for the log message. When selected, configure the data format on the Data Format tab.

    Clear the property to use the text data format for the log message. In most cases, you'll want to use the text data format.

    Message Text For the text data format, the log message to include in the syslog message.

    Enter the message or enter an expression that evaluates to the message.

    Timestamp Timestamp for the syslog message.

    Default is the processing time, defined with the expression ${time:now()}. To use a time associated with the record, use an expression that calls a field and resolves to a datetime value, such as ${record:value("/Timestamp")}.

    Hostname Host name to use for the syslog message.

    Enter the host name or enter an expression that evaluates to the hostname.

    Severity Level Numerical code from 0 through 7 representing the severity level for the syslog message.

    For a list of codes, see https://tools.ietf.org/html/rfc5424#section-6.2.1.

    Enter the numerical code or enter an expression that evaluates to the code.

    Syslog Facility Numerical code from 0 through 23 representing the facility for the syslog message.

    For a list of codes, see https://tools.ietf.org/html/rfc5424#section-6.2.1.

    Enter the numerical code or enter an expression that evaluates to the code.

    Application Name Application name to use for the syslog message.

    Enter the application name or enter an expression that evaluates to the name.

    Message ID Message ID to use for the syslog message.

    Enter the message ID or enter an expression that evaluates to the ID.

    Process ID Process ID to use for the syslog message.

    Enter the process ID or enter an expression that evaluates to the ID.

  4. If using a non-text data format for the log message, click the Data Format tab, and then configure the following property:
    Data Format Property Description
    Data Format Format of data to be written. Use one of the following options:
    • Avro
    • Binary
    • Delimited
    • JSON
    • Protobuf
    • SDC Record
    • XML
  5. For Avro data, on the Data Format tab, configure the following properties:
    Avro Property Description
    Avro Schema Location Location of the Avro schema definition to use when writing data:
    • In Pipeline Configuration - Use the schema that you provide in the stage configuration.
    • In Record Header - Use the schema in the avroSchema record header attribute. Use only when the avroSchema attribute is defined for all records.
    • Confluent Schema Registry - Retrieve the schema from the Confluent Schema Registry.
    Avro Schema Avro schema definition used to write the data.

    You can optionally use the runtime:loadResource function to use a schema definition stored in a runtime resource file.

    Register Schema Select to register a new Avro schema with the Confluent Schema Registry.
    Schema Registry URLs Confluent Schema Registry URLs used to look up the schema or to register a new schema. To add a URL, click Add. Use the following format to enter the URL:
    http://<host name>:<port number>
    Look Up Schema By Method used to look up the schema in the Confluent Schema Registry:
    • Subject - Look up the specified Avro schema subject.
    • Schema ID - Look up the specified Avro schema ID.
    Schema Subject Avro schema subject to look up or to register in the Confluent Schema Registry.

    If the specified subject to look up has multiple schema versions, the origin uses the latest schema version for that subject. To use an older version, find the corresponding schema ID, and then set the Look Up Schema By property to Schema ID.

    Schema ID Avro schema ID to look up in the Confluent Schema Registry.
    Include Schema Includes the schema in each message.
    Note: Omitting the schema definition can improve performance, but requires the appropriate schema management to avoid losing track of the schema associated with the data.
    Avro Compression Codec The Avro compression type to use.

    When using Avro compression, do not enable other compression available in the destination.

  6. For binary data, on the Data Format tab, configure the following property:
    Binary Property Description
    Binary Field Path Field that contains the binary data.
  7. For delimited data, on the Data Format tab, configure the following properties:
    Delimited Property Description
    Delimiter Format Format for delimited data:
    • Default CSV - File that includes comma-separated values. Ignores empty lines in the file.
    • RFC4180 CSV - Comma-separated file that strictly follows RFC4180 guidelines.
    • MS Excel CSV - Microsoft Excel comma-separated file.
    • MySQL CSV - MySQL comma-separated file.
    • PostgreSQL CSV - PostgreSQL comma-separated file.
    • PostgreSQL Text - PostgreSQL text file.
    • Tab-Separated Values - File that includes tab-separated values.
    • Custom - File that uses user-defined delimiter, escape, and quote characters.
    Header Line Indicates whether to create a header line.
    Replace New Line Characters Replaces new line characters with the configured string.

    Recommended when writing data as a single line of text.

    New Line Character Replacement String to replace each new line character. For example, enter a space to replace each new line character with a space.

    Leave empty to remove the new line characters.

    Delimiter Character Delimiter character for a custom delimiter format. Select one of the available options or use Other to enter a custom character.

    You can enter a Unicode control character using the format \uNNNN, where ​N is a hexadecimal digit from the numbers 0-9 or the letters A-F. For example, enter \u0000 to use the null character as the delimiter or \u2028 to use a line separator as the delimiter.

    Default is the pipe character ( | ).

    Escape Character Escape character for a custom delimiter format. Select one of the available options or use Other to enter a custom character.

    Default is the backslash character ( \ ).

    Quote Character Quote character for a custom delimiter format. Select one of the available options or use Other to enter a custom character.

    Default is the quotation mark character ( " ).

    Charset Character set to use when writing data.
  8. For JSON data, on the Data Format tab, configure the following property:
    JSON Property Description
    JSON Content Determines how JSON data is written:
    • JSON Array of Objects - Each file includes a single array. In the array, each element is a JSON representation of each record.
    • Multiple JSON Objects - Each file includes multiple JSON objects. Each object is a JSON representation of a record.
    Charset Character set to use when writing data.
  9. For protobuf data, on the Data Format tab, configure the following properties:
    Protobuf Property Description
    Protobuf Descriptor File Descriptor file (.desc) to use. The descriptor file must be in the Data Collector resources directory, $SDC_RESOURCES.

    For more information about environment variables, see Data Collector Environment Configuration. For information about generating the descriptor file, see Protobuf Data Format Prerequisites.

    Message Type The fully-qualified name for the message type to use when writing data.

    Use the following format: <package name>.<message type>.

    Use a message type defined in the descriptor file.
    Write Delimiter Writes a delimiter after each message.
  10. For XML data, on the Data Format tab, configure the following properties:
    XML Property Description
    Pretty Format Adds indentation to make the resulting XML document easier to read. Increases the record size accordingly.
    Validate Schema Validates that the generated XML conforms to the specified schema definition. Records with invalid schemas are handled based on the error handling configured for the destination.
    Important: Regardless of whether you validate the XML schema, the destination requires the record in a specific format. For more information, see Record Structure Requirement.
    XML Schema The XML schema to use to validate records.