日志配置

本页主要介绍如何通过配置文件配置 EMQX 的日志记录行为。您也可以通过 Dashboard 来配置 EMQX 日志。如果通过 Dashboard 配置，您可以点击左侧导航菜单的 管理 -> 日志 进行配置。有关日志和 Dashboard 配置的更详细描述，请参见日志与可观测性 - 日志。

TIP

本页面还介绍了与配置项对应的 Dashboard UI字段。 如果您通过 Dashboard 配置了这些项，新设置将只能临时覆盖 emqx.conf 中相同的配置项，直到下次重启。

EMQX 支持两种主要的日志输出方式：控制台输出日志和文件输出日志。另外还一个审计日志，始终将日志输出定向到文件。

系统的默认日志输出可以通过环境变量 EMQX_DEFAULT_LOG_HANDLER 配置，它接受以下设置：

• file：将日志输出定向到文件。
• console：将日志输出定向到控制台。

环境变量 EMQX_DEFAULT_LOG_HANDLER 的默认值为 console，但当通过 systemd 的 emqx.service 文件启动EMQX 时，明确设置为 file。

文件输出日志

使用 RPM 或 DEB 包安装时，EMQX_LOG_DIR 默认为 /var/log/emqx。从 EMQX 6.3.0 开始，/opt/emqx/log 是指向该目录的符号链接（symlink）。该符号链接始终指向 /var/log/emqx。修改 EMQX_LOG_DIR 不会更新该符号链接。

对于其他安装方式，默认日志目录为 EMQX 安装目录下的 log。在 Docker 容器中，该路径为 /opt/emqx/log。

要将日志输出到文件，您可以在 Dashboard 上配置文件日志输出，或直接修改 emqx.conf 文件，如下所示：

log {
  file {
    enable = true
    formatter = text
    level = warning
    path = "/var/log/emqx/emqx.log"
    rotation_count = 10
    rotation_size = 50MB
    time_offset = system
    timestamp_format = auto
  }
}

其中，

配置项	Dashboard UI	描述	默认值	可选值
formatter	日志格式类型	设置日志格式。	text	text 为自由文本。 json 为结构化日志。
level	日志级别	设置当前日志输出的日志级别，即您想要记录的最低日志级别。	warning	debug, info, notice, warning, error, critical, alert, emergency
path	日志文件名称	设置日志文件的路径和名称。 默认情况下，EMQX 将日志文件写入EMQX 安装目录下的 log 目录中的 emqx.log 文件。	emqx.log	--
rotation_count	最大日志文件数	设置可以保存的最大日志文件数量。	10	1 - 2,048
rotation_size	日志文件轮换大小	在轮换前单个日志文件的最大大小。达到指定值时，旧日志文件将被重命名并移动到归档目录，除非设置为 infinity，表示日志文件不会被轮换。	50MB	1 - infinity
time_offset	时间偏移量	定义日志中时间相对 UTC 的偏移量，默认情况下跟随系统。	system	--
timestamp_format	时间戳格式	从下拉列表中选择日志时间戳格式。	auto	auto: 根据所使用的日志格式类型自动确定时间戳格式。对于文本格式类型，使用 rfc3339 格式；对于 JSON 格式类型，则使用 epoch格式。 epoch: 以微秒精度的 Unix 纪元时间格式。 rfc3339: 符合 RFC3339 标准的日期时间字符串格式。

控制台输出日志

当 EMQX 在 Docker 容器中启动时，默认日志输出为 console。您可以通过以下配置项配置日志级别和日志格式。

log {
  console {
    formatter = json
    level = warning
    time_offset = system
    timestamp_format = auto
  }
}

其中，

配置项	Dashboard UI	描述	默认值	可选值
formatter	日志格式类型	设置日志格式。	text	text 为自由文本。 json 为结构化日志。
level	日志级别	设置当前日志输出的日志级别，即您想要记录的最低日志级别。	warning	debug, info, notice, warning, error, critical, alert, emergency
time_offset	时间偏移量	定义日志中时间相对 UTC 的偏移量，默认情况下跟随系统。	system	--
timestamp_format	时间戳格式	从下拉列表中选择日志时间戳格式。	auto	auto: 对于文本格式类型，使用 rfc3339 格式；对于 JSON 格式类型，则使用 epoch格式。 epoch: 以微秒精度的 Unix 纪元时间格式。 rfc3339: 符合 RFC3339 标准的日期时间字符串格式。

TIP

EMQX 提供了更多配置项以更好地满足定制化需求。详情请参见 EMQX 企业版配置手册。

Docker 中的崩溃转储文件

Erlang 虚拟机异常终止时，会在日志目录下写入崩溃转储文件 erl_crash.<timestamp>.dump，在容器中该目录为 /opt/emqx/log。该文件记录了节点宕机瞬间的状态，是排查崩溃问题的主要依据。

控制台日志无法保留崩溃转储文件。控制台日志处理器将运行日志写入容器的标准输出，您可以通过 docker logs 查看这些日志。崩溃转储则单独写入文件。如果未挂载日志目录，删除容器后将无法保留转储文件。

启动 EMQX 前，创建宿主机目录，并确保容器内的 emqx 用户（UID 1000）对该目录具有写权限：

mkdir -p $PWD/log && sudo chown 1000:1000 $PWD/log

启动 EMQX 时，将该目录挂载到 /opt/emqx/log：

docker run -d --name emqx \
  -v $PWD/log:/opt/emqx/log \
  emqx/emqx-enterprise:6.3.0

崩溃后，运行以下命令查看容器输出：

docker logs emqx

如果以下日志以 done 结尾，则表示转储文件已完整写入：

Crash dump is being written to: /opt/emqx/log/erl_crash.2026.08.31.06.56.22.dump...done

崩溃转储文件可能达到数十 MB。请评估挂载目录的磁盘空间，并可通过 node.crash_dump_bytes 限制文件大小。