nomad/website/content/docs/job-specification/logs.mdx

---
layout: docs
page_title: logs block in the job specification
description: |-
  Configure a task's log rotation policy in the `logs` block of the Nomad job specification. Set the maximum number of rotated files and the maximum size of each rotated file. Turn off log collection for a task. Review default log rotation values.
---

# `logs` block in the job specification

<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.

```hcl
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`][logs-command] command.

## 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.

## 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.

```hcl

```

### 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` &plus; 3 `stdout` &times; 5 MB &equals; 30 MB).

```hcl
logs {
  max_files     = 3
  max_file_size = 5
}
```

[logs-command]: /nomad/commands/alloc/logs 'Nomad logs command'
[`disable_log_collection`]: /nomad/docs/deploy/task-driver/docker#disable_log_collection
[ephemeral disk documentation]: /nomad/docs/job-specification/ephemeral_disk 'Nomad ephemeral disk Job Specification'