# 日志

通过 EMQX 的日志功能，您可查看客户端访问、操作系统或网络异常等问题，如登录错误，异常访问，性能故障等等，并基于日志信息进行问题排查或系统性能优化。

EMQX 支持两种不同的日志输出方式：控制台输出日志和文件输出日志。您可以根据需要选择输出方式或同时启用这两种方式。将日志数据输出到控制台或命令行界面通常在开发和调试过程中使用，这样开发人员能实时快速查看EMQX运行时的日志数据。将日志数据输出到文件通常在生产环境中使用，随着时间进展、日志数据能够被持久化以便进行分析和故障排除。

此外，为避免日志数据过多或日志写入过慢等问题，EMQX 默认开启了过载保护机制，以确保正常业务不被日志影响。

# 日志级别

EMQX 日志包含 8 个等级 (RFC 5424 (opens new window))，默认为 warning 级别，由低到高分别为：

debug < info < notice < warning < error < critical < alert < emergency

下面的表格描述了每个日志级别的含义和输出内容。

日志级别	含义	输出内容
debug	调试级别的日志，包含最详细的信息和调试数据。仅在需要进行详细调试时才使用此级别的日志。不建议在生产环境直接输出该级别日志，可以使用日志追踪为指定客户端开启。	通常包含最详细的调试信息、变量值、函数调用栈等信息。
info	提供有用的信息，比 debug 级别的日志更粗略	如客户端连接、订阅、发布、QoS 等级别、消息传递等信息。
notice	提供重要的系统信息，表示有事件发生但不需要采取行动。	例如，连接到代理服务器的客户端数量、重连次数、崩溃的节点数量等。
warning	表示存在潜在的问题或错误，需要采取一定的行动；此级别的日志通常用于发现问题和错误之前的预警。	连接断开、连接超时、认证失败等情况。
error	表示出现了错误，需要进行错误处理；此级别的日志通常用于标记错误，以便管理员可以快速检测和解决问题	无法连接到外部数据库、订阅的主题不存在、未能解析配置文件等。
critical	表示出现了严重错误，导致系统崩溃或无法继续工作；此级别的日志通常用于标记严重问题，以便管理员可以尽快采取行动。	代理服务器崩溃、数据库无法访问等。
alert	表示需要立即采取行动，以防止进一步的损失；此级别的日志记录将触发警报通知操作，并且可能导致应用程序的停止。	例如，应用程序已达到关键阈值，例如磁盘空间或内存耗尽，或关键系统进程已崩溃或停止响应。
emergency	导致系统无法继续运行的严重错误；这种级别的日志通常只会在极少数情况下出现，并且需要立即对其进行处理。	例如，EMQX 节点间数据同步失败

# 修改日志配置

您可通过 EMQX Dashboard 或者配置文件修改日志配置。比如，如果您想要将级别为 warning 的日志输出到日志文件和控制台，您可以在 emqx.conf 文件中修改 log 下的配置项，参见下面示例。重启节点后配置生效。

log {
  file_handlers.default {
    level = warning
    file = "log/emqx.log"
    count = 10
    max_size = 50MB
    formatter = text
  }
  console_handler {
    level = warning
    formatter = text
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13

本章节将主要介绍如何通过 EMQX Dashboard 修改日志配置。保存修改后将立即生效，无需重启节点。

点击左侧导航栏的管理-> 日志。选择相应的页签配置控制台输出日志或文件输出日志。

# 控制台输出日志

在日志页面，选择控制台日志页签。

配置控制台日志处理进程的常规选项：

启用日志处理进程：单击切换开关以启用控制台日志处理进程。
日志级别：从下拉列表中选择要使用的日志级别。可选值为：debug, info, notice, warning, error, critical, alert, emergency 。默认值为：warning。
时间偏移量：定义日志中时间戳的格式。默认情况下为 system。
单条日志长度限制：默认禁用，即不限制单条日志消息的最大长度。如果您启用切换开关，则可以指定最大长度。当长度超过限制时，日志消息将被截断。
日志格式类型：从下拉列表中选择日志格式。可选值为：text 和 json。默认值为 text。
注意：如果选择 json，建议禁用 单条日志最大长度，否则 json 数据不会完整显示。
单行模式：默认启用。如果禁用，日志消息打印时会自动换行。
进入同步模式的队列长度：设置缓冲日志事件的数量限制。如果消息队列超过设置值，则处理进程开始同步处理日志事件，这表明发送事件的客户端进程必须等待响应。默认设置为 100。
进入丢弃模式的队列长度：设置缓冲日志事件的数量限制。如果消息队列超过设置值，则处理程序开始丢弃新的日志事件。默认设置为 3000。
冲刷阈值：设置缓冲日志事件的数量阀值。如果超过设置的阀值，处理进程会开始丢弃缓冲的日志消息。默认设置为 8000。
日志处理进程超载保护: 默认启用，即当日志处理程序超载时，将会终止该进程。
日志处理进程允许使用的最大内存: 输入数值来指定日志处理程序允许使用的最大内存。从下拉列表中选择单位，可选值为：MB，GB 和 KB。默认值为 30 MB。
最大队列长度: 在文本框中输入数值来指定允许的最大队列长度。默认值为 2000。
处理进程重启延迟: 默认启用，这意味着在处理程序终止后，会自动延迟一段时间后重新启动。您可以在文本框中指定延迟时间，并从下拉列表中选择单位。可选值为 milliseconds、second、minute 和 hour。默认值为 5 second。如果您禁用改选项，该值将为 infinity，这将阻止任何后续的重启。
日志限流保护: 默认启用日志限流保护机制。
日志事件数: 指定在 window_time 时间间隔内要处理的最大日志事件数。默认值为 10000。
Window Time: 指定处理日志事件的时间窗口。从下拉列表中选择单位，可选值为 milliseconds，second，minute 和 hour。默认值为 1 second。
报告类型: 从下拉列表中选择类型。可选值为：error 和 progress。默认值为 error。
最大深度: 默认启用。您可以指定 Erlang 术语日志格式和 Erlang 进程消息队列检查的最大深度。您可以使用数字微调器来增加或减少该值。

完成配置后，点击 保存更改。

# 文件输出日志

在日志页面，选择文件日志页签。

配置控制台日志处理进程的常规选项：

启用日志处理进程：单击切换开关以启用文件日志处理进程。
日志文件名字：填写日志文件的名称。默认为log/emqx.log。
日志轮换：默认启用，启用后生成日志文件后缀会加上对应的索引数字。
最大日志文件数：轮换的最大日志文件数。默认值为10。
日志文件轮换大小：设置日志文件大小，达到设定的值时日志文件将进行轮换。如果禁用，则日志文件将无限增长。可在文本框输入设定的值，在下拉列表中选择单位，可选值为：MB, GB, KB。
日志级别：从下拉列表中选择要使用的日志级别。可选值为：debug, info, notice, warning, error, critical, alert, emergency 。默认值为：warning。
时间偏移量：定义日志中时间戳的格式。默认情况下为 system。
单条日志长度限制：默认禁用，即不限制单条日志消息的最大长度。如果您启用切换开关，则可以指定最大长度。当长度超过限制时，日志消息将被截断。
日志格式类型：从下拉列表中选择日志格式。可选值为：text 和 json。默认值为 text。
注意：如果选择 json，建议禁用 单条日志最大长度 的切换开关，否则 json 数据不会完整显示。
单行模式：默认启用。如果禁用切换开关，日志消息打印时会自动换行。
进入同步模式的队列长度：设置缓冲日志事件的数量限制。如果消息队列超过设置值，则处理进程开始同步处理日志事件，这意味着发送事件的客户端进程必须等待响应。默认设置为 100。
进入丢弃模式的队列长度：设置缓冲日志事件的数量限制。如果消息队列超过设置值，则处理程序开始丢弃新的日志事件。默认设置为 3000。
冲刷阈值：设置缓冲日志事件的数量阀值。如果超过设置的阀值，处理进程会开始丢弃缓冲的日志消息。默认设置为 8000。

参照控制台输出日志继续配置日志处理进程过载保护和日志限流保护功能选项。完成配置后，点击保存修改。

在文件日志启用后，日志目录下会有如下几种文件:

emqx.log.N: 以 emqx.log 为前缀的文件为日志文件，包含了 EMQX 的所有日志消息。比如 emqx.log.1、emqx.log.2 ...
emqx.log.siz 和 emqx.log.idx: 用于记录日志滚动信息的系统文件，请不要手动修改。
run_erl.log: 以 emqx start 方式后台启动 EMQX 时，用于记录启动信息的系统文件。
erlang.log.N: 以 erlang.log 为前缀的文件为日志文件，是以 emqx start 方式后台启动 EMQX 时，控制台日志的副本文件。比如 erlang.log.1、erlang.log.2 ...

# 日志格式

日志消息的格式为（各个字段之间用空格分隔）：

**date time level key-value-struct**

其中：

date-time: 当地时间的日期。格式为：RFC3339
level: 日志级别，使用中括号包裹。格式为：[Level]
flat log-content：扁平化日志消息内容。

# 日志消息举例 1：

2022-06-30T16:07:47.689512+08:00 [debug] clientid: test, line: 792, mfa: emqx_connection:handle_incoming/2, msg: mqtt_packet_received, packet: PINGREQ(Q0, R0, D0), payload: [], peername: 127.0.0.1:64391, tag: MQTT

此日志消息里各个字段分别为:

datetime: 2022-06-30T15:59:19.438914+08:00
level: [debug]
flat log-content: clientid: test, line: 792, mfa: emqx_connection:handle_incoming/2, msg: mqtt_packet_received, packet: PINGREQ(Q0, R0, D0), payload: [], peername: 127.0.0.1:64391, tag: MQTT

这条日志表示 EMQX 在 2022-06-30T16:07:47.689512+08:00 时 Client ID 为 test 客户端收到了一个 PINGREQ(Q0,R0,D0) 包。对应客户端的 IP 为 127.0.0.1:64391。

# 日志消息举例 2：

2022-06-30T16:25:32.446873+08:00 [debug] line: 150, mfa: emqx_retainer_mnesia:store_retained/2, msg: message_retained, topic: $SYS/brokers/emqx@127.0.0.1/sysdescr

此日志消息里各个字段分别为:

date-time: 2022-06-30T16:25:32.446873+08:00
level: [debug]
flat log-content: line: 150, mfa: emqx_retainer_mnesia:store_retained/2, msg: message_retained, topic: $SYS/brokers/emqx@127.0.0.1/sysdescr

← 告警主题监控 →