企业官网建设流程全解析

EMQX Trace API 配置查看与更新：/tracing接口实现与实战解析

【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx

导读

EMQX 的在线追踪（Trace）功能允许按客户端 ID、主题、IP 地址或规则 ID 对消息收发过程进行实时记录，而全局追踪配置（单文件大小上限、最大追踪任务数等）则决定了该功能的运行边界。本篇文章围绕changes/ee/feat-15904.en.md所记录的"通过 Trace API 查看与更新追踪配置"这一能力，深入解析 EMQX 管理接口中GET /tracing与PUT /tracing两个端点的实现原理、字段含义、校验规则与多租户权限约束。读完本文，你将掌握如何通过 REST API 查询和调整集群级 Trace 配置，并理解这些配置如何影响线上追踪任务的创建与日志输出。

一、特性背景：Trace API 中的配置端点

changes/ee/feat-15904.en.md记录了这样一项变更：

Support viewing and updating of tracing configuration through Trace API.

（通过 Trace API 支持查看和更新追踪配置。）

在 EMQX 中，trace相关 REST API 由 apps/emqx_management/src/emqx_mgmt_api_trace.erl 这一模块统一承载（namespace 为trace，采用minirest_api行为实现）。该模块声明的全部路由如下：

其中schema("/tracing")与config/2处理器即对应本次变更新增的配置查看与更新能力。追踪任务的创建、启停、日志读取等既有能力则作为上下文，帮助我们理解配置项的实际作用。

二、查看全局追踪配置：GET /tracing

2.1 请求与响应

GET /api/v5/tracing

对应源码中的config(get, #{}) -> {200, get_config_root()}，其中get_config_root/0的实现为：

get_config_root() -> RawConf = emqx:get_raw_config([?CONF_ROOT]), RootConf = emqx_config:fill_defaults(#{?CONF_ROOT => RawConf}), maps:get(?CONF_ROOT, RootConf).

即先从配置中心读取trace根的原始配置（?CONF_ROOT定义为<<"trace">>），再通过emqx_config:fill_defaults/1填充缺失字段的默认值，最终返回完整配置对象。因此即使集群从未显式配置过 Trace 参数，该接口也会返回带默认值的完整配置。

以全新部署的 EMQX 为例，响应示例：

{ "max_file_size": "128MB", "max_traces": 30 }

2.2 默认值与字段来源

GET /tracing返回的字段与默认值定义在 apps/emqx/src/emqx_schema.erl 的fields("trace")中：

• max_file_size：单个 Trace 日志文件的最大大小，类型为字节数（bytesize()），默认128MB，合法取值范围为100KB到10GB（由mk_validator_bounds({100 * ?KB, "100KB"}, {10 * ?GB, "10GB"})约束），配置优先级标记为IMPORTANCE_LOW；
• max_traces：集群中允许同时存在的 Trace 任务最大数量，类型为range(0, 100)，默认30；
• payload_encode：历史遗留字段，默认text，自5.0.22起标记为deprecated（{deprecated, {since, "5.0.22"}}），配置优先级为IMPORTANCE_HIDDEN，建议改用每个 Trace 任务自身的payload_encode参数。

对应的中文/多语言描述位于 rel/i18n/emqx_schema.hocon 与 rel/i18n/emqx_mgmt_api_trace.hocon。

三、更新全局追踪配置：PUT /tracing

3.1 请求与响应

PUT /api/v5/tracing Content-Type: application/json { "max_file_size": "256MB", "max_traces": 50 }

对应源码中的config(put, #{body := NewConf})：

config(put, #{body := NewConf}) -> UpdateOpts = #{rawconf_with_defaults => true, override_to => cluster}, case emqx_conf:update([?CONF_ROOT], NewConf, UpdateOpts) of {ok, #{raw_config := _}} -> {200, get_config_root()}; {error, Reason} -> ?BAD_REQUEST(<<"INVALID_CONFIG">>, Reason) end.

关键实现细节：

• 更新操作通过emqx_conf:update([<<"trace">>], NewConf, ...)写入配置中心，override_to => cluster表示配置会覆盖并同步到整个集群，而非仅当前节点；
• rawconf_with_defaults => true确保响应中未显式设置的字段同样以默认值形态返回；
• 更新成功后返回200及更新后的完整配置；校验失败返回400，错误码为INVALID_CONFIG。

3.2 常见错误码

schema("/tracing")中声明的错误响应包括：

四、配置校验与测试验证

emqx_mgmt_api_trace_SUITE中的t_config测试用例（见 apps/emqx_management/test/emqx_mgmt_api_trace_SUITE.erl）完整覆盖了上述行为，可作为接入调试的参照：

1. 默认值查询：GET /tracing返回max_file_size = "128MB"、max_traces = 30；
2. 空更新：PUT /tracing提交{}不会产生任何变更，返回的仍是默认配置（注意：经配置子系统处理，max_file_size的值形态会从字符串"128MB"变为字节数134217728）；
3. 非法更新被拒绝：提交未知字段（如encoding）或非法值（如max_file_size = 1）均返回400 BAD_REQUEST；
4. 配置即时生效：将max_traces更新为0后，再调用POST /trace创建追踪任务，会得到400 EXCEED_LIMIT，错误信息提示 "Creating traces is disallowed"；这也印证了max_traces = 0时创建任务被完全禁止的分支逻辑（见emqx_mgmt_api_trace.erl中trace(post, ...)对max_limit_reached的处理：Limit为0时返回"禁止创建"，否则提示先删除过期任务）。

因此，PUT /tracing更新是即时生效的，max_traces会在下一次创建 Trace 时作为硬性上限被强制检查。

五、配置与 Trace 任务 API 的联动

理解/tracing配置的价值，需要结合trace命名空间下的任务管理 API。创建追踪任务的POST /trace请求体字段定义在fields(trace)中：

创建时emqx_trace:create/1会执行去重与上限检查（apps/emqx/src/emqx_trace/emqx_trace.erl）：同名任务返回409 ALREADY_EXISTS，相同过滤条件返回409 DUPLICATE_CONDITION，超过max_traces上限返回400 EXCEED_LIMIT。任务状态由emqx_trace:status/2判定：

• enable = false→stopped；
• 当前时间早于start_at→waiting；
• 当前时间晚于end_at→stopped；
• 否则 →running。

此外，GET /trace/:name/download会将各节点日志聚合成 zip 归档返回（application/x-zip），GET /trace/:name/log支持按bytes（默认 1000，上限 64MB）、position（base62 编码游标，配合hint为eof/retry的元数据实现增量拉取）、node参数流式读取日志，详情见 apps/emqx_management/src/emqx_mgmt_api_trace.erl 中stream_trace_log/4相关实现。这些能力共同构成了完整的"创建 → 查询 → 消费日志 → 停止/删除"工作流。

六、权限与多租户约束

/tracing配置端点对调用者身份有严格限制。模块中通过filter/2解析请求命名空间（resolve_namespace），并结合emqx_dashboard_rbac的scopes()（返回?SCOPE_MONITORING）进行鉴权。关键约束如下：

• 只有全局管理员（global namespace）可以调用PUT /tracing修改配置，命名空间（多租户）用户即使具备监控权限也会收到403 UNAUTHORIZED_ROLE，对应错误描述trace_config_global_only；
• 命名空间用户在POST /trace时可通过ns查询参数指定归属命名空间，但仅允许操作自己命名空间内的资源，跨命名空间操作一律拒绝；全局管理员则可见全部任务（相关逻辑见lookup_trace_in_namespace/2，跨命名空间与不存在统一返回404 NOT_FOUND，避免泄露其他命名空间的任务存在性）；
• 测试用例t_namespaced_user_cannot_update_config（见 apps/emqx_management/test/emqx_mgmt_api_trace_SUITE.erl）验证了：普通命名空间用户 PUT 配置失败、全局管理员可成功将max_traces与max_file_size修改为1/"64MB"并同步到整个集群。

七、集群一致性说明

GET /tracing返回的是集群级统一配置。当集群由多节点组成时，配置的读取与写入均基于 EMQX 的配置子系统（emqx_conf）与 mria 表（?TRACE表，由 apps/emqx/src/emqx_trace/emqx_trace.erl 管理），而日志文件本身分布在各节点本地磁盘。因此：

• 查看各节点日志大小时，GET /trace/:name/log_detail会通过emqx_mgmt_trace_proto_v3发起集群 RPC（仅向支持 bpapi v3 的节点查询），返回每个节点的size与mtime；
• 下载日志时，GET /trace/:name/download同样按节点聚合后打包为 zip，文件名形如节点名-任务名-起始时间.log；
• 在滚动升级等节点版本不一致的场景下，POST /trace可能返回409 BAD_TYPE（提示 "Rolling upgrade in progress, create failed"），这是emqx_bpapi版本协商机制的一部分，属预期行为。

八、小结与排查建议

/tracing端点是运维 EMQX 在线追踪功能的重要入口：GET用于确认当前全局配置与默认值，PUT用于动态调整max_file_size与max_traces并即时同步到整个集群。实际使用中可遵循以下排查路径：

1. 创建 Trace 时收到400 EXCEED_LIMIT→ 先GET /tracing检查max_traces是否已被调小或为0，再DELETE /trace/:name清理过期任务；
2. 日志文件异常增大或写入受限 → 检查max_file_size是否接近单文件上限，必要时通过PUT /tracing调大（不超过10GB）；
3. 多租户环境下配置修改被拒 → 确认调用方为全局管理员账号，而非命名空间用户。

本文涉及的源码与测试可直接在仓库中进一步研读：API 实现、配置 Schema、Trace 核心模块、接口测试套件。

【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx