cmdc_skill_engine 标准 :telemetry 事件契约。
本模块只暴露事件 schema + emit 辅助函数，本身不挂任何 handler。集成方
（Studio / Hive / 其它 BaaS）用 :telemetry.attach_many/4 接入即可。
设计原则
- 零强制依赖 —
:telemetry已是 BEAM 生态事实标准 - 事件命名稳定 — schema 锁定 +
schema_version标签 - metadata 字段白名单 — 明确列出，避免敏感字段意外泄露
- inline emit 而非异步 — handler 必须自行 fast；慢 handler 会阻塞 Store GenServer，请在 handler 内异步分发
事件清单（v0.3，共 4 事件）
| 事件名 | 触发时机 | measurements | metadata |
|---|---|---|---|
[:cmdc_skill_engine, :analyzer, :analyze, :start] | Analyzer 开始分析 session | %{system_time} | %{session_id, scope, analysis_model, selected_skill_count} |
[:cmdc_skill_engine, :analyzer, :analyze, :stop] | Analyzer 分析完成（含降级到规则路径） | %{duration_ms} | %{session_id, scope, analysis_model, task_completed, suggestion_count, fallback?} |
[:cmdc_skill_engine, :evolution, :emitted] | Evolver 成功产出新 SkillRecord | %{count: 1} | %{evolution_type, skill_id, scope, parent_skill_ids, name, source_task_id} |
[:cmdc_skill_engine, :store, :record_updated] | Store 完成 save_record 或 update_counters | %{count: 1} | %{skill_id, scope, operation, name} |
evolution_type取值:fix | :derived | :capturedoperation取值:save | :counters_incrementedscope当前 v0.3 PR-1 默认"global"；PR-2 多租户支持完成后承载真实租户 IDfallback?表示 LLM 分析失败被降级到规则分析
Quick Start
# 1) 开发期 logger
CMDCSkillEngine.Telemetry.attach_logger()
# 2) 集成方挂自定义 handler
:telemetry.attach_many(
"studio-skill-engine-bridge",
CMDCSkillEngine.Telemetry.all_events(),
&MyApp.SkillBridge.handle_event/4,
nil
)
def handle_event([:cmdc_skill_engine, :evolution, :emitted], _meas, meta, _) do
# 异步派发到 Phoenix Channel / Kafka / ...
Task.Supervisor.start_child(MyApp.TaskSup, fn ->
MyApp.Skills.upsert(meta.skill_id, meta.scope)
end)
end
# 3) detach
:telemetry.detach("studio-skill-engine-bridge")schema_version
所有事件 metadata 自动注入 :schema_version（当前 1）。集成方可据此做
字段变更感知（v0.4+ 引入新字段时 bump version + 文档说明）。
Summary
Functions
返回当前所有 cmdc_skill_engine telemetry 事件名称。
附加一个开发期 Logger handler，所有 cmdc_skill_engine 事件打到 console。
Detach 开发期 Logger handler。
Evolver 成功产出新 SkillRecord 时调用。
Store 完成一次记录写入时调用。
低阶 emit，自动注入 schema_version。一般不直接调用，用各类 helper。
返回 telemetry schema 版本号。
包装一次 analyze 过程，自动 emit analyze :start / analyze :stop，
并把 :duration_ms 计入 measurements。
Functions
@spec all_events() :: [[atom()]]
返回当前所有 cmdc_skill_engine telemetry 事件名称。
附加一个开发期 Logger handler，所有 cmdc_skill_engine 事件打到 console。
生产环境请用 :telemetry.attach_many/4 接实际可观测性栈。
@spec detach_logger(keyword()) :: :ok | {:error, :not_found}
Detach 开发期 Logger handler。
@spec emit_evolution( :fix | :derived | :captured, CMDCSkillEngine.Types.SkillRecord.t(), map() ) :: :ok
Evolver 成功产出新 SkillRecord 时调用。
evolution_type—:fix | :derived | :capturedrecord— 新创建的SkillRecordextra— 任意补充字段（如source_task_id）
@spec emit_record_updated( :save | :counters_incremented, CMDCSkillEngine.Types.SkillRecord.t() ) :: :ok
Store 完成一次记录写入时调用。
operation—:save（save_record 路径） /:counters_incremented（update_counters 路径）
低阶 emit，自动注入 schema_version。一般不直接调用，用各类 helper。
@spec schema_version() :: pos_integer()
返回 telemetry schema 版本号。
@spec span_analyze(map(), (-> result)) :: result when result: var
包装一次 analyze 过程，自动 emit analyze :start / analyze :stop，
并把 :duration_ms 计入 measurements。
示例
Telemetry.span_analyze(meta, fn ->
build_session_analysis(state, ctx)
end)