How to use docker compose events command to monitor container events

Introduction

In this lab, you will learn how to use the docker compose events command to monitor container events. We will begin by preparing a simple Docker Compose project, including installing Docker Compose and creating a basic docker-compose.yml file.

Following the setup, you will start the services defined in the project and observe the basic events generated. We will then explore how to use the --json flag to output these events in a structured JSON format. Finally, you will learn how to filter events to monitor only those related to specific services within your Docker Compose application.

Skills Graph

Prepare a simple Docker Compose project

In this step, we will prepare a simple Docker Compose project. Since Docker Compose is not pre-installed in the LabEx environment, we will first install it. Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application's services. Then, with a single command, you create and start all the services from your configuration.

First, let's install Docker Compose. We will download the Docker Compose binary and make it executable.

sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

After the installation, you can verify the installation by checking the version of Docker Compose.

docker-compose --version

You should see output similar to Docker Compose version v2.20.2.

Now, let's create a directory for our project and navigate into it. We will create a simple project with a single service.

mkdir ~/project/my-compose-app
cd ~/project/my-compose-app

Next, we will create a docker-compose.yml file in this directory. This file will define our service. We will use the nano editor to create and edit the file.

nano docker-compose.yml

In the nano editor, paste the following content. This configuration defines a service named web that uses the nginx:latest image.

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"

Let's break down this docker-compose.yml file:

• version: '3.8' specifies the Docker Compose file format version.
• services: defines the services that make up your application.
• web: is the name of our service.
• image: nginx:latest specifies the Docker image to use for this service. In this case, we are using the latest version of the official Nginx image.
• ports: maps ports between the host and the container. "80:80" maps port 80 on the host to port 80 on the container.

Save the file by pressing Ctrl + X, then Y, and Enter.

Before starting the service, let's pull the nginx:latest image. While Docker Compose will pull the image if it's not present, explicitly pulling it beforehand can sometimes be helpful.

docker pull nginx:latest

You should see output indicating that the image is being pulled and downloaded.

Now we have our docker-compose.yml file ready and the necessary image pulled. In the next step, we will start the service defined in this file.

Start the services and observe basic events

In this step, we will start the services defined in our docker-compose.yml file and observe the basic events generated by Docker. Docker events are real-time information about what is happening with your Docker daemon and containers, such as container creation, start, stop, and destruction.

First, make sure you are in the ~/project/my-compose-app directory where you created the docker-compose.yml file in the previous step.

cd ~/project/my-compose-app

Now, we will use the docker-compose up command to start the service. The -d flag runs the containers in detached mode, meaning they will run in the background and not block your terminal.

docker-compose up -d

You should see output indicating that the network and the web service container are being created and started.

[+] Running 2/2
 ⠿ Network my-compose-app_default  Created
 ⠿ Container my-compose-app-web-1  Started

To observe the basic Docker events, we will use the docker events command. This command streams events from the Docker daemon.

docker events

You will see a continuous stream of events related to your Docker environment. Since we just started a container, you should see events related to the creation, start, and potentially other actions related to the my-compose-app-web-1 container. The output will look something like this (timestamps and specific details will vary):

2023-10-27T10:00:00.123456789Z container create 1234567890abcdef... (image=nginx:latest, name=my-compose-app-web-1, ...)
2023-10-27T10:00:01.987654321Z container start 1234567890abcdef... (image=nginx:latest, name=my-compose-app-web-1, ...)
...

The docker events command will keep running and displaying new events as they occur. To stop the command and return to your terminal prompt, press Ctrl + C.

You can also observe the running container using the docker ps command.

docker ps

You should see the my-compose-app-web-1 container listed with a status of Up.

CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                               NAMES
...            nginx:latest   "nginx -g 'daemon off"   About a minute ago   Up About a minute   0.0.0.0:80->80/tcp, :::80->80/tcp   my-compose-app-web-1

In this step, we successfully started our Docker Compose service and observed the basic events generated by Docker. In the next step, we will explore how to output these events in JSON format.

Use the --json flag to output events in JSON format

In this step, we will learn how to output Docker events in JSON format using the --json flag with the docker events command. Outputting events in JSON format is useful for programmatic processing and integration with other tools.

First, ensure you are in the ~/project/my-compose-app directory.

cd ~/project/my-compose-app

Now, let's run the docker events command with the --json flag. This will stream the events in JSON format.

docker events --json

You will see a continuous stream of JSON objects, where each object represents a Docker event. The output will look similar to this (details will vary):

{"status":"create","id":"1234567890abcdef...","from":"nginx:latest","Type":"container","Action":"create","Actor":{"ID":"1234567890abcdef...","Attributes":{"image":"nginx:latest","name":"my-compose-app-web-1"}},"scope":"local","time":1678886400,"timeNano":1678886400123456789}
{"status":"start","id":"1234567890abcdef...","from":"nginx:latest","Type":"container","Action":"start","Actor":{"ID":"1234567890abcdef...","Attributes":{"image":"nginx:latest","name":"my-compose-app-web-1"}},"scope":"local","time":1678886401,"timeNano":1678886401987654321}
...

Each line is a valid JSON object containing detailed information about the event, such as the event status, the affected object's id, Type, Action, and Actor details including Attributes like the image name and container name.

To demonstrate capturing these events, let's stop and then start the web service again while the docker events --json command is running in another terminal or background. Since we are using a single terminal in this lab, we will stop the docker events --json command first by pressing Ctrl + C.

Now, let's stop the web service.

docker-compose stop web

You should see output indicating that the web container is being stopped.

[+] Stopping 1/1
 ⠿ Container my-compose-app-web-1  Stopped

Now, let's run docker events --json in the background and then start the service again. We will use the & symbol to run the command in the background.

docker events --json &

You will see a process ID (PID) printed, indicating the command is running in the background.

Now, start the web service again.

docker-compose start web

You should see output indicating that the web container is being started.

[+] Starting 1/1
 ⠿ Container my-compose-app-web-1  Started

The docker events --json command running in the background will capture the stop and start events. To see the output from the background process, you might need to bring it to the foreground using the fg command, or check the terminal output after the background process is stopped. However, for the purpose of this step, simply running the command with --json is sufficient to understand the format.

To stop the background docker events --json process, you can use the jobs command to list background jobs and then kill %<job_number>. Alternatively, you can find the process ID using ps aux | grep 'docker events --json' and use the kill command with the PID. A simpler way in this context is to just proceed to the next step, as the background process won't interfere significantly.

In this step, we successfully used the --json flag to view Docker events in a structured JSON format, which is valuable for automation and analysis.

Filter events for specific services

In this step, we will learn how to filter Docker events to only see events related to specific services or containers. This is very useful in environments with many containers where you only want to monitor events for a particular application or service.

The docker events command supports filtering using the --filter flag. You can filter by various criteria, such as container, image, event, label, etc.

First, ensure you are in the ~/project/my-compose-app directory.

cd ~/project/my-compose-app

Our service is named web in the docker-compose.yml file, and the container name generated by Docker Compose is typically in the format <project_name>_<service_name>_<instance_number>. In our case, the project name is my-compose-app (derived from the directory name), the service name is web, and the instance number is 1. So the container name is my-compose-app-web-1.

Let's filter events to only show those related to our web container. We can use the container filter with the container name.

docker events --filter container=my-compose-app-web-1

This command will now only display events where the affected object is the container named my-compose-app-web-1. To see this in action, let's stop and start the web service again while this command is running.

First, stop the docker events command by pressing Ctrl + C.

Now, run the filtered docker events command in the background.

docker events --filter container=my-compose-app-web-1 &

You will see the background process ID.

Now, stop the web service using Docker Compose.

docker-compose stop web

You should see output indicating the container is stopping. The background docker events command should capture the stop event for the my-compose-app-web-1 container.

Next, start the web service again.

docker-compose start web

You should see output indicating the container is starting. The background docker events command should capture the start event for the my-compose-app-web-1 container.

You can also filter by other criteria. For example, to filter events by image, you could use --filter image=nginx:latest.

To stop the background docker events process, you can use jobs and kill %<job_number> or find the PID and use kill <PID>. For this lab, you can simply proceed.

Finally, let's clean up the running container and network created by Docker Compose.

docker-compose down

This command will stop and remove the containers, networks, and volumes defined in the docker-compose.yml file.

[+] Running 2/1
 ⠿ Container my-compose-app-web-1  Removed
 ⠿ Network my-compose-app_default  Removed

In this step, we learned how to filter Docker events using the --filter flag, which is essential for monitoring specific components in a busy Docker environment. We also cleaned up the resources created during the lab.

Summary

In this lab, we learned how to use the docker compose events command to monitor container events. We began by preparing a simple Docker Compose project, which involved installing Docker Compose and creating a docker-compose.yml file defining a basic Nginx service.

Following the project setup, we started the services and observed the basic events generated by Docker Compose. We then explored how to output these events in JSON format using the --json flag for easier parsing and analysis. Finally, we learned how to filter the events to monitor only those related to specific services within our Docker Compose project.