Working with Container Logs: A Practical Guide to Debugging

Previously in this course, we discussed managing environment variables to configure your services at runtime. Now that your applications are running with the correct settings, you need to know how to see what they are actually doing.

When a container fails or behaves unexpectedly, the first place you should look is its output. Efficient logging is the cornerstone of troubleshooting and maintaining system health.

Understanding the Docker Logging Architecture

By default, Docker captures the standard output (stdout) and standard error (stderr) streams of the process running inside your container. It stores these as JSON files on your host machine.

While you can access these files directly on the host file system, doing so is brittle and dangerous. Instead, we use the docker logs command. This tool acts as an abstraction layer, allowing you to interact with those streams without needing to know where the underlying files live or how they are formatted.

Following Logs in Real-Time

In development, you rarely want to see a static snapshot of logs; you want to see the stream as it happens. Much like the Linux tail -f command, Docker provides the --follow (or -f) flag.

Try this with a background service:

Bash
# Start a simple container that writes to stdout
docker run -d --name logger-example alpine /bin/sh -c "while true; do echo 'Logging heartbeat...'; sleep 2; done"

# Follow the logs in real-time
docker logs -f logger-example

Press Ctrl+C to stop following the stream. Note that the container keeps running in the background. If you want to see the most recent lines without following indefinitely, use --tail:

Bash
# Get the last 5 lines and exit
docker logs --tail 5 logger-example

Filtering Logs by Time

As your application grows, your logs will become noisy. Sometimes you only care about events that happened after a deployment or during a specific incident window. You can filter docker logs using the --since and --until flags.

These flags accept relative time (e.g., 30m, 1h) or timestamps (e.g., 2023-10-01T12:00:00).

Bash
# Show logs generated in the last 10 minutes
docker logs --since 10m logger-example

# Show logs between two specific times
docker logs --since "2023-10-20T10:00:00" --until "2023-10-20T10:05:00" logger-example

Redirecting Logs to Files

While the Docker CLI is great for interactive debugging, you will often need to persist these logs for post-mortem analysis or to share with team members. Since docker logs writes to your terminal's standard output, you can use standard shell redirection to save them.

Bash
# Redirect logs to a file on your host
docker logs logger-example > container_debug.log 2>&1

Note: The 2>&1 ensures that both standard output and standard error are captured in the same file.

Hands-on Exercise: Log Rotation and Capture

1. Ensure you have your project container running from our previous lessons.
2. Run docker logs --tail 20 <container_name> to see the most recent activity.
3. Open a new terminal and run docker logs -f <container_name>.
4. Trigger an action in your app (like refreshing a web page) and observe the logs updating in real-time.
5. Capture the last hour of logs into a file named app-debug.log using the redirection command shown above.

Common Pitfalls

• Log Bloat: If your application is "chatty" (logs every single request or debug statement), your host disk can fill up quickly. Remember that Docker stores these logs as plain text. In production environments, always configure log rotation.
• Missing Timestamps: By default, docker logs might not show timestamps. If you need to correlate events, use the --timestamps flag to prepend the date and time to every line.
• Buffer Delays: When redirecting logs to a file in some languages, the output might be buffered. If you don't see logs appearing in your file immediately, check if your application is flushing its output stream.

FAQ

Q: Does docker logs clear the logs from the disk? A: No. docker logs is a read-only operation. To clear logs, you would typically need to remove and recreate the container or configure a logging driver that handles rotation.

Q: Can I see logs for a stopped container? A: Yes! Unlike processes that disappear when they exit, Docker keeps the log files until the container is removed. Even if a container has crashed, you can run docker logs <container_id> to see the final output before the process terminated.

Q: What if my container doesn't output to stdout? A: Docker's native logging only captures stdout and stderr. If your application writes to its own internal log files inside the container, you will need to mount a volume to access those files or use a sidecar logging agent.

Recap

We have covered how to retrieve and monitor application output using the Docker CLI. You now know how to:

1. Stream logs in real-time using -f.
2. Limit output using --tail and time-based filtering.
3. Save logs to your host system for long-term review.

These skills are essential for the next phase of our course, where we will start connecting multiple services together and debugging their communication.

Up next: Defining Service Relationships