SuperAPI AI 工具集

telemetry-events

部署与运维

查看项目

更新于 10-16 08:38

技能介绍

用途:为 RWX CLI 添加遥测事件,规范事件命名、属性约定、采集器注入方式与错误分类,确保遥测数据可用于告警与仪表盘。

主要能力:CLI 在 internal/telemetry/ 中提供两种类型——*telemetry.Collector 是线程安全的事件队列,方法为 Record(event string, props map[string]any),用于传入内部包;*telemetry.Telemetry 是编排器,持有 Collector、Sender 与 StatsRoundTripper,负责进程退出时 Flush(),用于 cmd 层。cmd/rwx/root.go 中定义 telem 与 telemetryCollector 两个包级变量。

事件命名:采用 <area>.<action> 点分格式,如 cli.command、cli.error、api.summary、lsp.node_check。名称应描述子系统与可观测时刻,而非结果;结果用 status 属性分桶。

使用方式:cmd 层可直接调用 telem.Record,Telemetry 对 nil 容忍,无需判空。内部包应显式接收 *telemetry.Collector,可用结构体字段(Pattern A)或函数参数/配置结构体字段(Pattern B),并在函数内用闭包做 nil 容忍,再由 cmd/rwx/ 注入。

属性约定:props 为 map[string]any;分类状态放入 status 字符串而非布尔值,便于后续扩展;需要下钻时附带原始值;键名用 snake_case;记录前剥离 PII 与超长字符串;时间戳、OS、架构由信封自动添加。

错误与 cli.error:命令级错误记录为 cli.error,含 error_type(由 classifyError 与 errors.Is 对照 internal/errors/errors.go 哨兵得出)与 handled(是否包装 HandledError)。未分类且未处理的错误还会附带经 scrubErrorMessage 处理的 error_message。新增错误路径需用 errors.WrapSentinel 包装哨兵,否则会被归类为 unknown;若无合适哨兵,需新增哨兵并在 classifyError 与 TestClassifyError 中补充。已向用户展示的错误应包装 HandledError。

测试:使用真实 *telemetry.Collector 与 Drain() 检查事件,无需 mock;已有传 nil 的测试保持原样。

限制:遥测为尽力而为,绝不能阻塞 CLI;测试、MCP 入口与库消费者可能传入 nil。