logs.mdx

layout	page_title	description
docs	logs Block - Job Specification	The "logs" block configures the log rotation policy for a task's stdout and stderr. Logging is enabled by default with reasonable defaults. The "logs" block allows for finer-grained control over how Nomad handles log files.

logs Block

<Placement groups={['job', 'group', 'task', 'logs']} />

The logs block configures the log rotation policy for a task's stdout and stderr. Logging is enabled by default with reasonable defaults (provided in the parameters section below). The logs block allows for finer-grained control over how Nomad handles log files.

Nomad's log rotation works by writing stdout/stderr output from tasks to a file inside the alloc/logs/ directory with the following format: <task-name>.<stdout/stderr>.<index>. Output is written to a particular index, starting at zero, till that log file hits the configured max_file_size. After, a new file is created at index + 1 and logs will then be written there. A log file is never rolled over, instead Nomad will keep up to max_files worth of logs and once that is exceeded, the log file with the lowest index is deleted.

job "docs" {
  group "example" {
    task "server" {
      logs {
        max_files     = 10
        max_file_size = 10
        disabled      = false
      }
    }
  }
}

Each job's logs will be written to ephemeral disk space. If you increase the total amount of logs on disk, you may want to increase ephemeral disk size as well. See the ephemeral disk documentation for more information.

For information on how to interact with logs after they have been configured, please see the nomad alloc logs command.

logs Parameters

• max_files (int: 10) - Specifies the maximum number of rotated files Nomad will retain for stdout and stderr. Each stream is tracked individually, so specifying a value of 2 will create 4 files - 2 for stdout and 2 for stderr

• max_file_size (int: 10) - Specifies the maximum size of each rotated file in MB. If the amount of disk resource requested for the task is less than the total amount of disk space needed to retain the rotated set of files, Nomad will return a validation error when a job is submitted.

• disabled (bool: false) - Specifies that log collection should be enabled for this task. If set to true, the task driver will attach stdout/stderr of the task to /dev/null (or NUL on Windows). You should only disable log collection if your application has some other way of emitting logs, such as writing to a remote syslog server. Note that the nomad alloc logs command and related APIs will return errors (404 "not found") if logging is disabled.

  Some task drivers such as docker support a disable_log_collection option. If the task driver's disable_log_collection option is set to true, it will override disabled=false in the task's logs block.

logs Examples

The following examples only show the logs blocks. Remember that the logs block is only valid in the placements listed above.

Configure Defaults

This example shows a default logging configuration. Yes, it is empty on purpose. Nomad automatically enables logging with reasonable defaults as described in the parameters section above.

Customization

This example asks Nomad to retain 3 rotated files for each of stderr and stdout, each a maximum size of 5 MB per file. The minimum disk space this would require is 30 MB (3 stderr + 3 stdout × 5 MB = 30 MB).

logs {
  max_files     = 3
  max_file_size = 5
}