用途:为 HVE Core 各智能体提供共享的可观测性词汇,规定遥测数据有哪些、如何命名,而不规定使用哪个 SDK 或后端。产出规划类工件(ADR、PRD、安全/RAI 计划、代码评审报告)的智能体与产出面向用户应用代码的智能体都引用它,使下游 traces、metrics、logs 使用一致的 OpenTelemetry 对齐语言。
适用场景:产出 span、metric 或结构化日志的应用代码;涉及可观测性、监控或审计日志的架构决策记录;标记遥测缺口、span 命名不一致或指标基数失控的代码评审;引用审计日志、可追溯性或证据链的安全/负责任 AI 计划;以服务遥测表达成功指标的产品需求文档。
核心原则:声明式而非规定式,只定义名称与形状;对齐 OpenTelemetry 数据模型;优先采用已有 OTel 语义约定(HTTP、RPC、数据库、消息、GenAI、FaaS);PII 默认拒绝,以 references/pii-denylist.md 为准;厂商无关,默认 OTLP 为传输协议。
主要能力:Trace 方面定义 span 类型(server、client、producer、consumer、internal)、必需资源属性(service.name、service.version、deployment.environment)及 <verb>.<resource> 命名模式。Metric 方面定义 counter、up-down-counter、histogram、gauge 及异步变体,单位遵循 UCUM,命名模式为 <domain>.<entity>.<measure>,并强调基数控制。Log 方面定义 TRACE 至 FATAL 严重级别与推荐结构化字段,要求在活动 span 内注入 trace_id 和 span_id。PII 处理提供哈希、丢弃、令牌化三种脱敏模式,用户标识统一用 user.id 存放不透明哈希。另含采样与成本(头采样、尾采样及默认策略)、资源属性要求与埋点决策树。
限制:不指定 SDK、导出器或后端;具体 PII 清单与新增词汇提案需查阅内部 references 文件;资料未提供安装命令、收费或平台信息。