baraverkstad/journald-plus

Docker Journald Plus

Docker Journald Plus是一个Docker托管的日志驱动插件（v2版本），通过docker plugin install安装，提供多行日志合并、优先级解析、JSON日志结构化处理等增强功能，同时保留内置journald驱动的容器元数据字段，且占用空间极小（压缩后仅1.7MB）。可在Docker Hub获取：https://hub.docker.com/r/baraverkstad/journald-plus%EF%BC%8C%E6%9B%B4%E5%A4%9A%E4%BF%A1%E6%81%AF%E8%A7%81GitHub%E4%BB%93%E5%BA%93%EF%BC%9Ahttps://github.com/baraverkstad/docker-journald-plus%E3%80%82

核心功能

• 多行日志合并：根据可配置的正则模式，将连续日志行合并为单个journal条目
• 优先级检测：通过sd-daemon <N>前缀或自定义正则模式从日志内容中推断优先级
• JSON日志解析：可选的结构化解析，从JSON日志中提取级别、消息及自定义字段
• 完整元数据字段：保留内置驱动的所有容器元数据（CONTAINER_ID、CONTAINER_NAME、IMAGE_NAME等）
• 轻量占用：插件镜像仅7.4MB（压缩后1.7MB）

与内置journald驱动对比

1：Docker会为不支持日志读取API的插件自动启用有限的https://docs.docker.com/engine/logging/dual-logging/%E5%8A%9F%E8%83%BD%E3%80%82%E4%B8%BA%E5%AE%9E%E7%8E%B0%E8%BD%BB%E9%87%8F%E5%8D%A0%E7%94%A8%EF%BC%8Cjournald-plus%E7%9C%81%E7%95%A5%E4%BA%86%E8%AF%A5%E5%8A%9F%E8%83%BD%EF%BC%8C%E5%BB%BA%E8%AE%AE%E4%BD%BF%E7%94%A8%60journalctl%60%E6%9F%A5%E7%9C%8B%E5%A4%84%E7%90%86%E5%90%8E%E7%9A%84%E6%97%A5%E5%BF%97%E8%BE%93%E5%87%BA%E3%80%82

输出字段

每个日志条目会写入journald并包含以下字段：

此外还包含以下来源的字段：

• labels/labels-regex：继承自内置驱动的标签选项
• env/env-regex：继承自内置驱动的环境变量选项
• field-*：字段提取功能生成的自定义字段
• json-parse：JSON日志解析生成的字段

使用方法

基本运行示例

bash
docker run --name myapp \
  --log-driver baraverkstad/journald-plus:[VERSION] \
  --log-opt json-parse=true \
  myimage

Docker Compose示例

yaml
services:
  app:
    image: myapp:latest
    logging:
      driver: baraverkstad/journald-plus:[VERSION]
      options:
        json-parse: "true"

设置为默认驱动（/etc/docker/daemon.json）

json
{
  "log-driver": "baraverkstad/journald-plus:[VERSION]",
  "log-opts": {
    "json-parse": "true"
  }
}

👉 查看配置部分获取所有可用选项。

日志读取

docker logs从本地缓存读取原始输出（无合并或解析）。如需查看完整处理后的条目，请使用journalctl：

bash
journalctl -t myapp -f                # 实时跟踪（类似tail -f）
journalctl -t myapp -p warning        # 查看警告及以上级别日志
journalctl -t myapp --since -1h       # 查看最近1小时日志
journalctl CONTAINER_ID=abc123def456  # 按容器ID过滤
journalctl REQUEST_ID=abc123          # 按JSON或field-*生成的自定义字段过滤

高级示例

JSON日志解析

使用默认键解析JSON日志：

bash
docker run --log-driver baraverkstad/journald-plus:[VERSION] \
  --log-opt json-parse=true \
  myapp

应用输出JSON日志：

json
{
  "level": "error",
  "message": "database connection failed",
  "request_id": "abc123",
  "retry_count": 3
}

解析结果：

• MESSAGE=database connection failed
• PRIORITY=3（错误级别）
• JSON_REQUEST_ID=abc123
• JSON_RETRY_COUNT=3

自定义非标准格式的键名（如OpenTelemetry）：

bash
--log-opt json-level-keys='severity,lvl' \
--log-opt json-message-keys='body,text'

跳过高基数字段并将剩余字段内联到消息中：

bash
--log-opt json-skip-keys='ts,time,@timestamp' \
--log-opt json-extra=inline

字段提取

通过正则捕获组从日志消息中提取journal字段：

bash
docker run --log-driver baraverkstad/journald-plus:[VERSION] \
  --log-opt field-REQUEST_ID='request_id=([a-z0-9]+)' \
  --log-opt field-USER_ID='user=(\d+)' \
  --log-opt field-TRACE_ID='trace[:\s]+([a-f0-9]{32})' \
  myapp

Docker Compose中按服务配置：

yaml
services:
  api:
    image: myapi:latest
    logging:
      driver: baraverkstad/journald-plus:[VERSION]
      options:
        field-REQUEST_ID: "request_id=([a-z0-9]+)"
        field-USER_ID: 'user=(\d+)'
  worker:
    image: myworker:latest
    logging:
      driver: baraverkstad/journald-plus:[VERSION]
      options:
        field-JOB_ID: "job=([0-9]+)"

Daemon.json配置（需转义反斜杠）：

json
{
  "log-driver": "baraverkstad/journald-plus:[VERSION]",
  "log-opts": {
    "field-REQUEST_ID": "request_id=([a-z0-9]+)",
    "field-USER_ID": "user=(\\d+)"
  }
}

安装

bash
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
docker plugin install --alias baraverkstad/journald-plus:[VERSION] \
  baraverkstad/journald-plus:[VERSION]-$ARCH

别名baraverkstad/journald-plus:[VERSION]用于在daemon.json、compose.yml或--log-driver中引用。请勿直接使用架构特定的标签，仅别名可跨机器移植。

👉 无latest标签发布。如需最新构建且不固定版本，可使用latest-amd64或latest-arm64，但请注意这会增加升级难度。

升级

正在运行的容器使用的插件无法直接禁用或升级。版本化别名模式允许两个版本共存以实现零停机迁移：

1. 安装新版本并设置新别名：

   bash
   ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
   docker plugin install --alias baraverkstad/journald-plus:[NEW-VERSION] \
     baraverkstad/journald-plus:[NEW-VERSION]-$ARCH
   

2. 更新daemon.json或compose.yml以引用新别名。
3. 若使用daemon.json，重启dockerd以应用新默认驱动。
4. 重新创建服务以逐个切换到新别名。
5. 当无容器引用旧别名时，删除旧版本：

   bash
   docker plugin disable baraverkstad/journald-plus:[OLD-VERSION]
   docker plugin rm baraverkstad/journald-plus:[OLD-VERSION]
   

配置

继承选项

标签模板变量：

示例：--log-opt tag="{{.ImageName}}/{{.Name}}"

👉 内置journald驱动默认标签为{{.ID}}（短容器ID），本插件默认使用{{.Name}}（容器名称），更便于journalctl -t查询。

字段名称 sanitization： 标签和环境变量名称会转换为journald兼容格式：小写转大写，非字母数字字符转为_，以数字开头的名称前缀加_。例如，标签com.example.my-app会转为COM_EXAMPLE_MY_APP。

字段提取

1：选项名称为字段名（如field-REQUEST_ID），值为包含一个捕获组(...)的正则表达式。可使用多个field-*选项。

👉 查看高级示例了解用法。

多行日志

1：匹配该模式的行将追加到前一条消息。设为空字符串可禁用多行合并。
2：支持Go duration格式：10ms、100ms、1s。

默认^\s模式匹配以空白开头的行，可处理Java堆栈跟踪（at com.example.Foo续行缩进）和Python回溯（帧行以空格开头）。

优先级

1：<N>前缀会在写入journal前从MESSAGE中剥离，详见https://www.freedesktop.org/software/systemd/man/latest/sd-daemon.html%E3%80%82%5C 2：默认正则模式（允许关键字前最多30字符前缀）：

• priority-match-crit: ^.{0,30}(CRITICAL|\[Critical\])
• priority-match-err: ^.{0,30}(ERROR|FATAL|\[ERROR\]|\[Fatal\])
• priority-match-warning: ^.{0,30}(WARN|WARNING|\[Warning\])
• priority-match-debug: ^.{0,30}(DEBUG|\[Debug\])

优先级解析顺序（优先匹配靠前的规则）：

1. sd-daemon <N>前缀（若priority-prefix=true）
2. priority-match-*正则模式（从emerg到debug检查）
3. 默认值：priority-default-stdout或priority-default-stderr

优先级名称

priority-default-stdout和priority-default-stderr支持以下值：emerg、alert、crit、err、warning、notice、info、debug。

时间戳剥离

1：journald会记录自身时间戳，应用级时间戳通常冗余。
2：仅当strip-timestamp=true时生效。

启用后，时间戳会在优先级检测前剥离。默认优先级模式允许最多30字符前缀，可处理时间戳剥离后剩余的其他前缀。例如，MariaDB日志2026-02-15 15:15:16 0 [Warning] InnoDB:...剥离后变为0 [Warning] InnoDB:...，仍可匹配[Warning]模式。

内置模式支持以下格式：

时间戳后的分隔符（空白、-、|、:）也会被剥离。时区缩写仅限Z/UTC/GMT，避免误匹配ERROR或WARN等日志级别词。

优先级剥离

1：日志级别同时存在于PRIORITY字段和MESSAGE中通常冗余。
2：仅当strip-priority=true时生效。

启用后，开头的日志级别关键词会在优先级检测后剥离。默认正则匹配消息开头的常见级别关键词（可选带括号）：

(?i)^\[?(trace|debug|info|notice|note|warning|warn|critical|error|fatal|alert|emerg)\]?

匹配后的分隔符（空白、-、|、:）也会被剥离。由于正则锚定到^，仅多行合并消息的首行受影响，续行不会被修改。

空白符规范化

1：将一个或多个制表符（或两个及以上连续空格）替换为单个空格。在处理流程最后一步应用（时间戳剥离和优先级检测/剥离之后）。

JSON日志解析

1：fields（默认）：存储为JSON_*journal字段；inline：追加到MESSAGE中。

当json-parse=true时，驱动尝试解析每条日志行为JSON对象：

1. 级别提取：检查json-level-keys（按顺序）并映射为syslog优先级
2. 消息提取：检查json-message-keys（按顺序）并作为MESSAGE值
3. 跳过键：丢弃json-skip-keys中的键
4. 剩余字段：存储为JSON_*journal字段（json-extra=fields）或追加到消息中（json-extra=inline）；为空则忽略
5. 优雅降级：若解析失败或无消息键，使用原始行

支持的级别映射：

级别字符串不区分大小写。

👉 查看高级示例了解用法。

行为说明：

• 字段名称会转换为journald兼容格式（大写，特殊字符转为_）
• 嵌套JSON对象/数组会序列化为JSON字符串
• 空值会被忽略
• 解析失败时，原始行将被原样记录（无数据丢失）
• 禁用时无额外开销（仅一次布尔检查）

贡献

欢迎提出想法、bug报告和PR。查看DEVELOPMENT.md获取构建说明、测试及开发流程。

许可证

Docker Journald Plus基于MIT许可证开源。

版权所有 © 2026 Per Cederberg