19.2.4.4 Logs Timestamp Option

The timestamp option in docker logs prepends a date and time to each line of output. It is activated with the -t or --timestamps flag and is particularly valuable when the container's application does not include timestamps in its own log output, or when precise timing of events matters for debugging and correlation.

Basic Usage

docker logs -t my-container

2024-06-15T10:32:45.123456789Z Server started on port 8080
2024-06-15T10:32:45.789012345Z Connected to database at db:5432
2024-06-15T10:33:01.001234567Z GET /health 200 2ms
2024-06-15T10:33:15.456789012Z GET /api/users 200 45ms
2024-06-15T10:34:02.987654321Z ERROR: Connection to cache lost

Each line begins with a precise timestamp followed by the original log content.

Timestamp Format

Docker uses the RFC3339Nano format:

YYYY-MM-DDTHH:MM:SS.NNNNNNNNNz

Where:

• YYYY-MM-DD is the date.
• T is a literal separator.
• HH:MM:SS is the time.
• .NNNNNNNNN is the fractional seconds (nanosecond precision).
• Z indicates UTC (or a timezone offset like +05:30).

Example: 2024-06-15T10:32:45.123456789Z

Timestamps are always in UTC. If the local timezone display is needed, the timestamp can be converted after retrieval using standard date tools.

What the Timestamp Represents

The timestamp reflects the moment Docker's logging subsystem captured the line from the container's stdout or stderr. It is not the application's own timestamp (if the application also logs timestamps) — it is the time Docker received the output.

In practice, for non-buffered output, these two times are nearly identical. For applications that buffer output (e.g., programs that accumulate lines in memory before flushing), the Docker timestamp reflects when the buffer was flushed, which may be seconds or minutes after the event actually occurred.

Combining with Other Options

Timestamps with tail

docker logs -t --tail 100 my-container

Shows the last 100 lines with timestamps prepended to each.

Timestamps with follow

docker logs -t -f my-container

Streams logs in real time with timestamps on each incoming line. Useful for precise monitoring where sub-second timing matters.

Timestamps with tail and follow

docker logs -t --tail 50 -f my-container

Shows the last 50 historical lines with timestamps, then follows new output with timestamps.

Timestamps with since

docker logs -t --since 30m my-container

Shows all log lines from the last 30 minutes, each prefixed with its timestamp.

Use Cases for Timestamps

Correlating container events with external events

When an alert fires at 10:33:05 UTC, running:

docker logs -t --since 5m my-container | grep -A 5 -B 5 "10:33:0"

Shows the container's state around that moment without needing to know the exact line number.

Identifying slow operations

Comparing consecutive timestamps reveals where delays occur:

2024-06-15T10:33:00.001Z Starting database query
2024-06-15T10:33:12.453Z Database query complete

The gap between these timestamps shows the query took over 12 seconds.

Analyzing startup time

docker logs -t --tail all my-container | head -20

The first few lines with timestamps show exactly how long each initialization step takes.

Post-mortem debugging of stopped containers

docker logs -t my-stopped-container | grep "ERROR"

Each error line includes a timestamp, pinpointing when failures occurred.

Applications That Already Include Timestamps

If the containerized application already formats its own timestamps in log output, the Docker-prepended timestamp creates redundancy:

2024-06-15T10:32:45.123Z 2024-06-15T10:32:45.001 [INFO] Server started

(Docker timestamp on the left, application timestamp on the right.)

In this case, the Docker timestamp can be omitted:

docker logs my-container  # no -t flag, application timestamps are sufficient

Docker timestamps are most valuable for applications that do not log timestamps, for raw binary output, or for cases where the application's timestamp format differs from what is needed.

Precision and Accuracy

Docker logs timestamps at nanosecond precision, but the actual granularity depends on the host's clock resolution and how frequently the logging driver is flushed. On most modern Linux systems, the json-file driver captures timestamps at microsecond to millisecond resolution in practice, even though the format includes nanoseconds.

For high-frequency log lines (thousands per second), adjacent lines may share the same millisecond timestamp. This is expected and indicates the logging system is operating faster than the clock's effective tick resolution at that level.