The stackdriver() destination of syslog-ng PE can send log messages to the Google Stackdriver cloud. Google Stackdriver is a widely used metrics, event, and log aggregator and analyzer system. The stackdriver destination is available in syslog-ng PE version 7.0.14 and later.

How the stackdriver() destination works

The stackdriver() destination uses the HTTP REST API to perform OAuth2 authentication to Google Stackdriver and obtains an access token from Stackdriver using the key specified in a JSON file. This access token is required to send logs to Stackdriver using the Stackdriver Logging API.

The syslog-ng PE application automatically refreshes the token when it expires (usually every 60 minutes). The syslog-ng PE application stores the token it obtains, even if you restart or reload syslog-ng PE. If you change the JSON key on your syslog-ng PE host, syslog-ng PE will start using the new key only when the stored access token expires or becomes invalid.

By default, syslog-ng PE uses the default system CA certificate store to validate the certificate sent by Google Stackdriver. If the Certificate Authority of the certificate sent by Google Stackdriver is not available on your host, you must download the CA certificate and add it to the certificate store. The location of the certificate store depends on your platform. Most commonly, it is one of the following (or a similar location):

  • /etc/ssl/certs/

  • /etc/pki/ca-trust/

  • /etc/pki/tls/certs/

Limitations

  • The log_id() option of the destination currently does not support macros or templates, only strings. As a result, every log entry has the same log id.

  • Currently the following resource types are supported: generic_node, generic_task, and global. You can configure other resource types, but they are untested.

  • Each syslog-ng PE stackdriver() destination can use only one resource type. If you want to send logs using multiple resource types, you must configure multiple stackdriver() destinations.

  • When referring to options in the syslog-ng PE configuration file, the hyphen (-) and underscore (_) characters are usually interchangeable. In the stackdriver destination, you must use underscore (_) in the options that syslog-ng PE passes directly to Google Stackdriver. These options are the following:

    • gcp_auth_header and its contents

    • log_id

    • project_id

    • resource() and its contents.

NOTE: Typically, only the central syslog-ng PE server uses this destination. For more information on the server mode, see Server mode.

Declaration
destination d_stackdriver {
  stackdriver(
    gcp_auth_header(
      credentials("<path-to-the-service.json>")
    )
    log_id("<folder-name-for-logs-in-stackdriver>")
    resource(
      project_id("<identifier-of-the-GCP-project>")
      <parameters-of-the-monitored-resource>
    )
  );
};
Example: Sending log messages to Google Stackdriver

Using a generic_node() resource type to send log messages to Google Stackdriver

destination d_stackdriver {
  stackdriver(
    gcp_auth_header(
      credentials("/opt/syslog-ng/etc/service.json")
    )
    log_id("123456")
    resource(
      generic_node(
        project_id("my-test-project")
        location("EU/Budapest")
        namespace("my cluster")
        node_id("$HOST")
      )
    )
    [...]
  );
};
Batch size

The batch-lines(), batch-lines(), and batch-timeout() options of the destination determine how many log messages syslog-ng PE sends in a batch. The batch-lines() option determines the maximum number of messages syslog-ng PE puts in a batch in. This can be limited based on size and time:

  • syslog-ng PE sends a batch every batch-timeout() milliseconds, even if the number of messages in the batch is less than batch-lines(). This ensures that the destination receives every message in a timely manner even if suddenly there are no more messages.

  • syslog-ng PE sends the batch if the total size of the messages in the batch reaches batch-bytes() bytes.

To increase the performance of the destination, increase the number of worker threads for the destination using the workers() option, or adjust the batch-bytes(), batch-lines(), batch-timeout() options.