SigNoz MCP Server

在深入查看具体资源之前，获取 SigNoz 部署的当前状态和整体情况。data.sourceStats 是权威且完整的扁平数据集合，包含部署统计端点报告的所有键和值，包括当前字段和未来字段。类型化便捷投影涵盖遥测数据的新鲜度和数量、基础设施状况、仪表板、告警规则和运行时、通知渠道、已保存视图、日志管道、云集成、用户、身份验证、服务账号、角色、许可和配置。

• 参数：无任务参数；与每个工具一样，它接受非必需的 searchContext，用于 MCP 可观测性。
• 权威数据源：sourceStats 会保留从上游 data 对象成功解码的每个条目及其原始点分隔键。可使用分组字段便于解读；需要精确了解后端覆盖范围或查询新引入的字段时，则使用 sourceStats。计数是部署范围的汇总；如需精确清单，请使用 signoz_list_dashboards、signoz_list_alert_rules、signoz_list_notification_channels 或 signoz_list_views；查询指标名称请使用 signoz_list_metrics；查询当前告警实例请使用 signoz_list_alerts；查询时间范围内或按服务划分的数据，请使用 signoz_search_logs、signoz_search_traces 或 signoz_query_metrics。
• 缺失字段：sourceStats 中不存在的键表示上游采集器未报告该字段，不得将其解读为零。如果某个采集器失败，端点可能会返回部分数据，但 HTTP 状态码仍为 200。在类型化投影中，分组总数缺失时会产生 available: false；报告值为零时则会产生 available: true。预期字段缺失或无效时，会设置 metadata.projectionPartial，并在 incompleteGroups 中添加条目，其中包含受影响的输出路径、原因、后续操作，以及适用时的精确回退工具。无效的投影值仍会原样保留在 sourceStats 中，并列入 invalidProjectionFields。
• 云集成的完整性：cloudIntegrations.sourceAvailability 会报告当前 AWS/Azure 提供商计数是否均已报告。每个提供商都有各自的 dataAvailable；缺失的提供商计数绝不会被转换为零。如果两个提供商均未报告，源数据可用性为 unavailable，但不会设置整体 metadata.projectionPartial；这可能意味着云集成不受支持或受版本限制，也可能是两个提供商的查询均失败，因此不要将其解读为“未配置云集成”。如果仅报告一个提供商，源数据可用性为 partial，并会为缺失的提供商提供非递归恢复指引。connectedAccounts 表示未移除、具有账号 ID 且至少收到过一次 Agent 报告的账号，并不代表近期有签到记录，也不能证明集成服务已启用。
• 投影元数据：reportedStatCount 是 sourceStats 中权威条目的数量；projectedStatCount 统计也由类型化分组表示的条目；unprojectedStatCount 统计仅在 sourceStats 中可用的条目，包括未来字段。projectionPartial、incompleteGroups 和 invalidProjectionFields 仅描述类型化投影的缺失情况；它们不表示 sourceStats 中的数据已被删除，也不代表整个端点数据完整。

signoz_list_metrics

发现指标名称和目录元数据，例如类型、暂时性、单位和单调性。查询数值或趋势请使用 signoz_query_metrics。此列表有数量上限，但不支持偏移分页。

• 参数：
  • searchText（可选）- 按名称子字符串筛选指标（例如，'cpu'、'memory'）
  • limit（可选）- 返回的指标数量上限（默认值：50）
  • timeRange（可选）- 相对时间范围：30m、1h、6h、24h、7d（默认值：1h；同时提供 start 和 end 时会忽略）
  • start/end（可选）- Unix 毫秒时间戳。同时提供两者时，会覆盖 timeRange。
  • source（可选）- 数据源筛选条件。使用 "meter" 列出 Cost Meter 指标，即 SigNoz 计量的用量/计费指标（目前为遥测数据摄取量）；省略则使用默认指标存储
  • 完整性说明：响应会附加一条说明，报告 hasMore（根据 returnedRows == limit 推断），避免将被 limit 截断的列表误认为完整列表；可使用 searchText 缩小范围以获得更具体的结果

signoz_query_metrics

查询已知指标的数值、趋势、细分数据或公式。此工具会应用适合指标的默认值，并自动获取省略的元数据；已知 metricName 时可直接调用。只有在发现名称或查看目录元数据时，才使用 signoz_list_metrics。

• 参数：
  • metricName（必需）- 要查询的指标名称
  • metricType（可选）- gauge、sum、histogram、exponential_histogram（缺省时自动获取）
  • isMonotonic（可选）- 布尔值（或字符串 "true"/"false"）；缺省时自动获取。无效值会被拒绝，不会被静默视为 false
  • temporality（可选）- cumulative、delta、unspecified（缺省时自动获取）
  • timeAggregation（可选）- 时间聚合（根据类型自动设置默认值）
  • spaceAggregation（可选）- 跨维度聚合（根据类型自动设置默认值）
  • groupBy（可选）- 以逗号分隔的字段名称或数组。对于 k8s.*、container.*、host.*、cloud.*、deployment.*、process.*、service.*、telemetry.* 和 os.*，会推断为资源上下文；其他名称使用属性上下文
  • filter（可选）- 筛选表达式
  • timeRange（可选）- 相对时间范围 <number><unit>，其中单位为 m/h/d（例如，'30m'、'1h'、'6h'、'7d'；默认值：'1h'；同时提供 start 和 end 时会忽略）
  • start/end（可选）- Unix 毫秒时间戳。同时提供两者时，会覆盖 timeRange。
  • stepInterval（可选）- 步长，单位为秒（省略时自动计算）
  • requestType（可选）- 响应格式。枚举值：time_series（默认值）、scalar。不支持的值会被拒绝。
  • reduceTo（可选）- 用于标量：sum、count、avg、min、max、last、median
  • formula（可选）- 对命名查询执行的表达式（例如，"A / B * 100"）
  • formulaQueries（可选）- 公式所需的其他命名指标查询数组或 JSON 编码的数组字符串。每个对象支持 name、metricName、metricType、isMonotonic、temporality、timeAggregation、spaceAggregation、groupBy 和 filter；name 和 metricName 为必需项。
  • source（可选）- 数据源筛选条件。使用 "meter" 查询 Cost Meter 数据；省略则使用默认指标存储
  • 结果上限：独立生成的指标查询和公式结果使用 limit: 100，并按 __result desc 排序。由于组件数量上限会在公式计算前应用，因此每个供公式使用的查询都采用 limit: 10000，避免相互独立的前 100 条输入遗漏高比率分组。响应中的决策说明会报告这两种上限。若公式输入的基数可能超过 10000，请缩小筛选或分组范围。
  • 未找到键的错误：筛选条件引用了工作区指标元数据中不存在的键时会失败；错误文本会提供恢复指导，结构化错误内容中还会包含机器可读的 missingKeys 数组。

signoz_get_top_metrics

按摄取的样本量排名，返回排名前 100 的指标及预先计算的百分比。使用此工具可以识别哪些指标带来了最多的摄取量和成本。封装了 POST /api/v2/metrics/treemap。响应字段：metricName、percentage（占总样本量的比例）、totalValue（样本绝对数量）。

• 参数：
  • timeRange（可选）- 相对时间范围 <number><unit>，其中单位为 m/h/d（例如 '1h'、'24h'、'3d'、'7d'、'30d'；默认值：'7d'；如果同时提供 start 和 end，则忽略此参数）。从 7d 开始；如果查询超时，则依次使用 3d、24h 重试
  • start/end（可选）- Unix 毫秒时间戳。如果同时提供，则覆盖 timeRange
  • 完整性说明：按摄取样本量固定返回排名前 100 的结果；响应会附加一条说明标记列表是否已达到上限并被截断（hasMore）

signoz_check_metric_usage

给定一组指标名称，返回引用了每个指标的仪表板和告警。针对每个指标封装 /api/v3/metrics/dashboards?metricName=... 和 /api/v2/metrics/alerts?metricName=...。

• 参数：
  • metricNames（必填）- 要检查的指标名称字符串数组（每次调用最多 50 个）。示例：["system.disk.io", "k8s.node.condition"]。若列表更长，请拆分为每批 50 个并合并结果。
• 响应：针对每个指标，dashboards（引用该指标的仪表板名称列表）、alerts（引用该指标的告警名称列表）、error（非空表示查询失败；此时不要将该指标视为未使用）
• 限制：每次调用最多 50 个指标；整体超时为 30 秒（超时后返回部分结果）

signoz_check_metric_cardinality

返回单个指标的标签/属性键及其基数计数和样本值，并按基数从高到低排序。样本有助于区分 UUID 等无界值和状态代码等有界维度。此工具不会显示该指标是否正在使用；建议移除前请先调用 signoz_check_metric_usage。

• 参数：
  • metricName（必填）- 要检查的指标名称。示例：k8s.container.memory_limit
  • timeRange（可选）- 相对时间范围 <number><unit>，其中单位为 m/h/d（例如 '30m'、'1h'、'6h'、'24h'、'3d'、'7d'；默认值：'7d'；如果同时提供 start 和 end，则忽略此参数）
  • start/end（可选）- Unix 毫秒时间戳。如果同时提供，则覆盖 timeRange

signoz_list_alerts

列出 Alertmanager 中当前正在触发/已静默/已抑制的告警实例，而非规则定义。要查看已配置的规则，请使用 signoz_list_alert_rules；要查看某条完整规则定义，请使用带有 id 的 signoz_get_alert；要查看状态时间线，请使用 signoz_get_alert_history。

• 参数：
  • limit（可选）- 每页告警的最大数量（默认值：50）
  • offset（可选）- 分页时跳过的结果数量（默认值：0）
  • active / silenced / inhibited（可选）- 三态筛选条件。接受布尔值（或字符串 "true"/"false"）。省略时采用后端默认值（包含所有状态）。无效值会被拒绝，而非静默丢弃
  • filter（可选）- 以逗号分隔的告警标签比较条件，支持 =、!=、=~（正则表达式）或 !~（负向正则表达式），例如 alertname="HighCPU",severity="critical"
  • receiver（可选）- 用于按接收器名称筛选告警的正则表达式

signoz_list_alert_rules

列出来自 GET /api/v2/rules 的已配置告警规则摘要，包括未触发/状态为 OK 的规则和已禁用的规则。要查看某条完整定义，请使用 signoz_get_alert；要查看当前 Alertmanager 实例，请使用 signoz_list_alerts。

• 参数：
  • limit（可选）- 每页返回的规则最大数量（默认值：50，最大值：1000；超出时会限制为最大值）
  • offset（可选）- 分页时跳过的规则数量（默认值：0）

signoz_get_alert

获取一条告警规则的完整定义（GET /api/v2/rules/{id}）。使用 signoz_list_alert_rules 查找 ID。调用 signoz_update_alert 前，仅当当前操作尚未获得完整的现行定义时才调用此工具；如果已有仍然有效的结果，请重复使用并保留未更改的字段。

• 参数：id（必填）——告警规则 ID（支持 v2 的服务上为 UUIDv7）。
• 注意：响应结构取决于 SigNoz 服务版本。#10997 之后的服务会返回规范的 Rule 类型，其中包含 createdAt/updatedAt/createdBy/updatedBy；较早版本会返回 GettableRule，其中包含 createAt/updateAt/createBy/updateBy（不带「d」）。

signoz_list_dashboards

列出分页的租户仪表板摘要（名称、UUID、描述、标签、时间戳）。使用 signoz_get_dashboard 获取面板和查询定义；在确认某个仪表板不存在之前，请逐页将 offset 增加 limit，直到覆盖 total。

• 参数：
  • limit（默认值为 50）、offset（默认值为 0）——基于偏移量的分页
  • filter（可选）——针对仪表板元数据（名称、描述、标签、创建者、时间戳、锁定状态）的服务端过滤 DSL
  • sort（可选）——updated_at（默认值）、created_at 或 name
  • order（可选）——asc 或 desc（默认值）

只有 source: user 的仪表板才能更新、打补丁或删除。source 不是服务端列表过滤列；需要时，请在多页结果中本地过滤返回的行。

filter DSL 是由 AND/OR/NOT 和括号连接的 key operator value 布尔表达式，也可以包含独立的自由文本词语（例如 name CONTAINS 'overview' AND locked = true）。完整语法、可过滤键及其运算符、值格式和示例请参阅 signoz://dashboard/list-filter-guide；列表响应还会在 reservedKeywords 中回显权威的保留键集合。

signoz_get_dashboard

获取一个已知租户仪表板的完整布局、变量、面板和查询。使用 signoz_list_dashboards 查找 UUID。

• 参数：id（必填）——仪表板 UUID

signoz_create_dashboard

创建一个自定义多面板仪表板。适合使用精选模板时，请使用 signoz_import_dashboard；要保存一条 Explorer 查询，请使用 signoz_create_view。构建负载前，请阅读 signoz://dashboard/instructions、signoz://dashboard/widgets-instructions 和 signoz://dashboard/widgets-examples。

• 参数：
  • schemaVersion（必填）——必须为 "v6"
  • name（DNS-1123 标签），或使用 generateName: true 从 spec.display.name 推导名称
  • tags（必填）——键值标签数组（可以为空）
  • spec（必填）——Perses spec：display、variables（数组）、panels（以面板 ID 为键的映射）、layouts（数组）

静态 Markdown 面板使用 signoz/TextPanel，并设置 queries: []，同时提供 plugin.spec.mode: "markdown"、text、presentation 和 headerOptions。 请包含该面板的布局引用。包含查询的面板仍需一个查询；Text 面板不需要执行查询试运行。组件示例和补丁说明涵盖这两种面板。面积图使用 signoz/AreaChartPanel 和一个 time_series 查询；visualization.stack（none、normal 或 percent）用于堆叠分组序列，chartAppearance.fillMode 可设为 solid 或 gradient。仪表板输入使用规范的 id；已更改的仪表板工具不接受旧版 uuid 输入。

signoz_import_dashboard

从 SigNoz/dashboards 仓库（main 分支）中托管的精选模板创建仪表板。服务会获取模板 JSON，并通过一次调用创建仪表板。

如果不知道相对模板路径，请先调用 signoz_list_dashboard_templates。请传入其返回的 path，而不是 URL 或绝对路径。

• 参数：
  • path（必填）——SigNoz/dashboards 仓库中的模板路径，例如 hostmetrics/hostmetrics.json

signoz_list_dashboard_templates

搜索 SigNoz 内置的精选仪表板模板目录，并以 {"templates": [...], "total": N} 的形式返回匹配项，其中每个条目都包含 id、标题、路径、描述、类别和关键词。此工具不会列出租户中已创建的仪表板；如需列出，请使用 signoz_list_dashboards。

• 参数：
  • searchText（可选）– 与每个模板的 id、标题、路径、类别、描述和关键词进行不区分大小写的匹配；模板必须匹配所有单词，例如 postgres 或 kubernetes pod。最多 2048 个字符。不填写则返回完整目录。

signoz_update_dashboard

完全替换现有仪表板。使用 signoz_get_dashboard 获取仪表板，从响应中取出 data 对象，仅将请求的更改合并到该对象中，然后在顶层发送该对象的字段，并保留所有其他字段。{status, data} 响应封装不能作为输入。对于已保存的 Explorer 查询，请使用 signoz_update_view。

• 参数：
  • id（必填）– 仪表板 id（也接受旧版 uuid 键）
  • schemaVersion、name、tags、spec – 更新后的完整状态（请参阅该工具的 JSON Schema）

signoz_patch_dashboard

对仪表板应用 RFC 6902 JSON Patch：无需重新发送整个仪表板即可进行部分更新。对于有针对性的编辑（重命名、添加或编辑一个面板或查询、微调变量），优先使用此工具，而非 signoz_update_dashboard。请阅读 signoz://dashboard/patch-instructions，了解示例操作步骤和准确路径；特别是，添加面板需要两项操作（面板和网格项），否则面板不会显示。

• 参数：
  • id（必填）– 仪表板 id（也接受旧版 uuid 键）
  • patch（必填）– {op, path, value} 操作数组；路径是指向仪表板可提交结构的 JSON Pointer，例如 /spec/display/name、/spec/panels/<panelId>、/spec/layouts/0/spec/items/-、/tags/-

signoz_list_services

列出指定时间范围内有跟踪活动的分页 APM 服务。未列出表示该时间段内没有跟踪活动，并不表示相同的 service.name 从未出现在日志中；如需获取日志值，请使用 signoz_get_field_values 并设置 signal="logs"。

• 参数：
  • timeRange（可选）- 相对时间范围 <number><unit>，其中单位为 m/h/d（例如 '30m'、'1h'、'6h'、'7d'；默认最近 6 小时；如果同时提供 start 和 end，则忽略此参数）
  • start（可选）- 开始时间，单位为 unix 毫秒（默认 6 小时前）。
  • end（可选）- 结束时间，单位为 unix 毫秒（默认当前时间）
  • limit（可选）- 每页最多返回的服务数（默认：50，最大：1000；更高的值会被限制）
  • offset（可选）- 分页时跳过的结果数量（默认：0）

signoz_get_service_top_operations

获取一个有跟踪记录的服务的内置操作表，按 p99 延迟排序，并列出每项操作的 p50、p95、p99、调用次数和错误次数。对于自定义聚合、分组、时间序列、跨服务比较或任意跟踪筛选，请使用 signoz_aggregate_traces。

• 参数：
  • service（必填）- 精确的跟踪服务名称，通常来自 signoz_list_services
  • timeRange（可选）- 相对时间范围 <number><unit>，其中单位为 m/h/d（例如 '30m'、'1h'、'6h'、'7d'；默认最近 6 小时；如果同时提供 start 和 end，则忽略此参数）
  • start（可选）- 开始时间，单位为 unix 毫秒（默认 6 小时前）。
  • end（可选）- 结束时间，单位为 unix 毫秒（默认当前时间）
  • tags（可选）- 以字符串形式传递的 JSON 编码 TagQueryParam 数组，例如 [{"key":"http.method","tagType":"SpanAttribute","operator":"In","stringValues":["GET"]}]；不填写则不进行标签筛选

signoz_get_alert_history

获取某条已配置规则的触发或状态转换历史记录。默认查询最近 6 小时。使用 state 和 filter 缩小结果范围。获取下一页时，将 data.nextCursor 作为 cursor 传入，并重复使用原始筛选条件、时间范围和排序方式。

响应为 { "status": "success", "data": { "items": [...], "total": <n>, "nextCursor": "<opaque>" } }；最后一页会省略 nextCursor。

• 参数：
  • id（必填）— 来自 signoz_list_alert_rules 的告警规则 ID
  • timeRange（可选）— 相对时间范围，格式为 <number><unit>，其中单位为 m/h/d（例如 '30m'、'1h'、'6h'、'7d'；默认查询最近 6 小时；若同时提供 start 和 end，则忽略此参数）
  • start（可选）— Unix 毫秒时间戳的起始时间（默认为 6 小时前）。
  • end（可选）— Unix 毫秒时间戳的结束时间（默认为当前时间）
  • state（可选）— 按告警状态筛选：inactive、pending、recovering、firing、nodata 或 disabled（省略则包含所有状态转换）
  • filter（可选）— 对时间线标签使用的 SigNoz 查询构建器表达式。使用 AND、OR 和括号组合条件；字符串使用单引号。示例：severity = 'critical' AND (team = 'payments' OR service.name = 'checkout')。要查找键，先不带筛选条件调用并检查 data.items[].labels[].key.name。为保持兼容性，仍接受后端格式的 filterExpression 别名，但标准参数为 filter。
  • cursor（可选）— 不透明的续页游标。获取下一页时，重复使用原始时间范围、状态、筛选条件和排序方式。获取第一页时省略 cursor。
  • limit（可选）— 每页行数。默认值：20；最大值：10000（超过上限的值会被截断）。
  • order（可选）— 排序顺序。枚举值：asc、desc（默认值：'asc'）
  • 旧版 offset：不再支持；请改用返回的游标。
  • 完整性说明：响应会追加一条说明，根据 data.nextCursor 报告 hasMore，并给出下一页的游标名称。

signoz_list_views

列出已保存的 Explorer 视图，或查找 Logs、Traces、Metrics 或 Cost Meter 页面中的某个视图 UUID。一个视图保存一份可重复使用的 Explorer 查询规范；它不是多面板仪表板。分页前先应用名称筛选，并在 pagination.hasMore 为 true 时继续使用 pagination.nextOffset。

• 参数：
  • source（可选）— 要筛选的 Explorer，例如 traces、logs、metrics 或 meter（Cost Meter 是独立的 Explorer 页面）；SigNoz 会验证该值。省略则列出所有 Explorer 中的视图
  • name（可选）— 按视图名称进行部分匹配筛选（服务端执行）
  • limit（可选）— 每页大小（默认值：50，最大值：1000；超过上限的值会被截断）
  • offset（可选）— 要跳过的结果数量（默认值：0）

signoz_get_view

按 UUID 获取某个已保存 Explorer 视图的完整定义。调用 signoz_update_view 前先调用此工具；signoz_update_view 会完整替换该视图。

• 参数：id（必填）— 已保存视图的 UUID

signoz_search_docs

搜索 SigNoz 官方文档，并根据产品、设置、插桩、配置、API、部署或故障排除问题，返回按相关性排序的页面、URL 和摘要。针对一个主题发送 2 到 6 个关键词，并保留用户原样输入的产品和技术名称；将包含多个意图的问题拆分为单独的调用。如果排名靠前的结果不相关，请用更少或不同的词重试。不要用于查询实时租户数据；如需所选结果的完整内容或指定的文档 URL，请使用 signoz_fetch_doc。

• 参数：
  • searchText（必填）- 针对一个主题的 2 到 6 个关键词，例如“Kubernetes pod logs”。保留用户原样输入的产品和技术名称。
  • limit（可选）- 要返回的最大结果数，以字符串形式提供（默认值：10，最大值：25；也接受数值）。25 的上限是有意设置的：每个结果都会从进程内的文档索引中载入文档文本，因此更大的上限会增加此服务的常驻内存。
  • section_slug（可选）- 精确的顶级文档分区筛选条件，例如 setup、logs-management、apm-distributed-tracing、metrics、alerts、dashboards、signoz-apis、querying 或 collection-agents。缩小搜索范围时，可复用先前结果中的 section_slug；未知的 slug 会返回零个结果。
  • searchContext - 用户的原始问题

文档搜索遥测会通过 signoz_docs_searches_total 统计已执行的搜索，并记录 outcome=ok|error。只有成功的搜索才会有 result_count_bucket（0、1-4、 5-9 或 10+）。signoz_docs_search_top_score 仅会在成功且有结果的搜索中记录排名第一的命中结果的原始 Bleve 分数。 分数未经校准，并取决于查询词、权重和分析器设置；它们不是相关性概率或阈值。 搜索 span 会记录 mcp.docs.search_text（已执行的查询，截断至 256 个 Unicode 码位）、mcp.docs.section_slug 和 mcp.docs.result_count。成功且有结果的搜索 还会记录 mcp.docs.top_score。这些 span 属性会区分客户端的关键词查询与用户在 mcp.search_context 中的原始请求；查询文本不是指标属性。如果查询不符合 Bleve 查询字符串语法，搜索会丢弃该子句、继续进行文本匹配，并记录 mcp.docs.query_string_dropped=true。空查询或仅包含空格的查询仍会导致验证错误。

signoz_fetch_doc

获取一个已知的 SigNoz 官方文档页面的完整 Markdown 内容或指定标题。请先使用 signoz_search_docs 查找页面；可接受的输入为 https://signoz.io/docs/... URL 或 /docs/... 路径。

• 参数：
  • url（必填）- 文档页面的 URL 或路径
  • heading（可选）- 标题锚点 ID 或标题文本
  • searchContext - 用户的原始问题

signoz_create_view

保存一个可复用的 Explorer 查询规范。多面板仪表板请使用 signoz_create_dashboard。Cost Meter 视图使用 source="meter"、signal="metrics" 和 builder-spec source="meter"。

• 参数（v2 类型化结构）：
  • name（可选）- 视图名称（DNS-1123 标签）。除非 generateName 为 true，否则必填
  • generateName（可选）- 为 true 时，服务会根据 spec.displayName 生成 name，且 name 必须为空
  • source（必填）- 此视图所属的 Explorer，例如 traces、logs、metrics 或 meter；SigNoz 会验证该值
  • spec（必填）- 类型化视图内容：displayName、panelType、requestType、queries、selectedFields、display
  • schemaVersion（可选）- 始终为 v2；省略时使用默认值
• 必需：编写任何负载前，请阅读两个 MCP 资源 signoz://view/instructions 和 signoz://view/examples。

signoz_update_view

完全替换现有的已保存 Explorer 视图。使用 signoz_get_view 获取视图，修改其返回的 data 对象，保留所有未要求更改的字段，并将完整对象作为 view 传入。上游在更新时会保持 name 不变；显示标签位于 spec.displayName 中。

• 参数：
  • id（必需）- 要替换的视图的 UUID
  • view（必需）- 完整的 source/spec 对（必需）；移除 name 和服务器填充的字段
• 迁移：已弃用的扁平结构（source 和 spec 与 id 并列）会返回带代码的 VALIDATION_FAILED 错误，并指出 view 包装对象；请传入 {"id": "<uuid>", "view": {"source": ..., "spec": ...}}。
• 资源规则：更改 source 或 spec 时，请读取 signoz://view/instructions 和 signoz://view/examples。如果原样传递获取到的正文，则跳过。先调用 signoz_get_view；不完整的正文会清除未指定的字段。

signoz_delete_view

按 UUID 永久删除已确认的已保存 Explorer 视图。使用 signoz_list_views 查找 ID；删除仪表板请使用 signoz_delete_dashboard。

• 参数：id（必需）- 已保存视图的 UUID

signoz_aggregate_logs

返回日志聚合统计信息（计数、速率、平均值、百分位数或分组/前 N 项明细），而非单条记录。查询日志行并检查消息时，请使用 signoz_search_logs。

• 参数：
  • aggregation（必需）- 聚合函数：count、count_distinct、avg、sum、min、max、p50、p75、p90、p95、p99、rate
  • aggregateOn（可选）- 要聚合的字段（除 count 和 rate 外均必需）
  • groupBy（可选）- 用于分组的逗号分隔字段（例如：'service.name, severity_text'）
  • filter（可选）- 使用 SigNoz 搜索语法的筛选表达式。使用 AND、OR 和括号组合条件。未知键会导致硬错误；有歧义的键默认归入资源上下文。日志键因工作区而异；只有在日志管道设置了 service.name 时，该字段才会存在。参见 signoz://logs/query-builder-guide
  • service（可选）- 服务名称的快捷筛选器（添加 service.name = '<value>'；如果工作区的日志缺少该属性，则会报错 key service.name not found）
  • severity（可选）- 精确的 severity_text；DEBUG、INFO、WARN、ERROR 和 FATAL 是常见示例，并非完整枚举。使用 signoz_get_field_values(signal="logs", name="severity_text", fieldContext="log") 发现可用值
  • orderBy（可选）- 排序表达式和方向（例如：'count() desc'）
  • limit（可选）- 返回的最大分组数（默认值：100，最大值：10000；更高的值会被截断，以限制服务器内存使用）
  • timeRange（可选）- 相对时间范围 <number><unit>，其中单位为 m/h/d（例如：'30m'、'1h'、'6h'、'24h'、'7d'；默认值：'1h'；若同时提供 start 和 end，则忽略此参数）
  • start / end（可选）- 开始/结束时间，单位为 Unix 毫秒。如果两者均已提供，则优先于 timeRange。
  • requestType（可选）- scalar（默认值；整个时间范围内的一个聚合值）或 time_series（每个时间桶一个值）。不接受未知值。
  • stepInterval（可选）- time_series 模式下的时间桶大小，单位为秒。可接受数字或数字字符串（省略时由后端自动选择）
  • 时间序列排序说明：limit 会选择整个请求时间窗口内排名靠前的分组，而非分别按每个时间桶选择。如果短时序列可能因此被隐藏，请缩短时间窗口或调整 limit。
  • 未找到键的错误：筛选器引用了此工作区日志元数据中不存在的键时，错误文本会提供恢复指导，结构化错误内容中还会包含机器可读的 missingKeys 数组。

signoz_search_logs

返回符合文本、服务、严重性或字段筛选条件的单条分页日志记录。对于计数、趋势或分组细分，请使用 signoz_aggregate_logs。

仅使用 searchText、service、severity、时间或分页参数的调用无需读取指南。只有在使用不熟悉的工作区字段编写 filter 之前，才需要读取 signoz://logs/query-builder-guide。

• 参数：
  • filter（可选）- 使用 SigNoz 搜索语法的筛选表达式。使用 AND、OR 和括号组合条件（例如，"(severity_text = 'ERROR' OR body CONTAINS 'panic') AND service.name = 'payment-svc'"）。日志键因工作区而异；只有在日志流水线设置了 service.name 时，日志中才会包含该字段。请参阅 signoz://logs/query-builder-guide
  • service（可选）- 要筛选的服务名称（添加 service.name = '<value>'；如果工作区的日志中没有该属性，则会报错 key service.name not found）
  • severity（可选）- 精确的 severity_text；DEBUG、INFO、WARN、ERROR 和 FATAL 是常见示例，并非完整枚举值。使用 signoz_get_field_values(signal="logs", name="severity_text", fieldContext="log") 发现可用值
  • searchText（可选）- 要查找的字面文本；会自动转义，并与 filter 通过 AND 组合
  • searchScope（可选）- searchText 的匹配范围：body（默认值，body CONTAINS）、attribute 或 resource（键和值），或 all（不限定范围的 search()，在较宽的时间范围内速度较慢）
  • timeRange（可选）- 相对时间范围 <number><unit>，其中单位为 m/h/d（例如 '30m'、'1h'、'6h'、'24h'、'7d'；默认值：'1h'；如果同时提供 start 和 end，则忽略此参数）
  • start / end（可选）- 以 Unix 毫秒表示的开始/结束时间。如果同时提供两者，则会覆盖 timeRange。
  • limit（可选）- 返回的最大日志数（默认值：100，最大值：10000；超出上限的值会被截断；使用 offset 分页）
  • offset（可选）- 分页偏移量（默认值：0）
  • 排序：生成的原始日志查询使用 timestamp desc，然后使用 id desc，因此当多行具有相同时间戳时，偏移分页结果仍具有确定性。
  • 完整性说明：响应会附加一条说明，报告 hasMore（根据 returnedRows == limit 推断）以及要获取的 nextOffset，因此不会将被截断的页面误认为完整结果集
  • 键不存在错误：如果筛选条件引用了此工作区日志元数据中不存在的键，错误文本会提供恢复指导，结构化错误内容中还会包含机器可读的 missingKeys 数组

字段未知时，使用 filter: "search('timeout')"。 使用 search('checkout', body) 限定搜索范围，或通过 AND/OR/NOT 将该函数与字段 谓词组合。范围包括 body、attribute、resource 和 log。字段确定后，优先使用字段谓词。searchText 配合 searchScope 会为你构建这些谓词。表达式字面值中的反斜杠和撇号需要转义；显式筛选条件会直接传递，不会被改写。 相同的表达式也适用于日志聚合和已保存查询规范。

signoz_get_field_keys

发现可用于筛选或分组指标、追踪或日志的字段名称。此工具返回的是键，而非已观测到的值；选定键后，请使用 signoz_get_field_values。data.complete 为 false 表示 SigNoz 截断了键列表；请通过 searchText 或 fieldContext 缩小范围。

• 参数：
  • signal（必填）- 信号类型。枚举：metrics、traces、logs
  • searchText（可选）- 按名称子字符串筛选字段键
  • metricName（可选）- 按指标名称筛选（适用于 metrics 信号）
  • fieldContext（可选）- 限定字段上下文。枚举：resource、attribute、scope、log/span/metric（固有列）、body（JSON 日志正文）。请使用 attribute，不要使用旧版 Query Builder 上下文 tag，SigNoz 在此处会忽略它。
  • fieldDataType（可选）- 限定数据类型：string、bool、int64、float64、number。像 []string 这样的数组形式会按其元素类型处理。
  • source（可选）- 对于指标，使用 meter 获取 Cost Meter 字段；默认指标存储则省略

signoz_get_field_values

获取已知字段键的观测值。若键未知，请使用 signoz_get_field_keys；并确保 signal 和 fieldContext 与将使用该值的查询一致。data.complete 为 false 表示 SigNoz 截断了值列表；请通过 searchText 缩小范围。

• 参数：
  • signal（必填）- 信号类型。枚举：metrics、traces、logs
  • name（必填）- 要获取值的字段键名称（例如，service.name、http.method）
  • searchText（可选）- 按子字符串筛选值
  • metricName（可选）- 按指标名称筛选（适用于 metrics 信号）
  • fieldContext（可选）- 当同一键名存在于多个上下文时，限定查找的字段上下文（resource、attribute、scope、log/span/metric、body）。请使用 attribute，不要使用旧版 Query Builder 上下文 tag；对于 tag，SigNoz 不会返回任何值。
  • source（可选）- 对于指标，使用 meter 获取 Cost Meter 值；默认指标存储则省略

signoz_search_traces

返回与服务、操作、错误、耗时或字段筛选条件匹配的单条分页 span 行，并使用它们发现 trace ID。统计数据请使用 signoz_aggregate_traces；查询一个已知 trace 的详情请使用 signoz_get_trace_details。

• 参数：
  • filter（可选）- 使用 SigNoz 搜索语法的筛选表达式。使用 AND、OR 和括号组合条件（例如："service.name = 'payment-svc' AND (has_error = true OR attribute.http.response.status_code >= 500)"）。为保持向后兼容，仍接受旧版 query，但规范参数为 filter。请参阅 signoz://traces/query-builder-guide
  • service（可选）- 用于筛选的服务名称
  • operation（可选）- 用于筛选的操作/span 名称
  • error（可选）- 按错误状态筛选。值为布尔值（或字符串 "true"/"false"）。无效值会被拒绝，而不会被静默忽略
  • minDuration / maxDuration（可选）- span 耗时的最小值/最大值，单位为纳秒（例如，500000000 表示 500 毫秒）
  • timeRange（可选）- 相对时间范围，格式为 <number><unit>，其中 unit 为 m/h/d（例如，30m、1h、6h、24h、7d；默认值：1h；若同时提供 start 和 end，则忽略此参数）
  • start / end（可选）- 起始/结束时间，单位为 Unix 毫秒。若同时提供，则会覆盖 timeRange。
  • limit（可选）- 返回的 span 行数上限（默认值：100，最大值：10000；超过上限的值会被截断；使用 offset 分页）
  • offset（可选）- 要跳过的 span 行数（默认值：0）
  • selectFields（可选）- 每行需返回的额外字段，添加到默认字段中。接受字段名数组或逗号分隔的字符串，最多 50 个。字段名可以是 span 列（db_name）、资源属性（k8s.pod.name）或 span 属性（http.route）；resource.、attribute. 或 span. 前缀用于指定上下文。使用 signoz_get_field_keys（signal="traces"）发现字段名称
  • 默认字段：每行包含 timestamp、trace_id、span_id、parent_span_id、name、service.name、kind_string、duration_nano、has_error、status_code_string、status_message、response_status_code 和 http_method，以及任何 selectFields。所有字段都是扁平行键；某字段未出现在某行中，表示该字段未被选中
  • 排序：生成的原始 trace 查询使用 timestamp desc。
  • 完整性说明：响应会附加一条说明，报告 hasMore（根据 returnedRows == limit 推断）以及下一次抓取所用的 nextOffset，因此不会将截断的页面误认为完整结果集
  • 输出说明：原始结果行键采用规范的 Query Builder 字段名称（例如 trace_id、span_id、duration_nano、has_error）。旧版调用方提供的筛选条件（如 hasError）仍会传递给后端别名层，但新的响应解析器应读取规范的 snake_case 键。
  • 键未找到错误：若筛选条件引用的键不存在于此工作区的 traces 元数据中，将返回错误；错误文本中包含恢复指导，结构化错误内容中还包含机器可读的 missingKeys 数组

signoz_aggregate_traces

返回跨度的自定义聚合统计信息（计数、比率、延迟百分位数、分组／前 N 项明细或时间序列），而不是单独的行或完整的跟踪层级结构。若要查看某个跟踪服务按 p99 排名的内置操作表，请使用 signoz_get_service_top_operations。调用此工具前，请先阅读 signoz://traces/query-builder-guide。

• 参数：
  • aggregation（必填）- 聚合函数：count、count_distinct、avg、sum、min、max、p50、p75、p90、p95、p99、rate
  • aggregateOn（可选）- 要聚合的字段（例如，'duration_nano'）。除 count 和 rate 外，其他聚合均必填
  • groupBy（可选）- 用逗号分隔的分组字段（例如，'service.name, name'）
  • filter（可选）- 使用 SigNoz 搜索语法的筛选表达式。使用 AND、OR 和括号组合条件。未知键会导致硬错误；有歧义的键默认采用资源上下文。请参阅 signoz://traces/query-builder-guide
  • service（可选）- 服务名称的快捷筛选条件
  • operation（可选）- 跨度／操作名称的快捷筛选条件
  • error（可选）- 错误跨度的快捷筛选条件。接受布尔值（或字符串 "true"／"false"）。无效值会被拒绝，不会静默丢弃
  • orderBy（可选）- 排序表达式和方向（例如，'avg(duration_nano) desc'）
  • limit（可选）- 返回的最大分组数（默认值：100，最大值：10000；超出时会截断，以限制服务端内存占用）
  • timeRange（可选）- 相对时间范围 <number><unit>，其中单位为 m／h／d（例如，'30m'、'1h'、'6h'、'24h'、'7d'；默认值：'1h'；同时提供 start 和 end 时会忽略此参数）
  • start／end（可选）- 开始／结束时间，单位为 Unix 毫秒。同时提供两者时，它们会覆盖 timeRange。
  • requestType（可选）- scalar（默认值；整个范围内的一个聚合值）或 time_series（每个时间桶一个值）。不接受未知值。
  • stepInterval（可选）- time_series 模式下的时间桶大小，单位为秒。接受数字或数字字符串（省略时由后端自动选择）
  • 时间序列排名说明：limit 会选取整个请求时间窗口内的前 N 个分组，而不是独立选取每个时间桶的前 N 个分组。如果短暂出现的序列可能因此被隐藏，请缩小时间窗口或调整 limit。
  • 未找到键时的错误：如果筛选条件引用的键不存在于此工作区的跟踪元数据中，错误文本会提供恢复指导，结构化错误内容中还会包含机器可读的 missingKeys 数组

signoz_get_trace_details

对于已知的跟踪 ID，返回其跨度、元数据和层级结构。如果 ID 未知，请先使用 signoz_search_traces，并选择包含该跟踪的时间窗口；默认的最近 6 小时范围可能无法涵盖较早的跟踪。

• 参数：
  • traceId（必填）- 已知的跟踪 ID，通常通过 signoz_search_traces 查得
  • timeRange（可选）- 相对时间范围 <number><unit>，其中单位为 m／h／d（例如，'30m'、'1h'、'6h'、'7d'；默认为最近 6 小时；同时提供 start 和 end 时会忽略此参数）
  • start（可选）- 开始时间，单位为 Unix 毫秒（默认为 6 小时前）。
  • end（可选）- 结束时间，单位为 Unix 毫秒（默认为现在）
  • includeSpans（可选）- 是否包含详细的跨度信息。接受布尔值（或字符串 "true"／"false"），默认值：true

signoz_create_alert

通过 POST /api/v2/rules 在 SigNoz 中创建新的告警规则。

• 参数：符合 SigNoz 告警规则架构的 JSON 负载。
• 架构因 ruleType 而异：
  • threshold_rule / promql_rule → v2alpha1（结构化的 condition.thresholds、evaluation、notificationSettings）。
  • anomaly_rule → v1，仅限指标：顶层 evalWindow / frequency、条件中的异常字段，以及直接位于顶层的 preferredChannels。省略 thresholds、evaluation、notificationSettings 和 schemaVersion；不支持策略路由。
• 通知路由：对于直接路由，仅当结果来自同一仍有效的已准备操作时，才复用完整分页的 signoz_list_notification_channels 结果；否则调用该工具，并且仅在状态可能已更改时刷新。v2 的每个层级都需要一个与返回的 displayName 完全匹配的名称：SigNoz 会拒绝没有渠道的层级，也会拒绝名称不存在的渠道，并且顶层 preferredChannels 不参与 v2 路由。v1 异常规则使用直接位于顶层的 preferredChannels。如果没有合适的渠道，询问用户，或提供 signoz_create_notification_channel，并使用用户提供的配置；绝不要自动创建。已确认的 v2 策略路由可以省略层级渠道。
• 提示：仅当告警资源已在同一已准备操作中读取时才复用；否则读取 signoz://alert/instructions 和 signoz://alert/examples。必要时，为 PromQL 读取 signoz://promql/instructions。

signoz_update_alert

通过 PUT /api/v2/rules/{id} 更新现有告警规则。这会完整替换规则：仅当结果来自同一仍有效的已准备操作时，才复用 signoz_get_alert、signoz://alert/instructions、signoz://alert/examples 和完整分页的 signoz_list_notification_channels 结果；否则读取或调用它们，并且仅在状态可能已更改时刷新，然后保留未更改的字段。直接 v2 路由的每个层级都需要一个与已列出的 displayName 完全匹配的名称；已确认的 v2 策略路由可以省略这些名称。v1 异常规则使用直接位于顶层的 preferredChannels，且不能使用策略路由。

• 参数：
  • id（必填）——要更新规则的 UUIDv7（从 signoz_list_alert_rules / signoz_get_alert 获取）。
  • 以及告警规则架构中的所有字段（结构与 signoz_create_alert 相同）。

signoz_delete_alert

通过 DELETE /api/v2/rules/{id} 删除告警规则。此操作不可撤销：使用 signoz_list_alert_rules 查找 ID，并先确认确切的规则。如果这两个步骤都已完成，则直接调用删除工具，无需重复进行删除前的列表查询或获取操作。

• 参数：
  • id（必填）——要删除规则的 UUIDv7。服务器会对非 UUIDv7 值返回 invalid_input。

signoz_delete_dashboard

按 ID 永久删除已确认的租户仪表盘。删除操作不可撤销；使用 signoz_list_dashboards 查找 UUID。对于已保存的 Explorer 视图，请使用 signoz_delete_view。

• 参数：id（必填）——要删除的仪表盘 UUID

signoz_list_notification_channels

列出分页的 v2 渠道摘要（id、name、displayName、kind、时间戳）。 告警路由使用 displayName；name 是不可变的机器标识符。 结果不包含提供商设置和凭据。使用 signoz_get_notification_channel 获取完整配置，并遍历所有页面后再确认某个渠道不存在。

• 参数：query 搜索显示名称；kind 按提供商类型筛选； sort 为 updated_at、created_at 或 name；order 为 asc 或 desc。 limit 默认为 20，上限为 200；offset 默认为 0。
• 默认值：按更新时间从新到旧排序。响应包含筛选后的总数 和明确的分页元数据。当 pagination.hasMore 为 true 时，继续使用 pagination.nextOffset；pagination.limit 表示实际生效的上限。

signoz_create_notification_channel

根据 config: {kind, spec} 创建通知渠道。创建渠道前先检查现有的 显示名称。

• 参数：必需提供 config。提供符合 DNS1123 规范的 name，或使用 generateName: true 和 displayName。如果未提供 displayName，SigNoz 会将 显式提供的 name 设为默认值。创建后，这两个名称都不可更改。 警报路由引用的是 displayName，而不是 name。
• 提供方类型：signoz://notification-channel/examples 列出了固定 SigNoz 版本接受的所有类型、每种类型的 config.spec 字段，以及对应的示例载荷；该列表 由 SigNoz OpenAPI 规范通过 make gen 生成。SigNoz 会验证类型，拒绝时会列出 可接受的类型。对于未知或缺失的 config.spec 字段，SigNoz 也会拒绝并提供 准确的要求；对于重复名称，会返回 already-exists。
• 解析通知：省略 config.spec.sendResolved 时，会使用提供方的默认值。 Get 会返回其生效值；更新时请保留该值。
• 测试发送：test 默认为 false。仅在确实需要发送测试通知时才设置 test: true。测试失败不会撤销已创建的渠道；重试前请检查返回的状态。 写入后发生的授权错误会包含 mutationCommitted: true 和已知 ID，以便调用方进行 身份验证并检查现有渠道，而无需再次创建。

不发送测试通知的示例：

{
  "name": "checkout-oncall",
  "displayName": "Checkout on-call",
  "config": {
    "kind": "webhook",
    "spec": {"url": "https://alerts.example.com/signoz", "sendResolved": true}
  },
  "test": false
}

signoz_update_notification_channel

使用 id 和完整的规范 config: {kind, spec} 对象，完整替换一个渠道的 config。先获取渠道，复制其 config，仅修改请求的字段，然后提交完整对象。 名称不可更改。保留所有未修改的设置和凭据，但不要回显机密。获取的 config 可直接写回；要取消设置可选字段，请将其省略，因为对于标题和消息等由模板支持的 字段，SigNoz 会拒绝空字符串。 test 默认为 false；显式设置为 true 会在更新后发送测试通知。 测试失败不会撤销更新。不要自动重放结果不确定的写入，也不要自动执行选择加入的测试。

signoz_get_notification_channel

获取一个渠道的规范 id、机器可读的 name、displayName、时间戳 和完整 config。config.spec 可能包含明文凭据；更新时可以使用，但不要显示或 记录机密。参数：id。

signoz_delete_notification_channel

通过 id 永久删除已确认的渠道。先解析并确认确切的渠道；如果这些步骤已完成， 则直接调用。若路由策略引用了该渠道，后端可能会拒绝删除。请传递该依赖错误， 并在重试前解除相关引用。

signoz_execute_builder_query

运行专用工具无法表达的 SigNoz Query Builder v5 请求，包括多查询请求、公式、PromQL 和 ClickHouse SQL。查询行数据时，优先使用 signoz_search_logs / signoz_search_traces；查询分组结果时，优先使用 signoz_aggregate_logs / signoz_aggregate_traces；查询常规指标时，优先使用 signoz_query_metrics。

• 参数：query（必填）——完整的 query_range 请求。输入架构会使用 SigNoz OpenAPI 规范中的描述说明顶层字段（start、end、requestType、compositeQuery、variables、formatOptions、noCache）；compositeQuery.queries 中的查询封装对象则为开放对象，相关说明见指南和 signoz://query-builder/examples。
• 查询类型：每个封装对象的 compositeQuery.queries[i].type 用于选择规范形状：
  • builder_query：特定信号的规范（日志/追踪/指标），包含过滤器、聚合、分组等。
  • builder_formula：引用其他查询名称的公式表达式（例如 A / B * 100）。
  • promql：{name, query, disabled, step?, legend?}。OTel 指标的 PromQL 必须使用 Prometheus 3.x UTF-8 带引号选择器格式 {"metric.name.with.dots"}；详情请阅读 signoz://promql/instructions 资源。
  • clickhouse_sql：{name, query, disabled, legend?}。
• Builder 结果边界：为确保编写的查询结果可预测，请在每个 builder_query 和 builder_formula 中明确提供正数 spec.limit 和非空的 v5 spec.order（不是仪表板/编辑器的 orderBy）。如果省略、设为 null 或设为零，独立查询和公式结果的默认限制为 100；被公式引用的 builder 查询默认限制为 10000，因为基础查询的限制会在公式计算前应用。原始日志按 timestamp desc, id desc 排序；原始追踪按 timestamp desc 排序；指标标量/时间序列查询和公式按 __result desc 排序；日志/追踪标量/时间序列查询按主聚合降序排列。调用方提供的值会原样转发。插入默认值时，响应会附加一条决策说明。
• 验证：除插入的边界值外，请求会原样传递给 SigNoz，由 SigNoz 进行验证。requestType 没有默认值（raw、trace、time_series 或 scalar）；start 和 end 必须是 Unix 毫秒时间戳。
• 指南路由：日志请阅读 signoz://logs/query-builder-guide，追踪请阅读 signoz://traces/query-builder-guide，指标/公式请阅读 signoz://metrics-aggregation-guide，PromQL 请阅读 signoz://promql/instructions。
• 时间序列排名注意事项：Top-N 分组按整个请求时间窗口进行排名。即使某个短暂峰值在一个时间桶中占主导地位，也可能被省略；遇到这种情况时，请缩短时间窗口或调整限制。
• 后端警告：后端返回的非致命警告（例如，存在歧义的键解析）会与原始响应一同作为说明呈现，并记录为 WARN 日志，这与搜索/聚合/query_metrics 工具的处理方式一致（此前会原样返回响应正文并丢弃警告）。
• 未找到键的错误：如果过滤器引用的键不在工作区中所查询信号的元数据内，操作会失败；错误文本会提供恢复指导，结构化错误内容中还会包含机器可读的 missingKeys 数组。
• 文档：请参阅 SigNoz Query Builder v5 文档