用途:审计已接入 OpenTelemetry 的项目,对照 Maple 实际消费的约定找出差距,生成按服务分组的问题报告,再按严重程度修复。它是 maple-onboard 的对应技能:后者从零安装遥测,本技能假设埋点已存在,检查其是否正确。
主要能力:审计前需阅读本技能目录下的 checks.md,它是完整检查注册表,包含检查 id、严重级别以及每个缺口会破坏 Maple 的哪项功能。每条报告的问题都必须引用其中的检查 id,不得编造 checks.md 或上游 OTel semconv 之外的属性键或约定。修复配方来自配套技能:maple-onboarding-style 提供通用 OTel 风格、VCS 属性、日志桥、指标、LLM 约定;maple-nextjs-style、maple-nodejs-style、maple-python-style、maple-effect-style、maple-go-style、maple-rust-style、maple-java-style、maple-csharp-style、maple-kotlin-style 提供各技术栈的引导形态。
严重级别:critical 表示直接破坏 Maple 功能或存在数据风险,如缺少 service.name、手工写入状态字符串、日志无 trace 关联、出站调用无法形成服务图边、属性中含 PII;warn 表示功能降级或工作不可见,如缺少 environment/VCS 资源属性、使用已弃用 semconv 键、双重发射、高基数标签或 span 名、出站调用留为 Internal、未追踪操作;info 表示信号质量改进,如异步边界 trace 上下文传播、span 噪声、缺少指标、命名风格、LLM 调用缺少 gen_ai.*。
使用方式:第一步枚举仓库中所有应用/服务并分类为 instrumented、partial 或 not instrumented,先向用户展示分类结果以便纠正。第二步对已埋点服务做静态代码审计,覆盖引导与资源(RES-)、状态与类型(STAT-)、trace 覆盖(SPAN-)、服务图归属(MAP-)、属性键(REN-、NAME-)、日志(LOG-)、指标(MET-)、PII(PII-01)、LLM(LLM-*)等类别,逐条记录服务、检查 id、严重级别、证据(file:line)及受影响的 Maple 功能。第三步仅在 Maple MCP 已连接时做实时交叉核对,可用工具包括 audit_setup、get_instrumentation_recommendations、list_services、explore_attributes、service_map、get_service_top_operations 等;未连接则一行说明并跳过,静态审计可独立成立。第四步先展示报告再编辑,报告含服务、严重级别、检查、问题、证据、影响及汇总与建议修复顺序。第五步按严重级别修复,纯键重命名可在 SDK 重命名或接受 Maple 设置中的摄取映射,双重发射与命名问题只能在 SDK 修复,编辑需幂等并保留项目包管理器、日志器与格式,不得移除已有可观测性厂商,不得在属性中放 PII,不得提交、推送或开 PR。第六步对改动服务重新验证启动与 OTLP POST 返回 2xx,并总结变更。
限制:不得在报告展示前编辑;每条问题必须引用 checks.md 中的检查 id;静态审计必须可独立运行,Maple MCP 只是增强;不得修改项目根目录之外的文件;不得提交或推送;修复配方来自 maple-*-style 技能而非记忆。若用户只要审查,第四步后即可停止。