Skip to content

docs: Clarify docker logs --until/--since usage. #4360

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aznashwan wants to merge 1 commit into
base: master
Choose a base branch
from
+56 −22
Open

docs: Clarify docker logs --until/--since usage. #4360

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 56 additions & 22 deletions docs/reference/commandline/logs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,14 @@ Fetch the logs of a container

### Options

| Name | Type | Default | Description |
|:---------------------|:---------|:--------|:---------------------------------------------------------------------------------------------------|
| `--details` | | | Show extra details provided to logs |
| `-f`, `--follow` | | | Follow log output |
| `--since` | `string` | | Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) |
| `-n`, `--tail` | `string` | `all` | Number of lines to show from the end of the logs |
| `-t`, `--timestamps` | | | Show timestamps |
| [`--until`](#until) | `string` | | Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes) |
| Name | Type | Default | Description |
|:---------------------|:---------|:--------|:-------------------------------------------------------------------------------------------------------------------------------|
| `--details` | | | Show extra details provided to logs |
| `-f`, `--follow` | | | Follow log output |
| [`--since`](#since) | `string` | | Show logs after a [timestamp](#date_formats) (e.g. `2013-01-02T13:23:37Z`) or relative to now (e.g. `42m` for 42 minutes ago) |
| `-n`, `--tail` | `string` | `all` | Number of lines to show from the end of the logs |
| `-t`, `--timestamps` | | | Show timestamps |
| [`--until`](#until) | `string` | | Show logs before a [timestamp](#date_formats) (e.g. `2013-01-02T13:23:37Z`) or relative to now (e.g. `42m` for 42 minutes ago) |


<!---MARKER_GEN_END-->
Expand All @@ -43,18 +43,32 @@ The `docker logs --details` command will add on extra attributes, such as
environment variables and labels, provided to `--log-opt` when creating the
container.

The `--since` option shows only the container logs generated after
a given date. You can specify the date as an RFC 3339 date, a UNIX
timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date
format you may also use RFC3339Nano, `2006-01-02T15:04:05`,
`2006-01-02T15:04:05.999999999`, `2006-01-02Z07:00`, and `2006-01-02`. The local
timezone on the client will be used if you do not provide either a `Z` or a
`+-00:00` timezone offset at the end of the timestamp. When providing Unix
timestamps enter seconds[.nanoseconds], where seconds is the number of seconds
that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap
seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a
fraction of a second no more than nine digits long. You can combine the
`--since` option with either or both of the `--follow` or `--tail` options.
The `--since` option shows only the container logs generated **after**
a given [timestamp](#date_formats). You can combine the `--since` option with
either or both of the `--follow` or `--tail` options.

The `--until` option shows only the container logs generated **before** a given
[timestamp](#date_formats). You can combine the `--since` option with either or
both of the `--follow` (for timestamps in the future) or `--tail` options.

### <a name="date_formats"></a> Supported timestamp formats

The date values for `--since/--until` can be specified in the following ways:
* an RFC3339 or RFC3339Nano date string.
* date strings of the following formats: `2006-01-02`, `2006-01-02Z07:00`,
`2006-01-02T15:04:05`, and `2006-01-02T15:04:05.999999999`. Note that if you
do not provide either a `Z` or a `+-00:00` timezone offset at the end of the
timestamp, the local timezone on the client will be used.
* Unix timestamps of the form `seconds[.nanoseconds]`, representing the number
of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT),
not counting leap seconds (aka Unix epoch or Unix time) and an optional
`.nanoseconds` field with no more than nine digits for representing
fractions of a second.
* a Go duration string (e.g. `90s`, `1.5m`, `1h30m`) which is subtracted from
the Docker client's current time to get the equivalent timestamp. Specifying
a negative value (e.g. `-60m`) will lead to a timestamp in the future.
Accepts all time measurement units accepted by [`time.ParseDuration()`](https://pkg.go.dev/time#ParseDuration).


## Examples

Expand All @@ -64,10 +78,30 @@ In order to retrieve logs before a specific point in time, run:

```console
$ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done"
$ sleep 5
$ date
Tue 14 Nov 2017 16:40:00 CET
$ docker logs --until=3s test
Tue 14 Nov 2017 16:39:55 CET
Tue 14 Nov 2017 16:39:56 CET
Tue 14 Nov 2017 16:39:57 CET
<EOF>
```

### <a name="since"></a> Follow logs after a specific point in time (--since)

In order to follow logs after a specific point in time, run:

```console
$ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done"
$ sleep 5
$ date
Tue 14 Nov 2017 16:40:00 CET
$ docker logs -f --until=2s test
$ docker logs -f --since=3s test
Tue 14 Nov 2017 16:39:57 CET
Tue 14 Nov 2017 16:39:58 CET
Tue 14 Nov 2017 16:39:59 CET
Tue 14 Nov 2017 16:40:00 CET
Tue 14 Nov 2017 16:40:01 CET
Tue 14 Nov 2017 16:40:02 CET
...
```