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

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行为实现。该模块声明的全部路由如下方法路径用途GET / POST / DELETE/trace列出、创建、清空全部追踪任务DELETE/trace/:name按名称删除追踪任务PUT/trace/:name/stop停止指定追踪任务GET/trace/:name/download下载追踪日志zip 归档GET/trace/:name/log流式读取追踪日志GET/trace/:name/log_detail查看各节点日志文件大小与修改时间GET / PUT/tracing查看 / 更新全局追踪配置本文主题其中schema(/tracing)与config/2处理器即对应本次变更新增的配置查看与更新能力。追踪任务的创建、启停、日志读取等既有能力则作为上下文帮助我们理解配置项的实际作用。二、查看全局追踪配置GET /tracing2.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_LOWmax_traces集群中允许同时存在的 Trace 任务最大数量类型为range(0, 100)默认30payload_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 /tracing3.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)中声明的错误响应包括状态码错误码含义400INVALID_CONFIG提交的配置不合法类型错误、超出取值范围、包含未知字段等403UNAUTHORIZED_ROLE非全局管理员尝试修改配置详见第七节四、配置校验与测试验证emqx_mgmt_api_trace_SUITE中的t_config测试用例见 apps/emqx_management/test/emqx_mgmt_api_trace_SUITE.erl完整覆盖了上述行为可作为接入调试的参照默认值查询GET /tracing返回max_file_size 128MB、max_traces 30空更新PUT /tracing提交{}不会产生任何变更返回的仍是默认配置注意经配置子系统处理max_file_size的值形态会从字符串128MB变为字节数134217728非法更新被拒绝提交未知字段如encoding或非法值如max_file_size 1均返回400 BAD_REQUEST配置即时生效将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)中字段类型必填说明namestring是任务名须匹配^[A-Za-z][A-Za-z0-9-_]*$且长度 ≤ 256typeenum是过滤类型clientid/topic/ip_address/ruleidtopicstring否主题过滤支持通配符如/dev/#clientidstring否客户端 ID 过滤ip_addressstring否客户端 IP 过滤ruleidstring否规则 ID 过滤start_at/end_atRFC3339 时间否追踪窗口默认从当前时间开始payload_encodeenum否负载编码hex/text/hidden默认textpayload_limitinteger否负载最大记录字节数默认1024formatterenum否日志格式text/json创建时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-zipGET /trace/:name/log支持按bytes默认 1000上限 64MB、positionbase62 编码游标配合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并即时同步到整个集群。实际使用中可遵循以下排查路径创建 Trace 时收到400 EXCEED_LIMIT→ 先GET /tracing检查max_traces是否已被调小或为0再DELETE /trace/:name清理过期任务日志文件异常增大或写入受限 → 检查max_file_size是否接近单文件上限必要时通过PUT /tracing调大不超过10GB多租户环境下配置修改被拒 → 确认调用方为全局管理员账号而非命名空间用户。本文涉及的源码与测试可直接在仓库中进一步研读API 实现、配置 Schema、Trace 核心模块、接口测试套件。【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考