Configure logs

On this page

This page describes how to configure CockroachDB logs with the --log or log-config-file flag and a YAML payload. Most logging behaviors are configurable, including:

• The log sinks that output logs to different locations, including over the network.
• The logging channels that are mapped to each sink.
• The format used by the log messages.
• The redaction of log messages.

For examples of how these settings can be used in practice, see Logging Use Cases.

Flag

To configure the logging behavior of a cockroach command, include one of these flags with the command:

• --log={yaml}, where {yaml} is the YAML payload
• --log-config-file={yaml-file}, where {yaml-file} is the path to a YAML file

YAML payload

All log settings for a cockroach command are specified with a YAML payload in one of the following formats:

• Block format, where each parameter is written on a separate line. For example, after creating a file logs.yaml, pass the YAML values with either --log-config-file or --log:

  $ cockroach start-single-node --certs-dir=certs --log-config-file=logs.yaml
  

  $ cockroach start-single-node --certs-dir=certs --log="$(cat logs.yaml)"
  

• Inline format, where all parameters are specified on one line. For example, to generate an ops log file that collects the OPS and HEALTH channels (overriding the file groups defined for those channels in the default configuration):

  $ cockroach start-single-node --certs-dir=certs --log="sinks: {file-groups: {ops: {channels: [OPS, HEALTH]}}}"
  

  Note that the inline spaces must be preserved.

For clarity, this article uses the block format to describe the YAML payload, which has the overall structure:

file-defaults: ...       # defaults inherited by file sinks
fluent-defaults: ...     # defaults inherited by network sinks
sinks:
   file-groups: ...      # file sink definitions
   fluent-servers: ...   # network sink definitions
   stderr: ...           # stderr sink definitions
capture-stray-errors: ... # parameters for the stray error capture system

Configure log sinks

Log sinks route events from specified logging channels to destinations outside CockroachDB. These destinations currently include log files, Fluentd-compatible servers, and the standard error stream (stderr).

All supported output destinations are configured under sinks:

file-defaults: ...
fluent-defaults: ...
sinks:
  file-groups:
    {file group name}:
      channels: {channels}
      ...
  fluent-servers:
    {server name}:
      channels: {channels}
      ...
  stderr:
      channels: {channels}
      ...

All supported sink types use the following common sink parameters:

If not specified for a given sink, these parameter values are inherited from file-defaults (for file sinks) and fluent-defaults (for network sinks).

Output to files

CockroachDB can write messages to one or more log files.

file-groups specifies the channels that output to each log file, along with its output directory and other configuration details. For example:

file-defaults: ...
fluent-defaults: ...
sinks:
  file-groups:
    default:
      channels: [DEV]
    health:
      channels: [HEALTH]
      dir: health-logs
    ...

Along with the common sink parameters, each file group accepts the following parameters:

If not specified for a given file group, the parameter values are inherited from file-defaults (except channels, which uses the default configuration).

Log file naming

Log files are named in the following format:

{process}-{file group}.{host}.{user}.{start timestamp in UTC}.{process ID}.log

For example, a file group health will generate a log file that looks like this:

cockroach-health.work-laptop.worker.2021-03-15T15_24_10Z.024338.log

For each file group, a symlink points to the latest generated log file. It's easiest to refer to the symlink. For example:

cockroach-health.log

Access in DB Console

Known limitations

Log files can only be accessed in the DB Console if they are stored in the same directory as the file sink for the DEV channel.

Output to network

CockroachDB can send logs over the network to a Fluentd-compatible log collector (e.g., Elasticsearch, Splunk). fluent-servers specifies the channels that output to a server, along with its configuration details. For example:

file-defaults: ...
fluent-defaults: ...
sinks:
  fluent-servers:
    health:
      channels: [HEALTH]
      address: 127.0.0.1:5170
    ...

Along with the common sink parameters, each Fluentd server accepts the following parameters:

A Fluentd sink buffers at most one log entry and retries sending the event at most one time if a network error is encountered. This is just sufficient to tolerate a restart of the Fluentd collector after a configuration change under light logging activity. If the server is unavailable for too long, or if more than one error is encountered, an error is reported to the process's standard error output with a copy of the logging event, and the logging event is dropped.

For an example network logging configuration, see Logging use cases.

Output to stderr

CockroachDB can output messages to the standard error stream (stderr), which prints them to the machine's terminal but does not store them. stderr specifies the channels that output to the stream. For example:

file-defaults: ...
fluent-defaults: ...
sinks:
  stderr:
    channels: [DEV]

Along with the common sink parameters, stderr accepts the following parameters:

Because server start-up messages are always emitted at the start of the standard error stream, it is generally difficult to automate integration of stderr with log analyzers. We recommend using file logging or network logging instead of stderr when integrating with automated monitoring software.

Logging channel selection

Each sink can select multiple channels. The names of selected channels can be specified as a YAML array or as a string.

# Select just these two channels. Space is important.
channels: [OPS, HEALTH]

# Selection is case-insensitive.
channels: [ops, HeAlTh]

# Same configuration, as a YAML string. 
# Avoid space around commas when using the YAML inline format.
channels: OPS,HEALTH

# Same configuration, as a quoted string.
channels: 'OPS, HEALTH'

# Same configuration, as a multi-line YAML array.
channels:
- OPS
- HEALTH

To select all channels, using the all keyword:

channels: all
channels: 'all'
channels: [all]
channels: ['all']

To select all channels except for a subset, using the all except keyword prefix:

channels: all except ops,health
channels: all except [ops,health]
channels: 'all except ops, health'
channels: 'all except [ops, health]'

Configure logging defaults

When setting up a logging configuration, it's simplest to define shared parameters in file-defaults and fluent-defaults and override specific values as needed in file-groups, fluent-servers, and stderr. For a complete example, see the default configuration.

This section describes some recommended defaults.

Set file defaults

Defaults for log files are set in file-defaults, which accepts all common sink parameters and the file group parameters dir, max-file-size, max-group-size, and buffered-writes.

Logging directory

By default, CockroachDB adds log files to a logs subdirectory in the first on-disk store directory (default: cockroach-data):

cockroach-data/logs

In cloud deployments, the main data store will be subject to an IOPS budget. Adding logs to the store directory will excessively consume IOPS. For this reason, cloud deployments should output log files to a separate directory with fewer IOPS restrictions. You can override the default logging directory like this:

file-defaults:
  dir: /custom/dir/path/

File logging format

The default message format for log files is crdb-v2. Each crdb-v2 log message starts with a flat prefix that contains event metadata (e.g., severity, date, timestamp, channel), followed by the event payload. For details on the metadata, see Log formats.

If you plan to read logs programmatically, you can switch to a JSON or compact JSON format:

file-defaults:
  format: json

Set network defaults

Defaults for network sinks are set in fluent-defaults, which accepts all common sink parameters.

Note that the server parameters address and net are not specified in fluent-defaults:

• address must be specified for each sink under fluent-servers.
• net is not required and defaults to tcp.

Network logging format

The default message format for network output is json-fluent-compact. Each log message is structured as a JSON payload that can be read programmatically. The json-fluent-compact and json-fluent formats include a tag field that is required by the Fluentd protocol. For details, see Log formats.

fluent-defaults:
  format: json-fluent

Set logging levels

Log messages are associated with a severity level when they are generated. Each logging sink is configured to output messages that meet a minimum severity level, specified with filter. Messages with severity levels below the filter threshold do not enter logging channels and are discarded.

The default configuration uses the following severity levels for cockroach start and cockroach start-single-node:

• file-defaults and fluent-defaults each use filter: INFO. Since INFO is the lowest severity level, file and network sinks will emit all log messages.
• stderr uses filter: NONE and does not emit log messages.

You can also override the file-defaults and fluent-defaults severity levels on a per-sink basis. For example, use filter: NONE to disable logging for certain channels:

file-defaults: ...
fluent-defaults: ...
sinks:
  file-groups:
    dev:
      channels: [DEV]
      filter: NONE

Redact logs

CockroachDB can redact personally identifiable information (PII) from log messages. The logging system includes two parameters that handle this differently:

• redact is disabled by default. When enabled, redact automatically redacts sensitive data from logging output. We do not recommend enabling this on the DEV channel because it impairs our ability to troubleshoot problems.
• redactable is enabled by default. This places redaction markers around sensitive fields in log messages. These markers are recognized by cockroach debug zip and cockroach debug merge-logs, which aggregate CockroachDB log files and can be instructed to redact sensitive data from their output.

When collecting logs centrally (e.g., in data mining scenarios where non-privileged users have access to logs) or over a network (e.g., to an external log collector), it's safest to enable redact:

file-defaults:
  redact: true
fluent-defaults:
  redact: true

External log collectors can misinterpret the cockroach debug redaction markers, since they are specific to CockroachDB. To prevent this issue when using network sinks, disable redactable:

fluent-defaults:
  redactable: false

DEV channel

The DEV channel is used for debug and uncategorized messages. It can therefore be noisy and contain sensitive (PII) information.

We recommend configuring DEV separately from the other logging channels. When sending logs over the network, DEV logs should also be excluded from network collection.

In this example, the dev file group is reserved for DEV logs. These are output to a cockroach-dev.log file in a custom disk dir:

file-defaults: ...
fluent-defaults: ...
sinks:
  file-groups:
    dev:
      channels: [DEV]
      dir: /custom/dir/path/
    ...
  fluent-servers:
    ...

Stray error capture

Certain events, such as uncaught software exceptions (panics), bypass the CockroachDB logging system. However, they can be useful in troubleshooting. For example, if CockroachDB crashes, it normally logs a stack trace to what caused the problem.

To ensure that these stray errors can be tracked, CockroachDB does not send them to stderr by default. Instead, stray errors are output to a cockroach-stderr.log file in the default logging directory.

You can change these settings in capture-stray-errors:

file-defaults: ...
fluent-defaults: ...
sinks: ...
capture-stray-errors:
  enable: true
  dir: /custom/dir/path/

Default logging configuration

The YAML payload below represents the default logging behavior of cockroach start and cockroach start-single-node. To retain backward compatibility with v20.2 and earlier, these settings match the log filenames used in previous versions (except sql-auth, which should be changed to auth to match the log filename used in v20.2 and earlier).

file-defaults:
  max-file-size: 10MiB
  max-group-size: 100MiB
  buffered-writes: true
  filter: INFO
  format: crdb-v2
  redact: false
  redactable: true
  exit-on-error: true
  auditable: false
fluent-defaults:
  filter: INFO
  format: json-fluent-compact
  redact: false
  redactable: true
  exit-on-error: false
  auditable: false
sinks:
  file-groups:
    default:
      channels: [DEV, OPS, HEALTH, SQL_SCHEMA, USER_ADMIN, PRIVILEGES]
    pebble:
      channels: [STORAGE]
    sql-audit:
      channels: [SENSITIVE_ACCESS]
      auditable: true
    sql-auth:
      channels: [SESSIONS]
      auditable: true
    sql-exec:
      channels: [SQL_EXEC]
    sql-slow:
      channels: [SQL_PERF]
    sql-slow-internal-only:
      channels: [SQL_INTERNAL_PERF]
  stderr:
    channels: all
    filter: NONE
    redact: false
    redactable: true
    exit-on-error: true
capture-stray-errors:
  enable: true
  max-group-size: 100MiB

Note that a default dir is not specified for file-defaults and capture-stray-errors:

• The default dir for file-defaults is inferred from the first on-disk store directory. See Logging directory.
• The default dir for capture-stray-errors is inherited form file-defaults.

See also

• Logging Use Cases
• Log Formats

Was this helpful?