signoz-setting-up-observability

数据摄取后的可观测性设置

将服务从“遥测数据正在流入 SigNoz”推进到“我已有仪表板、告警、已保存的视图和调优闭环”。此技能是一个编排层，而非独立参考资料：具体操作由相邻的 SigNoz 技能完成，MCP 工具和资源则提供当前的负载架构。此技能负责安排执行顺序，并提供没有任何单一技能负责的判断依据（范围、SLO、阈值、需要跳过的内容）；它不会重复说明负载架构或字段规则，因此在编写任何负载前，请先阅读相关的 signoz://… 资源。

当追踪、日志或指标已开始写入 SigNoz，且你希望采用一种注重 SLO 的、带有明确建议的配置方案时，请使用此技能；如果你还在接入 SDK，则不要使用。适用对象有两类：无需人工介入即可运行的自治 AI SRE Agent（例如 SigNoz 产品内的助手），以及使用 Claude Code / Codex / Cursor 提示词的工程师。两类对象遵循相同的流程；若某个步骤需要人工决策（第 1 阶段的分流、第 5 阶段的签核），由宿主决定如何呈现；自治宿主则根据上游上下文补足缺失信息，而不是停下来等待。

前置条件

此技能会调用 SigNoz MCP 服务工具（signoz_list_services、 signoz_list_dashboards、signoz_get_field_keys、 signoz_execute_builder_query、signoz_create_dashboard、 signoz_create_alert、signoz_create_view 等），并委派给相邻技能。运行工作流前，请确认 signoz_* 工具可用。如果不可用，说明 SigNoz MCP 服务尚未安装或配置；请先运行 signoz-mcp-setup。不要改用原始 HTTP 调用，也不要伪造负载。

何时使用

当用户需要完整的数据摄取后配置时，请使用此技能：SLI/SLO → 探索 → 仪表板 → 视图 → 告警 → 调优；可按任意组合交付，并将其作为一个工作流按序执行。

如果用户只需要单个产物，请勿使用此技能；直接移交给相应技能：

• 只需要仪表板 → signoz-creating-dashboards。
• 只需要一个静态告警／阈值告警或通知规则 → signoz-creating-alerts。（但 SLO／燃烧率／错误预算告警，即使不需要仪表板，也仍属于此技能：它需要先完成 SLI/SLO 信息收集，并在以下阶段判断燃烧率。）
• 只需要一个已保存的 Explorer 视图 → signoz-managing-views。
• 一次性探索查询 → signoz-generating-queries。
• 概念／文档查询（SRE 方法、OTel 约定、燃烧率计算）→ signoz-searching-docs / signoz_search_docs。

以下各阶段都会指出负责具体操作的技能；此技能负责流程顺序和决策。

阶段 1：确定排查范围（不要跳过）

在使用任何工具之前，先获取以下答案。每个答案都能为后续阶段扫清障碍。

1. 此服务做什么？它会调用外部服务吗？ 用一两句话说明。这有助于确定 SLI（“正常运行”的含义），并标记值得监控的下游依赖：如果它调用数据库、缓存、队列或第三方 API，就计划监控到每个依赖项的客户端 Span 延迟和错误率，因为服务本身健康但依赖项故障，用户仍会受到影响。
2. 需要交付哪些内容？ 仪表板 / 告警 / 已保存的视图，可任意组合。
3. 是否也要监控基础设施？（可选；需询问） 如果服务运行在你负责的基础设施上（k8s Pod、VM、容器），且遥测数据使用相同的资源属性，你可以添加 USE/基础设施面板（CPU、内存、重启次数、网络），无需额外插桩；参见阶段 3。如果平台团队已经负责主机 / 集群仪表板，则跳过。
4. 会发出哪些信号？ 链路追踪 / 日志 / 指标。这决定你要调用哪些 signoz_get_field_keys。
5. 规范资源筛选条件是什么？ 通常是 service.name。查询前确认准确值；不要猜测。
6. 对该服务的用户来说，怎样才算成功？（为阶段 2 做准备。）即使只用一句话说明（“请求在 1s 内完成且没有 5xx”）也足够；这将成为 SLI。
7. 由谁负责？有运行手册吗？ 负责团队、服务层级，以及生产 / 预发布范围；这些会成为阶段 8 中的告警标签和注释。如果有真实的运行手册 URL，请记录；绝不要编造。

明确提供“先探索数据”这一选项。

阶段 1.5：盘点现有内容

每个创建类子技能在调用时都会进行自己的严格重复项检查（signoz-creating-dashboards 会列出仪表板；signoz-creating-alerts 会对告警规则分页）；此处不要重复实现。编排的价值在于预先统一检查一次，这样你就可以根据现有内容安排顺序，避免在构建过程中发生冲突：

• 服务是否正在上报？使用的准确名称是什么？ （signoz_list_services。）此名称是后续每个阶段都会复用的资源筛选条件；应优先确定。
• 是否已经存在与该服务相关的仪表板 / 告警 / 已保存的视图？ 如果有，就计划对其进行扩展（转至 signoz-modifying-dashboards、signoz-managing-views 或 signoz_update_alert），而不是另行创建一套。signoz-explaining-dashboards / signoz-explaining-alerts 可概述你将接手的现有内容。
• 是否有可复用的通知渠道？（将在阶段 5 中使用。）

逐页检查每个清单，直到找到匹配项或确认所有页面均已检查完毕。如果视图的 source 未知，请分别搜索链路追踪、日志、指标和 meter。

只需了解足够的信息，以判断每项内容应扩展还是创建；详尽的清单检查留给子技能完成。

阶段 2：在设计任何内容之前确定 SLI/SLO

这是一个前置必需项。没有它，告警就会变成“指标超过了阈值”，而不是“面向用户的错误预算消耗速度已经快到值得关注”。

收集以下内容：

• SLI 公式：正常事件数 / 有效事件数。例如，成功的结账请求数 / 结账请求总数（排除健康检查、合成探测、扫描器流量以及非用户长轮询端点）。
• SLO 目标：例如，在滚动 30 天的窗口内达到 99.5%。
• 排除项：哪些内容不计为有效事件（合成探测、扫描器流量、流式端点）。
• 错误预算额度：1 - SLO，根据目标推导得出。要计算剩余预算，还需要 SLO 窗口内观测到的错误事件数 / 有效事件数。

记录以上内容，供后续阶段使用；它们会直接用于阶段 8。（关于 SLO / 消耗率的背景信息：signoz-searching-docs。）

阶段 3：探索实际已有的数据（RED + USE 覆盖率）

signoz-generating-queries 负责实际探索：先发现再查询的规则、所有发现调用 （signoz_list_metrics、signoz_get_field_keys、 signoz_get_field_values、 signoz_get_service_top_operations）、工具选择，以及无数据的区分。让它盘点数据；不要在此重述其查询机制。（如需回顾，signoz-searching-docs 介绍了 RED/USE 方法和 SigNoz 字段语义。）

编排工作是将发现的内容映射到 RED（请求速率、错误、耗时）和 USE（利用率、饱和度、错误），找出缺口，并作出 generating-queries 不会作出的判断：

覆盖检查清单（服务使用 RED，基础设施/资源使用 USE）：

• Rate（速率）：每项操作的请求/调用速率
• Errors（错误）：每项操作的错误数或错误率
• Duration（耗时）：基于 spans 或直方图的 p50/p95/p99 延迟
• Utilization（利用率）：CPU、内存、磁盘、队列深度、池占用率（仅限你负责的基础设施）
• Saturation（饱和度）：请求队列、GC 暂停、连接池等待
• 资源层的 Errors（错误）：磁盘故障、驱逐、OOM 终止

缺少信号（例如没有错误数）就是检测埋点缺口；在基于现有信号构建之前，应先标出这一点。

Span 指标用于告警，不只是面板。 当 generating-queries 提供 SigNoz 的 trace→metrics 输出（signoz_calls_total、 signoz_latency_*、DB/外部调用 span 指标）时，优先将其用作 仪表盘和错误预算消耗速率告警的 RED 数据源：这些指标已预聚合，成本低；而在较长告警时间窗口内聚合原始 trace，成本高且不适合作为稳定的告警数据源。（通过发现确认确切的指标/标签名称；不要硬编码。）

绘制任何计数器时，都应根据刚测得的量级选择展示方式，而不是想当然。 这并非只针对吞吐量：它适用于所有要绘制的计数器（请求速率、错误数、重启次数、OOM 终止、驱逐），而低量错误和资源层事件最容易受到影响，并非只有请求才如此。每秒速率适合稳定的高流量信号；如果第 3 阶段显示计数较低、突发性强或由人工操作驱动，/sec 图表就会显示难以辨认的小数（0.03/s）。应根据实际表现而非固定阈值判断：如果每秒值显示为小数，就将此意图传递给第 6 阶段：在较长时间窗口（24h–7d）内，绘制每个时间区间的 increase 计数，而不是速率。（CPU、内存、队列深度等仪表值已经是绝对值；这是计数器需要考虑的问题。）这是有意为之的权衡（increase 会随着所选范围调整 y 轴刻度），因此要审慎决定，不能一概默认采用或不采用。 signoz-creating-dashboards 负责速率与 increase 机制的选择。

验证基础设施→服务的关联（USE 部分）。 不要假设 service.name 存在于主机/容器/k8s 指标中：这些指标通常只有 host.name / k8s.pod.name / k8s.node.name，而 k8s.deployment.name 可能与 service.name 不同。让 generating-queries 确认实际将基础设施指标关联到此工作负载的身份属性，然后使用这个已确认的属性限定 USE 面板范围。如果没有可用的关联属性，就向用户询问工作负载选择器，而不要猜测。

从 trace 中发现下游拓扑，而不是依赖人工记忆 （第 1 阶段 Q1）。值得特别注意的一点：在 SigNoz v5 schema 中，客户端 span 的 kind_string = 'Client'（不是 kind，也不是 SPAN_KIND_CLIENT），因此要先验证字段和值，再使用 signoz_get_field_keys 发现已填充的依赖属性。当前示例包括 http_url、server.address、db.system 和 db.operation；只使用该租户实际返回的字段。

多租户说明：如果服务面向多个租户/区域，应查找稳定且不含个人身份信息的租户/区域属性（例如 tenant.id、 region、deployment.environment）；避免使用原始 URL 或用户标识符。仪表盘应提供按租户细分的视图； 仅显示聚合结果会掩盖单个租户的故障。 SLI 卫生：确认 SLI 统计的事件携带了正确的标签。对于宽泛的分母（“对服务的所有请求”），扫描器对 /.env*、/.git* 发起的流量是真实存在的，但应予以排除，因为它不是用户流量。排除谓词应当只排除扫描器，其他情况保持中立，因此应使用单独的否定条件： <url_or_route_field> NOT REGEXP '/\\.(env|git|aws|ssh|well-known)' 而不是 EXISTS AND …。SigNoz 的否定运算符也会匹配字段不存在的行，因此没有字段的有效事件（非 HTTP span、内部操作）仍会计入；应由 SLI 自身的范围过滤器（service.name、http.route）定义事件范围，而不是由扫描器谓词定义。（只有在意图相反时，才将 EXISTS 与否定条件配对，即排除具有该字段的行中的某个特定值，例如 service.name EXISTS AND service.name != 'redis'。）范围定义良好的 SLI 已经排除了扫描器路径，因此这主要会影响服务级别的比例指标。如果需要监控扫描器，请单独保留安全视图。

第 4 阶段：按基数和成本对标签分类

将标签接入查询之前，先对每个标签分类。错误的分类是导致指标账单激增和仪表盘难以阅读的首要原因。

类别	基数	用途
路由	<20	告警标签、抑制规则、通知策略（例如 severity、team）
变量	<100，且便于人类阅读	仪表盘变量（例如 environment、tenant）
拆分维度	通常 <500	图表／表格中的 groupBy（例如 gen_ai.tool.name）
仅用于 Trace／日志	无上限	仅用于 Trace 或日志，绝不用于指标序列

切勿将原始 URL、查询字符串、用户 ID、会话 ID 或请求 ID 用作指标标签；它们会导致基数激增，推高账单。这些信息应放在 Trace／日志中。

基数对成本的影响大于对显示性能的影响；SigNoz／ClickHouse 可以轻松处理数百个变量值；真正的限制是下拉菜单是否便于人类阅读。

阶段 5：确认通知渠道、消耗率窗口和恢复阈值

创建告警前先敲定以下事项：

1. 通知路由。 确定每个严重级别对应的通知渠道（例如，严重 → PagerDuty，警告 → Slack）。如果 signoz_list_notification_channels 中有合适的现有渠道，就重复使用；切勿虚构渠道名称。实际的渠道解析／创建和密钥处理由 signoz-creating-alerts（阶段 8）负责；此处只敲定严重级别→渠道的映射。

2. 消耗率窗口。 对于 30 天预算、目标为 99.9% 的 SLO，常见的起始设置如下：

   严重级别	消耗率	长窗口	短窗口	路由
   立即呼叫的严重告警	14.4×	1h	5m	PagerDuty
   慢速消耗警告	6×	6h	30m	Slack
   工单级低优先级告警	1×	3d	6h	工单队列

   消耗率倍数与 SLO 无关，因此对于不同的目标，应直接计算每个绝对阈值： error-rate = burn rate × (1 − SLO)（例如，99.9% 时 14.4× → 1.44%）。 signoz-searching-docs 会说明消耗率方法；它无法计算你的数值。

   只有两个窗口同时触发，告警才会触发：长窗口用于抑制短暂峰值；短窗口则能快速恢复，让已解决的事件迅速停止触发呼叫。（规范 SRE 表中的 6× 这一行对应的是呼叫，因此在此将其路由到 Slack，是有意降低严重级别；请根据你的值班规范调整。）

3. 恢复阈值（滞后）。确定每个数值型告警都在低于触发目标时恢复（例如，达到 80% 时触发，降至 70% 时恢复），以防止在边界值附近反复触发。signoz-creating-alerts 会将此设置写入 recoveryTarget 字段。

通过宿主应用的问题／UI 机制，将这些事项作为澄清内容提出，并附上具体的建议值（使用结构化澄清工具、内联标签或交互式提示；遵循宿主应用的规则）。 切勿开放式地询问“你想要什么阈值？”；应提出建议，并让用户进行调整。 在开始构建前，明确获得用户对范围和阈值的认可。标出会影响阈值的基线（“当前错误率为 5.1%，因此静态的 5% 告警会产生过多噪声，所以建议改用消耗率告警。”）。

阶段 6：构建仪表板

交由 signoz-creating-dashboards 处理；它负责模板、布局／变量／OTel 命名默认值、v6 架构及其注意事项、无数据探测，以及每个面板必做的试运行（后续编辑交由 signoz-modifying-dashboards）。此处不要重述面板 JSON 或网格机制；传达意图，让该技能负责构建。

优先创建多个聚焦的仪表板，而不是一个大型仪表板。 由于 signoz-creating-dashboards 每次调用只构建一个仪表板，而且其模板目录已按技术分类整理，因此编排时要决定组合哪些仪表板。默认按类别／受众拆分，并针对每个仪表板调用一次子技能：

• 服务／RED（APM）： KPI 磁贴 + 请求速率、错误、p50/p95/p99。这是主要的值班仪表板。
• 基础设施／USE： 仅当已选择启用基础设施监控（阶段 1 Q3）时，才展示 CPU、内存、重启次数、网络；并按阶段 3 中已确认的属性限定范围。通常会将现成模板（hostmetrics、k8s）单独导入为一个仪表板。
• 下游依赖项： 仅当服务存在外部依赖项（阶段 1 Q1）时，才按阶段 3 中发现的依赖项属性分组，展示每个依赖项的客户端 Span p99 + 错误率。
• 业务／SLO： SLI 比率和错误预算；如果是多租户（阶段 3），还需按租户细分。仅展示聚合数据的面板会掩盖单租户故障。

拆分后，每个仪表板都能保持快速、用途单一，并由合适的受众负责（SRE、应用开发人员或平台团队）。只有在拆分会导致多个内容过少的仪表板时，才合并为一个仪表板：对于小型服务，与其创建四个各含 2 个面板的仪表板，不如将少量面板作为行放在一个仪表板上，阅读体验更好。每个仪表板仍须通过阶段 1.5 的扩展与新建检查，因此应复用现有仪表板，而不是另建一个平行仪表板。

质量标准（每个新建的仪表板都须满足）： 配置应达到生产环境标准，便于凌晨 3 点响应事件；每个面板都要有“关注事项”描述和下钻入口，每个仪表板顶部都要有“从这里开始”说明。将此作为意图传达，以便 signoz-creating-dashboards 据此处理。

阶段 7：已保存的 Explorer 视图

创建机制交由 signoz-managing-views 处理（它负责视图负载和 extraData／selectColumns 结构）。编排的价值在于决定要创建哪些视图；它们比面板成本更低，也是事件处理中最快捷的入口：

• 服务的 ERROR/FATAL 日志。
• API 请求列表：基于服务端 Span 的 Traces 列表视图（kind_string = 'Server'，按阶段 3 验证）；按请求展示服务／操作（或 http.route）／http.response.status_code／时长／trace_id 的表格。这是查看“我的各个端点现在在做什么”的最快入口，可按延迟或状态排序，一键打开完整 Trace；也是一个广泛视图，下面的失败 Span／慢 Span 视图都只是它经过筛选后的子集。
• 规范操作的失败 Span（has_error = true）。
• 慢 Span（duration_nano > <threshold>）。
• 失败的子流程（例如，出现错误的 OAuth 请求）。
• 关联下钻：带有 trace_id 的错误日志（日志激增时可直接跳转到 Trace），以及可链接回日志的慢速／错误 Trace。

还有两项需要跨阶段传达的约束：每个视图都必须带有与仪表板相同的环境／租户筛选条件（这样 prod 和 staging 数据就不会混在一起）；所选列必须通过与阶段 4 相同的 PII／无标识符检查。

Phase 8：告警

signoz-creating-alerts 负责所有单个告警的机制：渠道解析（通过 displayName 路由、可选择启用的测试通知、密钥处理）、严重性默认值、op/matchType、单位、注释、evalWindow/recoveryTarget、异常规则结构，以及强制执行的试运行。每个告警调用一次，不要在这里重复这些内容。（signoz-explaining-alerts 用于读取规则；规则触发后，signoz-investigating-alerts 会进行根因分析。）

此编排层在该技能基础上补充的内容：

• 与 SLI 绑定的告警应使用燃烧率告警对，而不是静态阈值。 对比率使用静态阈值会导致告警反复触发；对于任何与 Phase 2 SLO 相关的内容，默认使用燃烧率告警对。
• 燃烧率配置方法（signoz-creating-alerts 无法在缺少 SLO 的情况下推导的内容）。向它提供输入，而非规则结构：坏事件/总事件的定义（优先使用 Phase 3 的 signoz_calls_total 错误/总数拆分，而不是对原始追踪数据进行聚合）、Phase 5 中的长、短时间窗口长度，以及触发目标 burnRate × (1 − SLO)。这些输入还需附带两项判断。长、短窗口必须作为同时 AND 两者的同一条规则进行评估（两条独立规则会在每次短时峰值时都触发通知；如果当前 SigNoz 版本无法在单条规则中表达短窗口确认，则仅发布长窗口规则，并明确说明），如果采集的数据中不存在清晰的坏事件/总事件拆分，则目前无法构建燃烧率告警；此时应改用根据基线调整的阈值，而不是生成无法正常工作的规则。让 signoz-creating-alerts 和 signoz://alert/* 选择与版本对应的规则结构。请注意，creating-alerts 的“过去 1h 内本会触发 N 次”校准无法评估 6h/3d 的燃烧率窗口，因此不要据此认为“触发 0 次”代表已调优；Phase 9 中一周后重新调优的流程才是真正的校准。
• 燃烧率仅适用于比率 SLI，因此还要为非比率故障模式安排告警。 服务停止发送数据或流量骤降时，不会消耗错误预算（流量为零时 SLI 比率未定义），因此燃烧率告警对不会触发任何通知。完整的配置还应在主要信号上添加遥测数据存在性/数据缺失告警，并将流量/吞吐量作为独立信号处理。将这些意图交给 signoz-creating-alerts；规则结构（数据缺失、异常、阈值）和健康状态下的零值处理由它负责；编排层只需决定将这些告警纳入整个方案。
• 批量创建并安排顺序。 在任何规则引用渠道之前，先解析/确认渠道（Phase 5 映射），然后按路由级别分组，批量创建告警，而不是每个指标创建一条规则。
• 人工 TODO 边界。 抑制规则、组织级通知策略（usePolicy: true 仅表示选择启用此策略）和维护窗口需在 SigNoz UI/Terraform 中配置；这些工具不会创建它们。将其标记为 TODO；绝不要报告为已完成。

Phase 9：交接

将以下内容交还给人工：

• 仪表板 ID、视图 ID 和告警 ID。只有当某个 MCP 工具返回了确切的 webUrl 值时才提供该值；否则返回 ID。绝不要根据 ID 或租户主机名构造前端 URL。
• 尚未解决的问题；将它们作为明确的 TODO 移交。
• 可能需要调优的基线（例如：“工具错误率今天为 5.1%；针对 99% SLO 调优的燃烧率告警偶尔会触发，因此应在积累一周数据后重新调优”）。

应避免的事项

• 臆造频道名称或 webhook URL。 应改为询问用户。
• 为受 SLI 约束的告警设置静态阈值。 现代默认做法是使用消耗速率组合；比例的静态阈值会导致告警反复触发。
• 仪表板尺寸不当。 12 个面板就够时，不要硬塞 18 个；一个看起来更清晰时，也不要拆成四个各有 2 个面板的仪表板：先按类别拆分，再为每类调整合适的尺寸。
• 为节省时间而跳过试运行。 在创建时遇到 500 错误，比在试运行时遇到更难排查。
• 每个指标都创建一个告警。 按路由层级分组，而不是按指标分组。
• 在指标序列中使用高基数标签。 这会增加指标费用。应将它们移到追踪或日志中。
• 合成前端 URL。 如果 MCP 提供了 webUrl，就返回它；否则只返回资源 ID。
• 将扫描器流量计入 SLI 分母。 扫描器流量确实存在，但不属于用户流量；应将其排除。
• 把探索阶段的发现当作可有可无的信息。 基线、基数和错误计数决定了阈值和调优基线，因此不要丢弃。应将这些信息保存在任何主机上都能留存的地方：把数值写入工件（面板／仪表板描述、告警注释）以及 Phase 9 交接文档中；这些内容都存放在 SigNoz 中。不要依赖本地笔记文件。
• 让 AI 编写的检测代码未经审查就上线。 在据此设计仪表板之前，先抽查实际发出的内容。