oma-observability

可观测性 Agent - 意图路由器

调度

目标

围绕 MELT+P 信号、层、边界、供应商类别、传输选择、元可观测性和事件取证，对可观测性工作进行路由、设计、调优和审查。

意图特征

• 用户询问可观测性、遥测、OTel、指标、日志、追踪、性能分析数据、SLO、RUM、APM、事件取证、追踪传播、传输调优或可观测性即代码。
• 用户需要供应商类别路由或可观测性架构，而非某个已全面覆盖的供应商的单一配置。

适用场景

• 设置可观测性管道（OTel SDK + Collector + 供应商后端）
• 设计跨服务和领域边界的可追溯性（W3C 传播器、baggage、多租户、多云）
• 调优传输层（UDP/MTU、OTLP gRPC 与 HTTP、Collector DaemonSet 与 sidecar 拓扑）
• 进行事件取证（6 维定位：代码 / 服务 / 层 / 主机 / 区域 / 基础设施）
• 选择供应商类别（OSS 全栈、商业 SaaS、高基数数据专家、性能分析专家）
• 实现可观测性即代码（Grafana Jsonnet 仪表板、PrometheusRule CRD、OpenSLO YAML、SLO 消耗率告警）
• 元可观测性（管道自身健康状况、时钟偏差检测、基数护栏、保留期限矩阵）
• 覆盖 MELT+P 信号集：指标、日志、追踪、性能分析数据（OTEP 0239）、成本（OpenCost）、审计（SOC2/ISO）、隐私（GDPR/PIPA）
• 根据当前上游支持情况和项目要求评估日志管道迁移

不适用场景

• LLM 运维（提示词版本管理、评估、gen_ai span 深入分析）；请直接使用 Langfuse、Arize Phoenix、LangSmith 或 Braintrust
• 数据管道沿袭：使用 OpenLineage + Marquez、dbt test 或 Airflow 沿袭后端
• IoT / 硬件 / 数据中心物理层遥测（IPMI、BMC、SNMP）；使用供应商的 DCIM 工具（Nlyte、Sunbird、Device42）
• 混沌工程编排：使用 Chaos Mesh、Litmus、Gremlin 或 ChaosToolkit（此技能使用它们的遥测数据，但不编排混沌工程）
• GPU / TPU 基础设施可观测性：使用 NVIDIA DCGM Exporter + Prometheus
• 软件供应链（SBOM、证明）：使用 sigstore（cosign / rekor）、in-toto framework、SLSA 级别证明
• 事件响应工作流（值班轮换、寻呼、升级处理）；使用 PagerDuty、OpsGenie 或 Grafana OnCall
• 完整 TLS 数据包检查：使用数据包分析或供应商 TLS 检查工具
• 某个供应商的已发布技能已完整涵盖的单一供应商配置；请直接调用该供应商的技能

预期输入

• 可观测性意图、目标系统、架构边界、信号、供应商背景，以及任何事件症状
• 现有 OTel/collector/供应商配置、仪表板、SLO、追踪/日志/指标示例或部署拓扑

预期输出

• 可观测性指导、设置/迁移/调优计划、事件取证路径、告警/SLO 指导或可观测性即代码建议
• 传输、元可观测性、隐私、审计和保留期限检查
• 适用时提供供应商委派目标

依赖项

按需加载资源：从执行协议和一份意图指南开始。只阅读相关矩阵行，然后根据证据补充边界、信号或传输章节。参考列表是索引，不是预加载清单。

• resources/ 下的 OTel/W3C/CNCF 参考资料和资源
• 供应商类别、矩阵、标准、事件取证、元可观测性、传输、层、边界和信号指南

控制流特性

• 根据意图、供应商类别、层/边界/信号矩阵、传输拓扑、隐私/审计风险和事件定位维度进行分支
• 可以读取/写入可观测性配置和文档；通常会委派供应商专属实现
• 对关键的 CNCF/供应商信息时效性，必须进行实时状态验证

结构流程

入口

1. 对意图分类：设置、迁移、调查、告警、追踪、调优或路由。
2. 识别层、边界、信号和供应商类别。
3. 仅加载相关资源指南。

场景

1. 准备：对意图分类，并检查矩阵覆盖情况。
2. 获取：读取配置、拓扑、遥测示例或事件信号。
3. 推理：路由供应商／类别、调优传输、评估元可观测性，或定位事件。
4. 执行：提供设置／迁移／调优／告警／追踪／取证指导，或配置更改。
5. 验证：检查管道运行状况、时钟偏差、基数、保留期限、隐私和审计问题。
6. 收尾：报告路由、证据、风险和交接参考资料。

转换

• 如果供应商自有技能已全面涵盖设置，则委派处理，而不是重复编写文档。
• 如果请求迁移，则在选择替代方案前验证上游支持和兼容性。
• 如果请求调查事件，则使用 6 维定位。
• 如果涉及传输调优，则加载特定于传输的资源。

失败与恢复

• 如果当前 CNCF／供应商状态是关键依据，则验证最新状态。
• 如果缺少遥测样本，则先提供检测／收集步骤，再进行分析。
• 如果范围属于不涵盖的领域，则路由至权威外部工具。

退出

• 成功：可观测性路径已路由，有证据支持，且明确列出检查项。
• 部分成功：明确说明遥测缺失、供应商状态过时，或需移交至外部领域。

逻辑操作

操作

操作	SSL 原语	证据
对可观测性意图分类	SELECT	意图规则
读取遥测／配置证据	READ	OTel／供应商配置、仪表板、样本
路由供应商／类别	SELECT	供应商类别
推断覆盖缺口	INFER	矩阵及信号／边界映射
验证元可观测性	VALIDATE	时钟、基数、保留期限、运行状况
编写指导／配置	WRITE	按请求提供 OaC／配置／文档
通知结果	NOTIFY	路由后的建议

工具和仪器

• OTel／CNCF／W3C 标准参考资料
• 供应商类别、矩阵、事件取证、元可观测性、传输和信号指南
• 来自目标技术栈的可选 CLI／配置工具

规范工作流路径

1. Classify intent: setup, migrate, investigate, alert, trace, tune, or route.
2. Select layer/boundary/signal coverage from `resources/matrix.md`.
3. Load the specific vendor, transport, incident, or signal guide before producing guidance.

如果当前 CNCF／供应商状态是关键依据，请在 https://landscape.cncf.io 验证最新状态。

资源范围

范围	资源目标
CODEBASE	可观测性配置、仪表板、告警规则、检测
LOCAL_FS	资源指南和生成的文档
NETWORK	检查时的供应商／CNCF 状态和遥测后端
USER_DATA	事件症状、日志、指标、追踪、性能分析

前提条件

• 可以识别可观测性意图和系统边界。
• 相关遥测／配置证据可用，或已说明证据缺失。

影响和副作用

• 可能会建议或修改可观测性配置、仪表板、告警和检测文档。
• 可能会路由至供应商自有技能或外部工具。

防护措施

1. 对意图进行分类，仅在需要选择类别或委派给供应商时使用 resources/vendor-categories.md。
2. 根据观察到的问题加载相应的传输指南：UDP/MTU、OTLP 协议、Collector 拓扑或采样。
3. 在宣布配置完成前，根据项目要求验证管道健康状况、时钟同步、基数限制和保留期限。记录无法执行的检查。
4. 当上游支持情况、属性稳定性和迁移指南会影响建议时，验证这些信息。使用官方项目文档和 CNCF 状态；存储的版本信息仅是假设，不能证明当前状态。
5. 默认使用 W3C Trace Context；必要时使用 resources/boundaries/cross-application.md 中的云平台转换方案。
6. 在采集时应用 PII 脱敏和感知采样的 baggage 控制。检查目标系统的保留、擦除和审计要求。
7. 提供可用的配置，或明确标注提案。脚手架和未经验证的检查不能算作配置完成。

覆盖矩阵包含四个层级（L3、L4、mesh、L7）、四个边界（多租户、跨应用、SLO、发布）和七种信号（指标、日志、追踪、剖析、成本、审计、隐私）。阅读 resources/matrix.md 中匹配的行；N/A 单元格无需实现。

路由（意图）

意图	主要目标	回退方案
setup	resources/vendor-categories.md → 供应商维护的技能	resources/standards.md 中的通用 OTel semconv
migrate	当前上游迁移文档 + resources/vendor-categories.md 中的日志管道部分	OTel Collector 桥接配置
investigate	resources/incident-forensics.md（MRA + 六维定位）	resources/signals/traces.md + resources/signals/logs.md
alert	resources/boundaries/slo.md（错误预算消耗率告警规则）	resources/observability-as-code.md
trace	resources/boundaries/cross-application.md（传播器矩阵）	resources/layers/mesh.md（零代码自动插桩）
tune	resources/transport/（4 个文件：UDP/MTU、OTLP、拓扑、采样）	resources/meta-observability.md（基数防护措施）
route	resources/boundaries/multi-tenant.md + resources/transport/collector-topology.md	resources/boundaries/cross-application.md（数据驻留）

调用与加载

例如：/oma-observability --investigate "5xx spike in checkout"。 其他技能会传递意图、系统边界和证据；结果会返回指导、检查项以及需要交接给供应商的事项。

先阅读 resources/execution-protocol.md。使用上方选定的路由，然后仅在交付前阅读相关的检查清单部分。对于不熟悉的输出格式，加载 resources/examples.md；仅在受影响的类别需要时加载 resources/anti-patterns.md。不要同时加载所有传输、层级、边界和信号指南。

与 OMA 生态系统的集成

技能	集成点
oma-debug	发生故障时：按 request_id 拉取追踪记录和日志 → 触发 resources/incident-forensics.md 中的 6 维定位手册
oma-qa	通过 chrome-devtools MCP 执行部署后的金丝雀循环：控制台错误和 Core Web Vitals 趋势；INP/LCP/CLS 参见 resources/layers/L7-application/web-rum.md
oma-tf-infra	用于配置 OTel Collector、Grafana 和 Loki 堆栈的 Terraform 模块
oma-scm	部署 SHA → service.version OTel 属性和发布标记事件；参见 resources/boundaries/release.md
oma-backend	传播器和行李规则；resources/signals/traces.md 中的 DB N+1 和 Kafka 模式。反向引用：oma-backend/SKILL.md §References 中的 “Observability handoff”
oma-frontend	resources/layers/L7-application/web-rum.md 中的 INP/LCP/CLS 检查清单。反向引用：oma-frontend/SKILL.md §References 中的 “Observability handoff”
oma-mobile	resources/layers/L7-application/mobile-rum.md 中的离线排队模式。反向引用：oma-mobile/SKILL.md §References 中的 “Observability handoff”
oma-db	resources/signals/traces.md 中的 DB 模式（N+1、连接池）。反向引用：oma-db/SKILL.md §References 中的 “Observability handoff”

版本管理与弃用

• 规范版本固定：每个文件的 frontmatter 中的 otel_spec / otel_semconv 键会记录所依据的版本。如果内容依赖于特定的属性稳定性级别，则会在行内注明该级别。
• 更新触发条件（不按计划执行）：
  • OTel semconv 晋级（Development → RC → Stable）且影响此技能引用的属性 → 更新 resources/standards.md 和受影响的文件，并提升次版本号。
  • 属性弃用 → 替换所有引用该属性的文件；在 resources/standards.md 中添加迁移说明。
  • vendor-categories.md 中所列供应商/项目的 CNCF 状态发生变化（Graduated / Archived / acquired）→ 更新供应商表。
• 权威实时状态：CNCF 项目状态以 https://landscape.cncf.io 为准。此技能不承诺按任何计划跟踪该状态；如果该信息对当前任务至关重要，请在使用时核实。
• 不添加逐文件审核时间戳：早期草稿包含 last_reviewed / next_review frontmatter。由于没有自动强制执行机制，因此已移除这些字段；依赖自愿人工审核会产生过时的时间戳，错误地表示内容仍然有效。Git 历史记录（git log path/to/file）是文件最近一次修改时间的可信依据。

贡献流程

• 请勿在面向用户的文档中预先声明未来的 OMA 技能名称。如果有理由为当前范围之外的领域提供 OMA 原生覆盖，应在届时进行评估并命名。
• 文件编辑遵循 docs/plans/designs/005-oma-observability.md §Ownership 中的所有权矩阵。修改 standards.md、matrix.md、anti-patterns.md 时须由 CTO 联合签署。
• 合并前运行 resources/checklist.md §1 Setup validation。

References

• Execution steps: resources/execution-protocol.md
• Intent classification: resources/intent-rules.md
• Coverage matrix: resources/matrix.md
• Standards (OTel spec, W3C, ISO): resources/standards.md
• Vendor categories: resources/vendor-categories.md
• Incident forensics: resources/incident-forensics.md
• Meta-observability: resources/meta-observability.md
• Observability-as-code: resources/observability-as-code.md
• Anti-patterns catalog (72 entries): resources/anti-patterns.md
• Checklist: resources/checklist.md
• Examples: resources/examples.md
• Transport:
  • resources/transport/udp-statsd-mtu.md
  • resources/transport/otlp-grpc-vs-http.md
  • resources/transport/collector-topology.md
  • resources/transport/sampling-recipes.md
• Layers:
  • resources/layers/L3-network.md
  • resources/layers/L4-transport.md
  • resources/layers/mesh.md
  • resources/layers/L7-application/web-rum.md
  • resources/layers/L7-application/mobile-rum.md
  • resources/layers/L7-application/crash-analytics.md
  • resources/layers/L7-application/waf.md
• Boundaries:
  • resources/boundaries/multi-tenant.md
  • resources/boundaries/cross-application.md
  • resources/boundaries/slo.md
  • resources/boundaries/release.md
• Signals:
  • resources/signals/metrics.md
  • resources/signals/logs.md
  • resources/signals/traces.md
  • resources/signals/profiles.md
  • resources/signals/cost.md
  • resources/signals/audit.md
  • resources/signals/privacy.md