telemetry

遥测运维

使用此技能运维遥测栈——Prometheus、OpenTelemetry Collector 和 Loki，作为其打包部署的单一单元：采集与抓取、摄取、保留，以及将原始信号转化为告警的规则。此技能是针对一组指定工具的工具技能。可观测性策略——SLI、SLO、错误预算以及要进行哪些埋点——属于 platform-engineering；仪表板、面板，以及 Grafana 侧的告警规则、联系人和通知策略属于 grafana。此技能负责采集／摄取／保留层，以及上述两个技能都会使用的 Prometheus 规则文件。

运维约定

1. 任何变更前先进行只读排查。 首先检查抓取配置、规则文件、采集器管道和保留设置。随附的 telemetry-check 脚本会运行规则合理性检查和抓取目标可达性检查，且不会更改任何内容。
2. 操作前确认目标、范围和回滚路径。 无需确认即可进行只读排查。变更——重新加载配置、推送 promtool 规则、重启采集器、更改保留策略——都需要明确的人类指令，且指令中须注明实例。
3. 配置能够解析，不代表配置有效。 规则合理性检查可以发现结构问题，但无法证明表达式有意义或目标可抓取。应在交付边界进行验证（抓取成功、规则已评估、告警已触发），再宣称运行正常。
4. 限制证据范围。 概述配置差异和查询结果；切勿在聊天中完整输出 prometheus.yml、采集器管道或凭据。
5. 负责保留决策。 保留策略是针对每个组件谨慎制定的容量与合规决策——Prometheus 块保留、OTel 导出器缓冲、按租户设置 Loki 保留期限——应按计划定期审查，而非沿用默认值。

telemetry-check 脚本

scripts/telemetry-check 是一款面向 Agent 的只读检查工具。它使用随附的标准库 YAML 读取器解析 Prometheus 规则文件，并运行无需依赖的结构合理性检查；从抓取配置中提取静态目标并探测 TCP 可达性；最后输出有范围限制的 JSON。它绝不会写入文件，也不会向任何地方发送数据。

scripts/telemetry-check --help                      # no server needed
scripts/telemetry-check --rules rules.yml --json    # rule sanity, machine-readable
scripts/telemetry-check --scrape prometheus.yml --json   # probe static targets
scripts/telemetry-check --targets targets.txt --timeout 5

退出码：0 表示所有检查均已通过，1 表示发现问题或发生致命错误，2 表示用法错误。telemetry-check --rules 仅检查结构：每条规则必须且只能包含 record／alert 中的一个，表达式非空且定界符匹配，持续时间有效，记录规则名称和标签名称有效，且标签值只能是字符串。请另行使用 promtool check rules 进行完整的 PromQL 解析。

运维流程

1. 识别部署：明确哪些组件在范围内（Prometheus、OTel Collector、Loki）、部署方式（二进制、容器、运算符）、配置文件位置，以及负责人。
2. 收集证据：对配置运行 telemetry-check --rules 和 --scrape，然后在有访问权限时检查实时状态端点（/-/healthy、/api/v1/targets、采集器健康状态、Loki 就绪状态）。
3. 调查查询问题时，加载 references/05-query-workflows.md。定义信号、选择器、UTC 时间范围、步长／限制和预期单位；分别验证语法与语义；先执行只读即时查询，再执行范围受限的范围／日志查询；并记录状态、范围、时间、限制、警告和基数证据。
4. 根据症状进行分类：将报告的问题对应到证据（缺少时间序列 → 抓取或重新标记；告警未触发 → 规则或保留；日志缺失 → 摄取或标签基数）。将空结果视为未知，绝不能视为数值零，并区分陈旧、部分、已过期、缺少标签和查询错误等状态。
5. 经确认后执行操作：收到人类指令后执行范围明确、影响受限的变更，并事先说明回滚路径。
6. 验证：重新运行相关检查，并在交付边界确认可观测结果。

Prometheus：抓取、规则、重新标记、保留、HA

• 抓取配置（scrape_configs）：每个抓取组对应一个 job，并有明确的 scrape_interval、低于该间隔的 scrape_timeout，以及 metrics_path。已知端点优先使用 static_configs，动态端点则使用服务发现（*_sd_configs）。通过 /api/v1/status/config 验证正在运行的配置，并通过 /api/v1/targets?state=active 验证目标。
• 记录规则和告警规则：规则文件由多个 groups 组成，每组包含 record 或 alert 规则，并带有 PromQL expr、可选的 for/keep_firing_for 时长，以及 labels/annotations。每次更改后，都要使用 promtool check rules 完整解析 PromQL，并使用随附的 telemetry-check --rules 在无依赖的情况下检查结构是否合理，然后再重新加载。规则必须简洁、命名清晰且便于审查——100 行的表达式会增加调试负担，不是规则。
• 重新标记：relabel_configs 和 metric_relabel_configs 会在摄取前重写标签。使用它们来规范标签命名、删除高基数或内部标签，并附加抓取元数据。重新标记错误会悄无声息地改变序列标识——通过针对性的 curl 检查 /metrics，并查看 /api/v1/targets 中目标的 scrapeUrl 进行验证。
• 保留：--storage.tsdb.retention.time 和 --storage.tsdb.retention.size 限制本地块的保留量；默认情况下，块的时长为 2h。保留策略是容量决策（参见 references/04-stack-integration-and-retention.md），不能置之不理。监控 prometheus_tsdb_head_series 和 prometheus_tsdb_compaction，以了解基数和压缩压力。
• 高可用性（HA）：使用两个配置完全相同的 Prometheus 实例，并为 --query.max-concurrency 留出余量，同时确保外部标签一致，即可在查询层进行分片或去重（Thanos、Mimir 或 Grafana 数据源）。告警规则不得重复触发：HA 对需要去重层或一致的标签，而且各副本的规则评估必须保持一致。规则评估状态（for 计数器）在每个实例上都是本地的。

OpenTelemetry Collector：管道、采样、关联

• Collector 管道：每种信号类型（指标、日志、跟踪）的管道都是由 receivers → processors → exporters 组成的有向无环链。保持管道精简并按信号类型划分；混合信号的管道会变得难以调试。每个管道都必须至少有一个 exporter；未使用的 receiver/exporter 属于无效配置。
• 接收器、处理器、导出器：接收器接收数据（OTLP、Prometheus、filelog、hostmetrics）；处理器负责转换、批处理、过滤、采样和附加资源属性；导出器将数据发送到下游（OTLP、Prometheus 远程写入、Loki、日志记录）。顺序很重要——批处理和 memory_limiter 处理器应放在导出器之前；tail_sampling 只能用于跟踪管道。
• 采样：跟踪中的 tail_sampling 会在批次级别做出决策；probabilistic_sampler 无状态且成本更低。应审慎采样：错误和慢速路径保留完整跟踪，高流量的成功请求使用尾部采样，绝不要采样掉错误信号。采样必须与保留策略协调——被采样掉的跟踪将永久消失，因此应在管道设计阶段做出决定，而不是等到紧急情况发生时再处理。
• 跟踪/span 关联：在日志行和指标示例中携带 trace_id 和 span_id，以便 LogQL 和 PromQL 能够跳转回跟踪。Collector 的 spanmetrics 处理器会根据 span 推导 RED 指标；带有跟踪上下文的 OTLP 日志会进入 Loki，并将 trace_id 作为结构化标签以便关联。跟踪上下文传播属于应用层职责，由 backend-engineering 负责；此处介绍的是 Collector 侧。

Loki：摄取、LogQL、保留期限、标签

• 摄取：Loki 通过推送 API（/loki/api/v1/push）从 Promtail、OTel Collector 的 loki exporter 或 Grafana Agent/Alloy 摄取数据。通过 loki_distributor_bytes_received_total 和就绪端点验证摄取情况；静默丢弃数据的摄取问题（速率限制、too many outstanding requests）会掩盖故障。
• LogQL：{label="value"} |= "filter" | json 用于选择流并筛选日志行；标签匹配器是主要的成本驱动因素。LogQL 分析（sum by (...) (rate({app="x"} |~ "error"[5m]))）基于标签索引和日志行筛选运行——设计标签时，应确保你实际使用的匹配器成本较低。
• 保留期限：retention_period 和 retention_size 按租户生效；compactor 会强制执行这些设置并合并索引分片。若不加管理，日志量会无限增长——在推出前设置保留期限，通过 loki_compactor 指标跟踪，并将日志保留视为由指定负责人负责的合规决策。
• 标签：Loki 标签是反向索引——高基数标签（请求 ID、用户 ID、跟踪 ID）会使索引大小和流式处理成本激增。标签仅保留租户、应用、环境和作业；将高基数字段放入日志行，并使用 LogQL | json/| regexp 或 OTel 结构化元数据提取。基数指南：取值随每条日志行变化的标签不应放入索引。

整个技术栈的保留期限

保留期限是整个技术栈层面的决策：Prometheus 块（原始样本）、OTel Collector 缓冲（内存队列、exporter 重试）和 Loki（已索引日志）各自具有独立的保留期限，而总计存储占用才是团队需要承担的成本。根据每个组件的数据用途（用于告警的热指标、用于趋势分析的样本、用于调试和审计的日志）逐一决策，在配置中设置，并定期审查。有关权衡表和用于监控保留期限的告警规则，请参阅 references/04-stack-integration-and-retention.md。

参考文档索引

何时加载	参考文档
来源、版本观察结果、刷新流程	references/00-source-index.md
抓取配置、记录/告警规则、重新标记、保留期限、HA	references/01-prometheus-operations.md
Collector 管道、接收器/处理器/exporter、采样、关联	references/02-opentelemetry-collector.md
摄取、LogQL、保留期限、标签设计	references/03-loki-operations.md
PromQL/LogQL 构建、语义审查、成本控制和无数据诊断	references/05-query-workflows.md
跨组件保留期限决策和技术栈集成	references/04-stack-integration-and-retention.md

包含的制品

• scripts/telemetry-check：只读的规则健全性 + 抓取目标可达性检查器（仅使用标准库、--json、--rules/--scrape/--targets、无需服务端即可使用 --help）。
• tests/test_telemetry_check.py：针对固定配置的确定性测试，包括只读约定。
• fixtures/：测试使用的起始配置，包括 prometheus-rules.yml（有效规则）和 scrape-config.yml（有效抓取配置）。
• references/：五份带日期且按来源索引的参考文档，以及来源索引，其中包括成本受限的 PromQL/LogQL 工作流。
• evals/evals.json：用于 Agent 运行的六个输出质量评估案例。

验证边界

声明	最低证据
规则文件在结构上有效	telemetry-check --rules FILE --json 以状态码 0 退出，且没有错误
规则文件在语义上有效	promtool check rules FILE 以状态码 0 退出
目标可抓取	telemetry-check --scrape CONFIG --json 报告目标可访问，且 /api/v1/targets 显示 state="up"
管道正在运行	Collector 健康检查端点有响应，且各信号的指标（otelcol_receiver_*、otelcol_exporter_*）持续递增
数据接收正常	Distributor 指标持续递增，且就绪端点返回 200
保留策略已受控	已显式设置 retention_period/retention_size，且 compactor/TSDB 指标确认了该策略

硬性边界

• 未获得明确的人类指令（指明目标并说明回滚路径）时，绝不修改抓取配置、规则文件、Collector 管道或保留策略。只读发现可自由进行。
• 没有交付边界证据（抓取成功、规则已评估、告警已触发）时，绝不声称某条规则或某个目标有效。
• 绝不在聊天中暴露完整配置、凭据或原始日志；应改为总结证据。
• 绝不将 telemetry-check 用作其他用途；它是只读工具，不具备任何修改能力。
• 仪表板、Grafana 告警规则、联系点和通知策略属于 grafana 的职责；SLI/SLO 设计和可观测性策略属于 platform-engineering 的职责。此处不要重复相关内容。

不适用场景

• 可观测性策略和 SLO（需要采集哪些数据、SLI/SLO 设计、错误预算、寻呼策略）——这些属于 platform-engineering。
• Grafana 产品相关工作（仪表板、面板、数据源、Grafana 告警规则、联系点、通知策略、RBAC）——这些属于 grafana；它会查询 Prometheus 和 Loki，但负责 Grafana 侧的工作。
• 应用程序埋点代码（服务中的 OTel SDK、追踪上下文传播、应用程序代码中的自定义导出器）——这些属于应用程序开发；参见 backend-engineering。
• 反向代理和边缘可观测性（Traefik 指标/追踪/访问日志配置）——这些属于 traefik，其可观测性参考将此技术栈视为后端。
• 技术栈的基础设施部署（Helm charts、Kubernetes operators、该技术栈自身的 Docker Compose）——这些属于 kubernetes 和 docker-compose。
• 其他后端（Tempo、Mimir、Thanos、Datadog、InfluxDB）——这些仍由各自的负责人负责；此技能将 Prometheus、OTel Collector 和 Loki 作为一个整体进行介绍。