# 日志配置

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

::: tip

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

:::

EMQX 支持两种主要的日志输出方式：控制台输出日志和文件输出日志。另外还一个[审计日志](../dashboard/audit-log.md)，始终将日志输出定向到文件。

系统的默认日志输出可以通过环境变量 `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` 文件，如下所示：

```bash
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` 为自由文本。<br /> `json` 为结构化日志。              |
| `level`            | 日志级别         | 设置当前日志输出的日志级别，即您想要记录的最低日志级别。 | `warning`  | `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency` |
| `path`             | 日志文件名称     | 设置日志文件的路径和名称。<br />默认情况下，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`格式。<br />`epoch`: 以微秒精度的 Unix 纪元时间格式。<br />`rfc3339`: 符合 RFC3339 标准的日期时间字符串格式。 |

## 控制台输出日志

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

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

其中，

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

::: tip

EMQX 提供了更多配置项以更好地满足定制化需求。详情请参见 [EMQX 企业版配置手册](https://docs.emqx.com/zh/enterprise/v6.3.1/hocon/)。

:::

## Docker 中的崩溃转储文件

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

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

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

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

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

```bash
docker run -d --name emqx \
  -v $PWD/log:/opt/emqx/log \
  emqx/emqx-enterprise:6.3.1
```

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

```bash
docker logs emqx
```

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

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

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