Docker Compose events 命令详解实时追踪 Compose 项目容器事件流【免费下载链接】composeDefine and run multi-container applications with Docker项目地址: https://gitcode.com/GitHub_Trending/compose/composedocker compose events用于实时接收 Compose 项目中所有容器的事件创建、启动、停止、退出等。本篇基于当前仓库的命令参考文档 compose_events.md 与命令定义 docker_compose_events.yaml并结合 cmd/compose/events.go、pkg/compose/events.go 的源码实现完整讲解该命令的参数、JSON 输出格式、底层事件过滤链路与典型排障场景帮助你在多容器应用运维中建立一条可靠的事件观测通道。命令概览events命令的用途是流式接收项目中每一个容器的容器事件Stream container events for every container in the project。在docker compose up、docker compose restart、依赖服务故障重启等场景下该命令可以回答两个问题我的容器什么时候发生了start/die/kill/restart等状态变化变化发生时的容器属性镜像名、容器名等是什么命令的用法形式为docker compose events [OPTIONS] [SERVICE...]注意用法中的[SERVICE...]位置参数可以只监听项目内指定服务的容器事件而不传服务名时则监听整个项目。在 cmd/compose/events.go 中可以看到该命令定义为Use: events [OPTIONS] [SERVICE...]并且注册了ValidArgsFunction: completeServiceNames(...)即在 shell 中补全服务名时由 Compose 项目配置提供候选项。如果传入一个不存在的服务名命令会直接报错退出。E2E 测试 pkg/e2e/events_test.go 中的TestEventsUnknownService验证了这一点cmd : c.NewDockerComposeCmd(t, -f, ./fixtures/simple-composefile/compose.yaml, events, not-a-service) cmd.Timeout 10 * time.Second res : icmd.RunCmd(cmd) res.Assert(t, icmd.Expected{ExitCode: 1, Err: no such service: not-a-service})参数说明命令参考文档给出的完整参数表如下名称类型默认值说明--dry-runboolfalse以 dry run 模式执行命令--jsonboolfalse以 JSON 对象流的形式输出事件--sincestring—显示自该时间戳之后创建的所有事件--untilstring—在该时间戳之后停止流式接收事件在 cmd/compose/events.go 中这三个专属 flag 的注册方式为cmd.Flags().BoolVar(opts.json, json, false, Output events as a stream of json objects) cmd.Flags().StringVar(opts.since, since, , Show all events created since timestamp) cmd.Flags().StringVar(opts.until, until, , Stream events until this timestamp)各参数的实操要点--since/--until透传给引擎的事件过滤条件支持 Docker 引擎事件时间戳的常见格式如2025-01-01T08:00:00或相对时间10m。两者配合可实现“回溯查看某个时间窗内的事件”例如docker compose events --since 30m --until 5m用于复盘半小时前到 5 分钟前容器发生了什么。--dry-run这是根命令上的持久化参数persistent flag在 cmd/compose/compose.go 中注册c.PersistentFlags().BoolVar(dryRun, dry-run, false, Execute command in dry run mode)。当 root 命令检测到--dry-run时会通过backendOptions.Add(compose.WithDryRun)为后端注入 dry run 行为见 cmd/compose/compose.go命令本身不会真正产生副作用而是以可记录的“演练”方式展示将要执行的操作。JSON 输出格式使用--jsonflag 时命令会每行输出一个 JSON 对象文档给出的标准格式为{ time: 2015-11-20T18:01:03.615550, type: container, action: create, id: 213cf7...5fc39a, service: web, attributes: { name: application_web_1, image: alpine:edge } }字段含义字段含义来源time事件时间戳引擎事件时间Unix 秒 / 纳秒type事件类型恒为container硬编码action动作如create、start、stop、die、kill等引擎事件的Action字段id容器 IDevent.Actor.IDserviceCompose 服务名容器 labelcom.docker.compose.serviceattributes容器属性键值对引擎事件的Actor.Attributes过滤后该格式并非凭空约定源码中的序列化逻辑在 cmd/compose/events.goConsumer: func(event api.Event) error { if opts.json { marshal, err : json.Marshal(map[string]any{ time: event.Timestamp, type: container, service: event.Service, id: event.Container, action: event.Status, attributes: event.Attributes, }) // ... _, _ fmt.Fprintln(dockerCli.Out(), string(marshal)) } else { _, _ fmt.Fprintln(dockerCli.Out(), event) } return nil }可以看到type字段确实被硬编码为containeraction对应api.Event的Status字段。这种一行一对象JSON Lines的输出天然适配管道处理例如可以直接接jq过滤动作类型docker compose events --json | jq -c select(.action die)底层事件流与过滤链路不带--json时的默认输出由api.Event的String()方法生成定义在 pkg/api/api.gofunc (e Event) String() string { t : e.Timestamp.Format(2006-01-02 15:04:05.000000) var attr []string for k, v : range e.Attributes { attr append(attr, fmt.Sprintf(%s%s, k, v)) } return fmt.Sprintf(%s container %s %s (%s)\n, t, e.Status, e.Container, strings.Join(attr, , )) }即人类可读的一行式输出时间 container 动作 容器ID (属性键值对)例如2026-09-05 04:20:11.382917 container start 213cf7...5fc39a (imagealpine:edge, nameapplication_web_1)而真正的事件从哪里来、如何被过滤在 pkg/compose/events.go 的composeService.Events方法中从源码结构看其处理链如下按项目过滤调用引擎Events接口时附带Filters: projectFilter(projectName)。projectFilter定义在 pkg/compose/filters.go本质上是加一个labelcom.docker.compose.project项目名的过滤器保证只订阅本项目容器的事件Since、Until也在此处透传给引擎。只保留容器事件循环中显式跳过非container类型源码注释标注了TODO: support other event types因此镜像构建、网络变更等其他引擎事件类型不会被该命令输出。忽略一次性容器如果容器带有一性容器 labelcom.docker.compose.oneoff True即docker compose run创建的 one-off 容器label 定义见 pkg/api/labels.go直接丢弃不进入事件流。按服务名过滤当命令传入了SERVICE...位置参数时仅保留com.docker.compose.servicelabel 命中服务名列表的事件slices.Contains(options.Services, service)。清理内部属性遍历Actor.Attributes时跳过所有以com.docker.compose.为前缀的内部 label只把对外属性如image、name、size-rw等填入attributes。纳秒级时间戳优先使用引擎事件中的TimeNano若为 0 则回退到秒级Time换算为time.Time后交给消费者回调。其中api.Event与api.EventsOptions的 API 结构定义在 pkg/api/api.gotype EventsOptions struct { Services []string Consumer func(event Event) error Since string Until string } // Event is a container runtime event served by Events API type Event struct { Timestamp time.Time Service string Container string Status string Attributes map[string]string }从源码结构看Consumer回调采用错误即可中断的设计消费者返回err时Events立即终止而 CLI 层的runEvents回调cmd/compose/events.go始终返回nil因此流会持续运行直至收到--until时间戳、连接断开或用户手动CtrlC结束。命令的入口链路为CLI 层的runEvents先通过opts.projectOrName(ctx, dockerCli, services...)解析出项目名并校验服务存在性再构造compose.NewComposeService(...)后端最后调用backend.Events(ctx, name, api.EventsOptions{...})。典型使用场景结合参数与输出格式几个可直接复制的场景1. 实时观察整个项目docker compose events输出示例2026-09-05 04:20:11.382917 container start 213cf7...5fc39a (imagealpine:edge, nameapplication_web_1) 2026-09-05 04:20:12.001832 container stop 213cf7...5fc39a (imagealpine:edge, nameapplication_web_1)2. 只监听某个服务并输出 JSON适合接入日志/监控管道docker compose events --json web db3. 回放最近 10 分钟的事件定位故障窗口docker compose events --since 10m4. 在时间窗口上自动停止--since --until 组合docker compose events --since 2026-09-05T04:00:00 --until 2026-09-05T04:30:00 --json这类窗口式回放在排查某次up之后容器为何被重建/重启时非常实用事件流中的die/kill/restart动作配合attributes里的exitCode等属性可以快速还原容器生命周期。适用范围与注意事项事件来源是 Docker 引擎的容器事件因此只能观察到由 Compose 管理带com.docker.compose.projectlabel且非 one-off 的容器docker compose run产生的一次性容器会被 pkg/compose/events.go 显式过滤掉。非容器类型的引擎事件目前不会被输出这是当前实现的限制而非遗漏源码中的 TODO 注释表明这是后续可扩展点。--json输出中type恒为container消费方无需按type再做分支。命令需要能连接到 Docker 守护进程并且当前目录或-f/-p指定的项目可以解析出一个 Compose 项目服务名必须真实存在否则以no such service: name错误退出见 pkg/e2e/events_test.go 的验证。参考命令参考文档docs/reference/compose_events.md命令元数据定义docs/reference/docker_compose_events.yamlCLI 入口实现cmd/compose/events.go事件流与过滤实现pkg/compose/events.go项目过滤器pkg/compose/filters.go事件 API 与输出格式pkg/api/api.goCompose label 常量pkg/api/labels.goE2E 测试pkg/e2e/events_test.go【免费下载链接】composeDefine and run multi-container applications with Docker项目地址: https://gitcode.com/GitHub_Trending/compose/compose创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/6 19:48:04 · 阅读 1.2k Docker Compose events 命令详解：实时追踪 Compose 项目容器事件流
Docker Compose events 命令详解实时追踪 Compose 项目容器事件流【免费下载链接】composeDefine and run multi-container applications with Docker项目地址: https://gitcode.com/GitHub_Trending/compose/composedocker compose events用于实时接收 Compose 项目中所有容器的事件创建、启动、停止、退出等。本篇基于当前仓库的命令参考文档 compose_events.md 与命令定义 docker_compose_events.yaml并结合 cmd/compose/events.go、pkg/compose/events.go 的源码实现完整讲解该命令的参数、JSON 输出格式、底层事件过滤链路与典型排障场景帮助你在多容器应用运维中建立一条可靠的事件观测通道。命令概览events命令的用途是流式接收项目中每一个容器的容器事件Stream container events for every container in the project。在docker compose up、docker compose restart、依赖服务故障重启等场景下该命令可以回答两个问题我的容器什么时候发生了start/die/kill/restart等状态变化变化发生时的容器属性镜像名、容器名等是什么命令的用法形式为docker compose events [OPTIONS] [SERVICE...]注意用法中的[SERVICE...]位置参数可以只监听项目内指定服务的容器事件而不传服务名时则监听整个项目。在 cmd/compose/events.go 中可以看到该命令定义为Use: events [OPTIONS] [SERVICE...]并且注册了ValidArgsFunction: completeServiceNames(...)即在 shell 中补全服务名时由 Compose 项目配置提供候选项。如果传入一个不存在的服务名命令会直接报错退出。E2E 测试 pkg/e2e/events_test.go 中的TestEventsUnknownService验证了这一点cmd : c.NewDockerComposeCmd(t, -f, ./fixtures/simple-composefile/compose.yaml, events, not-a-service) cmd.Timeout 10 * time.Second res : icmd.RunCmd(cmd) res.Assert(t, icmd.Expected{ExitCode: 1, Err: no such service: not-a-service})参数说明命令参考文档给出的完整参数表如下名称类型默认值说明--dry-runboolfalse以 dry run 模式执行命令--jsonboolfalse以 JSON 对象流的形式输出事件--sincestring—显示自该时间戳之后创建的所有事件--untilstring—在该时间戳之后停止流式接收事件在 cmd/compose/events.go 中这三个专属 flag 的注册方式为cmd.Flags().BoolVar(opts.json, json, false, Output events as a stream of json objects) cmd.Flags().StringVar(opts.since, since, , Show all events created since timestamp) cmd.Flags().StringVar(opts.until, until, , Stream events until this timestamp)各参数的实操要点--since/--until透传给引擎的事件过滤条件支持 Docker 引擎事件时间戳的常见格式如2025-01-01T08:00:00或相对时间10m。两者配合可实现“回溯查看某个时间窗内的事件”例如docker compose events --since 30m --until 5m用于复盘半小时前到 5 分钟前容器发生了什么。--dry-run这是根命令上的持久化参数persistent flag在 cmd/compose/compose.go 中注册c.PersistentFlags().BoolVar(dryRun, dry-run, false, Execute command in dry run mode)。当 root 命令检测到--dry-run时会通过backendOptions.Add(compose.WithDryRun)为后端注入 dry run 行为见 cmd/compose/compose.go命令本身不会真正产生副作用而是以可记录的“演练”方式展示将要执行的操作。JSON 输出格式使用--jsonflag 时命令会每行输出一个 JSON 对象文档给出的标准格式为{ time: 2015-11-20T18:01:03.615550, type: container, action: create, id: 213cf7...5fc39a, service: web, attributes: { name: application_web_1, image: alpine:edge } }字段含义字段含义来源time事件时间戳引擎事件时间Unix 秒 / 纳秒type事件类型恒为container硬编码action动作如create、start、stop、die、kill等引擎事件的Action字段id容器 IDevent.Actor.IDserviceCompose 服务名容器 labelcom.docker.compose.serviceattributes容器属性键值对引擎事件的Actor.Attributes过滤后该格式并非凭空约定源码中的序列化逻辑在 cmd/compose/events.goConsumer: func(event api.Event) error { if opts.json { marshal, err : json.Marshal(map[string]any{ time: event.Timestamp, type: container, service: event.Service, id: event.Container, action: event.Status, attributes: event.Attributes, }) // ... _, _ fmt.Fprintln(dockerCli.Out(), string(marshal)) } else { _, _ fmt.Fprintln(dockerCli.Out(), event) } return nil }可以看到type字段确实被硬编码为containeraction对应api.Event的Status字段。这种一行一对象JSON Lines的输出天然适配管道处理例如可以直接接jq过滤动作类型docker compose events --json | jq -c select(.action die)底层事件流与过滤链路不带--json时的默认输出由api.Event的String()方法生成定义在 pkg/api/api.gofunc (e Event) String() string { t : e.Timestamp.Format(2006-01-02 15:04:05.000000) var attr []string for k, v : range e.Attributes { attr append(attr, fmt.Sprintf(%s%s, k, v)) } return fmt.Sprintf(%s container %s %s (%s)\n, t, e.Status, e.Container, strings.Join(attr, , )) }即人类可读的一行式输出时间 container 动作 容器ID (属性键值对)例如2026-09-05 04:20:11.382917 container start 213cf7...5fc39a (imagealpine:edge, nameapplication_web_1)而真正的事件从哪里来、如何被过滤在 pkg/compose/events.go 的composeService.Events方法中从源码结构看其处理链如下按项目过滤调用引擎Events接口时附带Filters: projectFilter(projectName)。projectFilter定义在 pkg/compose/filters.go本质上是加一个labelcom.docker.compose.project项目名的过滤器保证只订阅本项目容器的事件Since、Until也在此处透传给引擎。只保留容器事件循环中显式跳过非container类型源码注释标注了TODO: support other event types因此镜像构建、网络变更等其他引擎事件类型不会被该命令输出。忽略一次性容器如果容器带有一性容器 labelcom.docker.compose.oneoff True即docker compose run创建的 one-off 容器label 定义见 pkg/api/labels.go直接丢弃不进入事件流。按服务名过滤当命令传入了SERVICE...位置参数时仅保留com.docker.compose.servicelabel 命中服务名列表的事件slices.Contains(options.Services, service)。清理内部属性遍历Actor.Attributes时跳过所有以com.docker.compose.为前缀的内部 label只把对外属性如image、name、size-rw等填入attributes。纳秒级时间戳优先使用引擎事件中的TimeNano若为 0 则回退到秒级Time换算为time.Time后交给消费者回调。其中api.Event与api.EventsOptions的 API 结构定义在 pkg/api/api.gotype EventsOptions struct { Services []string Consumer func(event Event) error Since string Until string } // Event is a container runtime event served by Events API type Event struct { Timestamp time.Time Service string Container string Status string Attributes map[string]string }从源码结构看Consumer回调采用错误即可中断的设计消费者返回err时Events立即终止而 CLI 层的runEvents回调cmd/compose/events.go始终返回nil因此流会持续运行直至收到--until时间戳、连接断开或用户手动CtrlC结束。命令的入口链路为CLI 层的runEvents先通过opts.projectOrName(ctx, dockerCli, services...)解析出项目名并校验服务存在性再构造compose.NewComposeService(...)后端最后调用backend.Events(ctx, name, api.EventsOptions{...})。典型使用场景结合参数与输出格式几个可直接复制的场景1. 实时观察整个项目docker compose events输出示例2026-09-05 04:20:11.382917 container start 213cf7...5fc39a (imagealpine:edge, nameapplication_web_1) 2026-09-05 04:20:12.001832 container stop 213cf7...5fc39a (imagealpine:edge, nameapplication_web_1)2. 只监听某个服务并输出 JSON适合接入日志/监控管道docker compose events --json web db3. 回放最近 10 分钟的事件定位故障窗口docker compose events --since 10m4. 在时间窗口上自动停止--since --until 组合docker compose events --since 2026-09-05T04:00:00 --until 2026-09-05T04:30:00 --json这类窗口式回放在排查某次up之后容器为何被重建/重启时非常实用事件流中的die/kill/restart动作配合attributes里的exitCode等属性可以快速还原容器生命周期。适用范围与注意事项事件来源是 Docker 引擎的容器事件因此只能观察到由 Compose 管理带com.docker.compose.projectlabel且非 one-off 的容器docker compose run产生的一次性容器会被 pkg/compose/events.go 显式过滤掉。非容器类型的引擎事件目前不会被输出这是当前实现的限制而非遗漏源码中的 TODO 注释表明这是后续可扩展点。--json输出中type恒为container消费方无需按type再做分支。命令需要能连接到 Docker 守护进程并且当前目录或-f/-p指定的项目可以解析出一个 Compose 项目服务名必须真实存在否则以no such service: name错误退出见 pkg/e2e/events_test.go 的验证。参考命令参考文档docs/reference/compose_events.md命令元数据定义docs/reference/docker_compose_events.yamlCLI 入口实现cmd/compose/events.go事件流与过滤实现pkg/compose/events.go项目过滤器pkg/compose/filters.go事件 API 与输出格式pkg/api/api.goCompose label 常量pkg/api/labels.goE2E 测试pkg/e2e/events_test.go【免费下载链接】composeDefine and run multi-container applications with Docker项目地址: https://gitcode.com/GitHub_Trending/compose/compose创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考