Menu Close

Chapter 14. Monitoring containers

This chapter focuses on useful Podman commands that allow you to manage a Podman environment, including determining the health of the container, displaying system and pod information, and monitoring Podman events.

14.1. Performing a healthcheck on a container

The healthcheck allows you to determine the health or readiness of the process running inside the container. A healthcheck consists of five basic components:

  • Command
  • Retries
  • Interval
  • Start-period
  • Timeout

The description of healthcheck components follows.

Podman executes the command inside the target container and waits for the exit code.

The other four components are related to the scheduling of the healthcheck and they are optional.

Defines the number of consecutive failed healthchecks that need to occur before the container is marked as "unhealthy". A successful healthcheck resets the retry counter.
Describes the time between running the healthcheck command. Note that small intervals cause your system to spend a lot of time running healthchecks. The large intervals cause struggles with catching time outs.
Describes the time between when the container starts and when you want to ignore healthcheck failures.
Describes the period of time the healthcheck must complete before being considered unsuccessful.

Healthchecks run inside the container. Healthcheck only make sense if you know what is a health state of the service and can differentiate between a successful and unsuccessful health check.


  1. Define a healthcheck:

    $ podman run -dt --name hc1 -p 8080:8080  --health-cmd='curl http://localhost:8080 || exit 1' --health-interval=0
    • The --health-cmd option sets a healthcheck command for the container.
    • The -health-interval=0 option with 0 value indicates that you want to run healthcheck manually.
  2. Run the healthcheck manually:

    $ podman healthcheck run hc1
  3. Optionally, you can check the exit status of last command:

    $ echo $?

    The "0" value means success.

Additional resources

14.2. Displaying Podman system information

The podman system command allows you to manage the Podman systems. This section provides information on how to display Podman system information.


  • Display Podman system information:

    • To show Podman disk usage, enter:

      $ podman system df
      TYPE           TOTAL       ACTIVE      SIZE        RECLAIMABLE
      Images         3           2           1.085GB     233.4MB (0%)
      Containers     2           0           28.17kB     28.17kB (100%)
      Local Volumes  3           0           0B          0B (0%)
    • To show detailed information on space usage, enter:

      $ podman system df -v
      Images space usage:
      REPOSITORY                                TAG         IMAGE ID      CREATED     SIZE        SHARED SIZE  UNIQUE SIZE  CONTAINERS           latest      b1e63aaae5cf  13 days     233.4MB     233.4MB      0B           0  latest      0d04740850e8  13 days     461.5MB     0B           461.5MB      1           latest      dce10f591a2d  13 days     390.6MB     233.4MB      157.2MB      1
      Containers space usage:
      CONTAINER ID  IMAGE         COMMAND                     LOCAL VOLUMES  SIZE        CREATED     STATUS      NAMES
      311180ab99fb  0d04740850e8  /usr/bin/run-httpd          0              28.17kB     16 hours    exited      hc1
      bedb6c287ed6  dce10f591a2d  podman run ubi9 echo hello  0              0B          11 hours    configured  dazzling_tu
      Local Volumes space usage:
      VOLUME NAME                                                       LINKS       SIZE
      76de0efa83a3dae1a388b9e9e67161d28187e093955df185ea228ad0b3e435d0  0           0B
      8a1b4658aecc9ff38711a2c7f2da6de192c5b1e753bb7e3b25e9bf3bb7da8b13  0           0B
      d9cab4f6ccbcf2ac3cd750d2efff9d2b0f29411d430a119210dd242e8be20e26  0           0B
    • To display information about the host, current storage stats, and build of Podman, enter:

      $ podman system info
        arch: amd64
        buildahVersion: 1.22.3
        cgroupControllers: []
        cgroupManager: cgroupfs
        cgroupVersion: v1
          package: conmon-2.0.29-1.module+el8.5.0+12381+e822eb26.x86_64
          path: /usr/bin/conmon
          version: 'conmon version 2.0.29, commit: 7d0fa63455025991c2fc641da85922fde889c91b'
        cpus: 2
          distribution: '"rhel"'
          version: "8.5"
        eventLogger: file
        hostname: localhost.localdomain
          - container_id: 0
            host_id: 1000
            size: 1
          - container_id: 1
            host_id: 100000
            size: 65536
          - container_id: 0
            host_id: 1000
            size: 1
          - container_id: 1
            host_id: 100000
            size: 65536
        kernel: 4.18.0-323.el8.x86_64
        linkmode: dynamic
        memFree: 352288768
        memTotal: 2819129344
          name: runc
          package: runc-1.0.2-1.module+el8.5.0+12381+e822eb26.x86_64
          path: /usr/bin/runc
          version: |-
            runc version 1.0.2
            spec: 1.0.2-dev
            go: go1.16.7
            libseccomp: 2.5.1
        os: linux
          path: /run/user/1000/podman/podman.sock
          apparmorEnabled: false
          rootless: true
          seccompEnabled: true
          seccompProfilePath: /usr/share/containers/seccomp.json
          selinuxEnabled: true
        serviceIsRemote: false
          executable: /usr/bin/slirp4netns
          package: slirp4netns-1.1.8-1.module+el8.5.0+12381+e822eb26.x86_64
          version: |-
            slirp4netns version 1.1.8
            commit: d361001f495417b880f20329121e3aa431a8f90f
            libslirp: 4.4.0
            libseccomp: 2.5.1
        swapFree: 3113668608
        swapTotal: 3124752384
        uptime: 11h 24m 12.52s (Approximately 0.46 days)
        configFile: /home/user/.config/containers/storage.conf
          number: 2
          paused: 0
          running: 0
          stopped: 2
        graphDriverName: overlay
            Executable: /usr/bin/fuse-overlayfs
            Package: fuse-overlayfs-1.7.1-1.module+el8.5.0+12381+e822eb26.x86_64
            Version: |-
              fusermount3 version: 3.2.1
              fuse-overlayfs: version 1.7.1
              FUSE library version 3.2.1
              using FUSE kernel interface version 7.26
        graphRoot: /home/user/.local/share/containers/storage
          Backing Filesystem: xfs
          Native Overlay Diff: "false"
          Supports d_type: "true"
          Using metacopy: "false"
          number: 3
        runRoot: /run/user/1000/containers
        volumePath: /home/user/.local/share/containers/storage/volumes
        APIVersion: 3.3.1
        Built: 1630360721
        BuiltTime: Mon Aug 30 23:58:41 2021
        GitCommit: ""
        GoVersion: go1.16.7
        OsArch: linux/amd64
        Version: 3.3.1
    • To remove all unused containers, images and volume data, enter:

      $ podman system prune
      WARNING! This will remove:
              - all stopped containers
              - all stopped pods
              - all dangling images
              - all build cache
      Are you sure you want to continue? [y/N] y
      • The podman system prune command removes all unused containers (both dangling and unreferenced), pods and optionally, volumes from local storage.
      • Use the --all option to delete all unused images. Unused images are dangling images and any image that does not have any containers based on it.
      • Use the --volume option to prune volumes. By default, volumes are not removed to prevent important data from being deleted if there is currently no container using the volume.

Additional resources

  • podman-system-df man page
  • podman-system-info man page
  • podman-system-prune man page

14.3. Podman event types

You can monitor events that occur in Podman. Several event types exist and each event type reports different statuses.

The container event type reports the following statuses:

  • attach
  • checkpoint
  • cleanup
  • commit
  • create
  • exec
  • export
  • import
  • init
  • kill
  • mount
  • pause
  • prune
  • remove
  • restart
  • restore
  • start
  • stop
  • sync
  • unmount
  • unpause

The pod event type reports the following statuses:

  • create
  • kill
  • pause
  • remove
  • start
  • stop
  • unpause

The image event type reports the following statuses:

  • prune
  • push
  • pull
  • save
  • remove
  • tag
  • untag

The system type reports the following statuses:

  • refresh
  • renumber

The volume type reports the following statuses:

  • create
  • prune
  • remove

Additional resources

  • podman-events man page

14.4. Monitoring Podman events

You can monitor and print events that occur in Podman. Each event will include a timestamp, a type, a status, name (if applicable), and image (if applicable).


  • Show Podman events:

    • To show all Podman events, enter:

      $ podman events
      2020-05-14 10:33:42.312377447 -0600 CST container create 34503c192940 (, name=keen_colden)
      2020-05-14 10:33:46.958768077 -0600 CST container init 34503c192940 (, name=keen_colden)
      2020-05-14 10:33:46.973661968 -0600 CST container start 34503c192940 (, name=keen_colden)
      2020-05-14 10:33:50.833761479 -0600 CST container stop 34503c192940 (, name=keen_colden)
      2020-05-14 10:33:51.047104966 -0600 CST container cleanup 34503c192940 (, name=keen_colden)

      To exit logging, press CTRL+c.

    • To show only Podman create events, enter:

      $ podman events --filter event=create
      2020-05-14 10:36:01.375685062 -0600 CST container create 20dc581f6fbf (
      2019-03-02 10:36:08.561188337 -0600 CST container create 58e7e002344c (
      2019-03-02 10:36:29.978806894 -0600 CST container create d81e30f1310f (

Additional resources

  • podman-events man page