SuperAPI AI 工具集

telemetry-essentials

部署与运维

查看项目

更新于 10-15 22:17

技能介绍

用途:该技能用于 Elixir/Phoenix 项目中的遥测、日志与可观测性工作,要求在编写任何 telemetry 处理器、Logger 调用或指标代码之前先使用。

主要能力与规则:使用结构化日志 Logger.info("action", key: value),禁止在日志消息中做字符串插值;在 Application.start/2 中挂载 telemetry 处理器,不要放在可能重启的模块或 GenServer init 中;使用 Ecto.Repo 的 telemetry 事件监控查询,不手动埋点;在 dev/staging 使用 Phoenix.LiveDashboard;为事件附加 user_id、request_id 等关联元数据;生产环境不要使用 :debug 级别,改用 :info,因为 :debug 会包含查询参数和 PII。

使用方式:可用 :telemetry.execute 发出自定义事件,参数依次为事件名、measurements、metadata;用 :telemetry.attach_many 挂载处理器并实现 handle_event/4;用 :telemetry.span 包裹操作。可在 iex -S mix 中执行事件验证处理器是否生效。LiveDashboard 通过 router.ex 中的 live_dashboard 挂载,并配置 metrics 与 ecto_repos。

适用场景:Phoenix 应用的日志规范化、自定义事件埋点、慢查询监控、开发与预发环境可观测性。

限制与注意:handle_event/4 中不要做重活,以免阻塞调用方;处理器应保持快速,慢任务转交进程或队列;事件需带关联元数据,否则追踪无意义。性能剖析见 benchee-profiling 技能,指标导出与生产部署见 deployment-gotchas 技能,底层指标聚合参考 Telemetry.Metrics 与 TelemetryMetricsPrometheus 文档。