How to use docker system events command to monitor Docker activity

Introduction

In this lab, you will learn how to effectively monitor Docker activity using the docker system events command. You will begin by listening for real-time Docker events generated by actions such as pulling images and running containers.

Subsequently, you will explore how to filter these events based on various criteria. This includes filtering by time using the --since and --until flags, filtering by object type and action using the --filter flag, and combining multiple filters for more specific monitoring. Finally, you will learn how to format the event output for better readability and analysis using the --format flag.

Skills Graph

Listen for real-time Docker events

In this step, you will learn how to listen for real-time Docker events. Docker events are generated by the Docker daemon when certain actions occur, such as starting, stopping, or deleting containers, images, or volumes. Monitoring these events can be useful for automation, logging, and debugging.

To listen for Docker events, you use the docker events command. By default, this command will continuously output events as they happen.

First, let's open a terminal and run the docker events command. This command will block and wait for events.

docker events

Now, open a new terminal (keep the first terminal running docker events). In this new terminal, we will run a simple Docker container. This action will generate events that you will see in the first terminal.

In the new terminal, run the following command to pull the hello-world image. This will generate a pull event.

docker pull hello-world

You should see output in the first terminal indicating that an image pull event occurred.

Next, run the hello-world container. This will generate create, start, and die events.

docker run hello-world

Observe the output in the first terminal. You should see events related to the container being created, started, and then exiting (dying).

You can stop the docker events command in the first terminal by pressing Ctrl+C.

Filter events by time using --since and --until

In this step, you will learn how to filter Docker events based on time using the --since and --until flags. This is useful for viewing events that occurred within a specific time range.

The --since flag allows you to view events that have occurred since a specific time. The --until flag allows you to view events that occurred up to a specific time. You can use these flags together to specify a time window.

The time can be specified in various formats, including RFC3339 date format (e.g., 2023-10-27T10:00:00Z), Unix timestamps (e.g., 1698393600), or relative times (e.g., 10m for 10 minutes ago, 1h for 1 hour ago).

Let's first generate some events. We will run the hello-world container again.

docker run hello-world

Now, let's try to view the events that occurred in the last 5 minutes. We can use the --since flag with a relative time.

docker events --since 5m

You should see the events related to the hello-world container run that you just performed.

Next, let's try to view events that occurred in the last 10 minutes but not in the last 2 minutes. We can use both --since and --until flags with relative times.

docker events --since 10m --until 2m

Depending on when you ran the hello-world container, you might or might not see the events. If you don't see any events, try adjusting the time ranges.

You can also use absolute timestamps. To get the current Unix timestamp, you can use the date +%s command.

Let's get the current timestamp.

date +%s

Now, run the hello-world container again.

docker run hello-world

Get the current timestamp again.

date +%s

Now, use the two timestamps you obtained with the --since and --until flags to view the events that occurred between those two times. Replace START_TIMESTAMP and END_TIMESTAMP with the actual timestamps you recorded.

docker events --since START_TIMESTAMP --until END_TIMESTAMP

You should see the events from the hello-world container run that happened between the two timestamps.

Filter events by object type and action using --filter

In this step, you will learn how to filter Docker events based on the object type and action using the --filter flag. This allows you to focus on specific types of events, such as container events or image events, and specific actions, such as create, start, stop, or delete.

The --filter flag takes a key-value pair in the format key=value. For filtering by object type, the key is type and the value can be container, image, volume, network, daemon, or plugin. For filtering by action, the key is event and the value is the specific action.

Let's start by filtering for only container events. We will run the hello-world container again to generate events.

docker run hello-world

Now, use the docker events command with the --filter type=container flag to view only container-related events.

docker events --filter type=container --since 5m

You should see events like create, start, and die for the hello-world container, but not events related to image pulling.

Next, let's filter for a specific action, for example, only start events for containers.

docker events --filter type=container --filter event=start --since 5m

This command will only show the start event for the hello-world container if it occurred within the last 5 minutes.

You can also filter by the name or ID of the object. For example, to filter events for a specific container named my-container, you would use --filter container=my-container.

Let's run the hello-world container with a specific name.

docker run --name my-hello-container hello-world

Now, filter events specifically for the container named my-hello-container.

docker events --filter container=my-hello-container --since 5m

You should see all events related to the my-hello-container within the last 5 minutes.

Filter events by multiple criteria using multiple --filter flags

In this step, you will learn how to combine multiple --filter flags to filter Docker events based on multiple criteria simultaneously. This allows you to create more specific filters to find exactly the events you are interested in.

When you use multiple --filter flags, Docker applies an "AND" logic. This means that an event must match all the specified filters to be included in the output.

Let's combine filtering by object type and action. We will filter for container start events.

First, run a container to generate a start event.

docker run hello-world

Now, use two --filter flags: one for the object type (type=container) and one for the action (event=start). We will also use --since 5m to limit the time range.

docker events --filter type=container --filter event=start --since 5m

You should see only the start event for the hello-world container if it occurred within the last 5 minutes. Events like create or die will be excluded because they don't match the event=start filter.

You can also combine filtering by time, type, and action. For example, let's filter for container die events that occurred in the last 10 minutes but not in the last 2 minutes.

docker events --filter type=container --filter event=die --since 10m --until 2m

This command will show container die events that fall within the specified time window.

You can add even more filters, such as filtering by container name or image name. Let's filter for start events of a container named my-specific-container using the ubuntu image.

First, pull the ubuntu image.

docker pull ubuntu

Now, run an ubuntu container with a specific name.

docker run --name my-specific-container ubuntu echo "Hello from Ubuntu"

Now, filter for start events of the container named my-specific-container.

docker events --filter type=container --filter event=start --filter container=my-specific-container --since 5m

You should see the start event for the my-specific-container if it occurred within the last 5 minutes.

Format event output using --format

In this step, you will learn how to format the output of Docker events using the --format flag. This allows you to customize the information displayed for each event, making it easier to parse or read.

The --format flag uses Go's text/template package syntax. You can access various fields of the event object, such as .Time, .Type, .Action, .Actor.ID, and .Actor.Attributes.

Let's start by displaying the time, type, and action of each event.

First, generate some events by running the hello-world container.

docker run hello-world

Now, use the docker events command with the --format flag to specify the desired output format. We will display the time, type, and action, separated by a tab (\t).

docker events --since 5m --format '{{.Time}}\t{{.Type}}\t{{.Action}}'

You should see output similar to this, but with different timestamps and IDs:

2023-10-27 10:30:00.123456789 +0000 UTC	container	create
2023-10-27 10:30:00.987654321 +0000 UTC	container	start
2023-10-27 10:30:01.567890123 +0000 UTC	container	die

You can also access attributes of the actor that triggered the event. For example, to display the container name, you can use .Actor.Attributes.name.

Let's run the hello-world container with a name again.

docker run --name my-formatted-container hello-world

Now, format the output to include the container name.

docker events --since 5m --format '{{.Time}}\t{{.Type}}\t{{.Action}}\t{{.Actor.Attributes.name}}'

The output should now include the container name:

2023-10-27 10:35:00.123456789 +0000 UTC	container	create	my-formatted-container
2023-10-27 10:35:00.987654321 +0000 UTC	container	start	my-formatted-container
2023-10-27 10:35:01.567890123 +0000 UTC	container	die	my-formatted-container

You can use various template functions and control structures within the format string for more complex formatting. Refer to the Go text/template documentation for more details.

Summary

In this lab, you learned how to use the docker events command to monitor Docker activity in real-time. You started by listening for all Docker events as they occurred, observing events generated by pulling and running a simple container.

Subsequently, you explored how to filter these events based on various criteria. You learned to filter events by time using the --since and --until flags to view events within a specific time range. You also discovered how to filter events by object type and action using the --filter flag, and how to apply multiple filters simultaneously to narrow down the event stream. Finally, you learned how to format the output of the docker events command using the --format flag for better readability and parsing.