Logging

Defaults

By default, Gate logs in json format to stderr with log level info, equivalent to:

Environment variables

GATE_LOG_FORMAT=json
GATE_LOG_LEVEL=info
GATE_LOG_OUTPUTS_0_SINK=stderr

HCL

gate = {
  log = {
    format = "json"
    level  = "info"
    outputs = [
      {
        sink = "stderr"
      }
    ]
  }
}

JSON

{
  "gate": {
    "log": {
      "format": "json",
      "level": "info",
      "outputs": [
        {
          "sink": "stderr"
        }
      ]
    }
  }
}

TOML

[gate.log]
format = "json"
level = "info"

[[gate.log.outputs]]
sink = "stderr"

YAML

gate:
  log:
    format: json
    level: info
    outputs:
      - sink: stderr

Supported Log Levels

• panic
• fatal
• error
• warn
• info
• debug
• trace

caution

trace and debug logs may contain sensitive information, such as data included in request headers. Only use these levels in environments where you can safely print the configuration.

Supported Log Formats

• text
• json

Supported Sinks

• stderr
• stdout
• syslog

Multiple Outputs

You can configure multiple log outputs, each with a different log level, file format and sink, overriding the defaults. The format and level parameters are optional for outputs and, if not specified, take the values of the top-level log.format and log.level.

For example, the following configuration outputs trace and higher severity logs (i.e., all logs) to stdout in textual format, while warnings and higher severity logs are written to stderr as JSON:

Environment variables

GATE_LOG_OUTPUTS_0_SINK=stdout
GATE_LOG_OUTPUTS_0_FORMAT=text
GATE_LOG_OUTPUTS_0_LEVEL=trace

GATE_LOG_OUTPUTS_1_SINK=stderr
GATE_LOG_OUTPUTS_1_FORMAT=json
GATE_LOG_OUTPUTS_1_LEVEL=warn

HCL

gate = {
  log = {
    outputs = [
      {
        sink = "stdout"
        format = "text"
        level = "trace"
      },
      {
        sink = "stderr"
        format = "json"
        level = "warn"
      }
    ]
  }
}

JSON

{
  "gate": {
    "log": {
      "outputs": [
        {
          "sink": "stdout",
          "format": "text",
          "level": "trace"
        },
        {
          "sink": "stderr",
          "format": "json",
          "level": "warn"
        }
      ]
    }
  }
}

TOML

[[gate.log.outputs]]
sink = "stdout"
format = "text"
level = "trace"

[[gate.log.outputs]]
sink = "stderr"
format = "json"
level = "warn"

YAML

gate:
  log:
    outputs:
      - sink: stdout
        format: text
        level: trace
      - sink: stderr
        format: json
        level: warn

Logging to Standard Streams

Gate supports logging to stdout and stderr.

Buffering

By default, the output of the Gate's standard streams is "unbuffered", only relying on the stream buffers provided by the operating system.
If your application logs to standard streams faster than your infrastructure or collectors can consume, you can configure Gate to add its own buffering by using the sink-specific parameters.buffer_size.

In the following example the stdout sink has an extra Gate-managed buffer of 64KiB.

Environment variables

GATE_LOG_FORMAT=text
GATE_LOG_LEVEL=trace
GATE_LOG_OUTPUTS_0_SINK=stdout
GATE_LOG_OUTPUTS_0_PARAMETERS_BUFFER_SIZE=65536

HCL

gate = {
  log = {
    format = "text"
    level = "trace"
    outputs = [
      {
        sink = "stdout"
        parameters = {
          buffer_size = 65535
        }
      }
    ]
  }
}

JSON

{
  "gate": {
    "log": {
      "format": "text",
      "level": "trace",
      "outputs": [
        {
          "sink": "stdout",
          "parameters": {
            "buffer_size": 65535
          }
        }
      ]
    }
  }
}

TOML

[gate.log]
format = "text"
level = "trace"

[[gate.log.outputs]]
sink = "stdout"
parameters.buffer_size = 65535

YAML

gate:
  log:
    format: text
    level: trace
    outputs:
      - sink: stdout
        
        parameters:
          buffer_size: 65535

Logging to SysLog

Gate supports shipping logs to an RFC5424-compliant SysLog server using the syslog sink type. The supported configuration values are:

Environment variables

GATE_LOG_OUTPUTS_0_SINK=syslog
GATE_LOG_OUTPUTS_0_FORMAT=<Log format>
GATE_LOG_OUTPUTS_0_LEVEL=<Log level>
GATE_LOG_OUTPUTS_0_PARAMETERS_NETWORK=<Network>
GATE_LOG_OUTPUTS_0_PARAMETERS_ADDRESS=<Address>
GATE_LOG_OUTPUTS_0_PARAMETERS_FACILITY=<SysLog facility>
GATE_LOG_OUTPUTS_0_PARAMETERS_TAG=<SysLog tag>

HCL

gate = {
  log = {
    outputs = [
      {
        sink = "syslog"
        format = "<Log format>"
        level = "<Log level>"
        parameters = {
          network = "<Network>"
          address = "<Address>"
          facility = <SysLog facility>
          tag = "<SysLog tag>"
        }
      }
    ]
  }
}

JSON

{
  "gate": {
    "log": {
      "outputs": [
        {
          "sink": "syslog",
          "format": "<Log format>",
          "level": "<Log level>",
          "parameters": {
            "network": "<Network>",
            "address": "<Address>",
            "facility": <SysLog facility>,
            "tag": "<SysLog tag>"
          }
        }
      ]
    }
  }
}

TOML

[[gate.log.outputs]]
sink = "syslog"
format = "<Log format>"
level = "<Log level>"
parameters.network = "<Network>"
parameters.address = "<Address>"
parameters.facility = <SysLog facility>
parameters.tag = "<SysLog tag>"

YAML

gate:
  log:
    outputs:
      - sink: syslog
        format: <Log format>
        level: <Log level>
        parameters:
          network: <Network>
          address: <Address>
          facility: <SysLog facility>
          tag: <SysLog tag>

SysLog configuration details:

• <Log format> supports the same values as all other sinks: trace, debug, info, warn, error, fatal, panic
• <Log level> supports the same values as all other sinks: text, json
• <Network> is the network type to connect to the SysLog server:
  • tcp
  • tcp4 (IPv4-only)
  • tcp6 (IPv6-only)
  • udp
  • udp4 (IPv4-only)
  • udp6
• <Address> is the network address of the remote SysLog server in host:port format (e.g., syslog.example.com:6514)
• <SysLog facility> is the SysLog facility value: between 0 and 23 (included)
• <SysLog tag> is the SysLog application tag (also referred to as application name): any string value identifying the current Gate instance

By default, Gate connects to the SysLog server over TLS (v1.2 and above). You can skip certificate verification or disable TLS entirely using the tls.insecure and tls.disabled boolean parameters:

Environment variables

GATE_LOG_OUTPUTS_0_SINK=syslog
...
GATE_LOG_OUTPUTS_0_PARAMETERS_TLS_INSECURE=<Skip certificate verification>
GATE_LOG_OUTPUTS_0_PARAMETERS_TLS_DISABLED=<Disable TLS>

HCL

gate = {
  log = {
    outputs = [
      {
        sink = "syslog"
        ...
        parameters = {
          ...
          tls = {
            insecure = <Skip certificate verification>
            disabled = <Disable TLS>
          }
        }
      }
    ]
  }
}

JSON

{
  "gate": {
    "log": {
      "outputs": [
        {
          "sink": "syslog",
          ...
          "parameters": {
            ...
            "tls": {
              "insecure": <Skip certificate verification>,
              "disabled": <Disable TLS>
            }
          }
        }
      ]
    }
  }
}

TOML

[[gate.log.outputs]]
sink = "syslog"
...
parameters.tls.insecure = <Skip certificate verification>
parameters.tls.disabled = <Disable TLS>

YAML

gate:
  log:
    outputs:
      - sink: syslog
        ...
        parameters:
          ...
          tls:
            insecure: <Skip certificate verification>
            disabled: <Disable TLS>

Priority

The SysLog priority value of each message is a combination of the "facility" value from the configuration, and the "severity" value of each log line. In particular, Gate maps log levels to SysLog severity values as follows:

• panic, fatal: Critical
• error: Error
• warn: Warning
• info: Informational
• debug, trace: Debug

Connection management

Gate automatically manages the connection to the remote SysLog server. In particular, it will try to connect immediately on start-up and fail to initialize if a connection cannot be established. If a connection or communication error is detected, Gate will automatically try to reconnect, with an exponential backoff delay. Gate continues to log without interruptions even while not connected to the SysLog server, as described in the message queueing section.

Message Queueing

To avoid a negative impact on performance due to slow or intermittent connectivity with the SysLog server, Gate's syslog sink handles logs asynchronously. Any logging operation simply adds the log entry to a transmission queue. The log is then asynchronously sent to the SysLog server as soon as a connection becomes available. Refer to the connection management section for more details.

The transmission queue holds up to 64K log entries, but it may fill up entirely under certain circumstances, such as a prolonged disconnection from the SysLog server, or the server being consistently slow at ingesting messages. In this case, Gate prioritizes continuity of operations, dropping the oldest message in the queue in favor of each new entry.

Metadata

Gate populates the following fields for all outgoing SysLog messages:

• HOSTNAME: hostname of the machine as provided by the operating system
• APP-NAME: application tag as specified in the syslog sink configuration parameters
• PROCID: the PID of the Gate process
• TIMESTAMP: current time with micro-second precision, the maximum allowed by the SysLog protocol

On top of the information provided in the header, Gate takes advantage of the SysLog Structured Data mechanism to enrich each message with the following additional information:

• origin:
  • ip: the local IP address of the connection to the SysLog server
  • enterpriseId: always equal to 60696, SlashID's Private Enterprise Number as assigned by IANA
  • software: always equal to gate
  • swVersion: a string representing Gate's version in the [version]-[commit] format
• meta:
  • sequenceId: the sequence number for the message (starts at 1 and wraps around after 2147483647)

You can find more information about logging in the Monitoring page.

Debugging Configuration Issues

When log level is set to debug, the entire configuration is printed at the start.

caution

Gate's configuration may include sensitive data. Set log-level to debug only in environments where you can safely print the configuration.