signoz-searching-docs

SigNoz 文档

仅使用 signoz.io 官方文档和 API 参考资料。所有回答都必须以获取的文档内容为依据，并引用规范文档 URL。

访问文档

如有 SigNoz MCP 服务工具，请优先使用；否则改用直接 HTTP 获取。

首选：MCP 工具

• signoz_search_docs：在索引文档库中进行关键词搜索。对于同一主题，以 searchText 传入 2 到 6 个关键词，例如 Kubernetes pod logs；产品和技术名称保持用户的写法，并删除“how do I”或“please”等填充词。不要传入完整的问题句。当问题中只有一个可用词时，例如 Retention?，只发送该词，不要凑词或编造关键词。包含两个意图的问题应拆成两次调用。如果问题明确对应单个文档章节，可用 section_slug 缩小范围；复用先前结果中的 section_slug，不要猜测 slug，并遵循工具参数说明中的 slug 和排序行为。如果首个结果不相关，回答前用更少或不同的词重试一次；对于单词问题，用同义词或补充一个上下文词重试，例如对 Retention? 搜索 data retention。
• signoz_fetch_doc：获取一个索引页面的 Markdown。传入规范 URL 或 /docs/... 路径；也可通过 heading 将范围缩小到某个章节。每次响应都要检查 truncation_reason 和 available_headings，不要想当然地认为返回的 content 已完整。

切勿使用空的 searchText 调用 signoz_search_docs；请传入取自用户问题的关键词，仅可在上述重试情形中添加同义词或上下文词。 切勿在未提供 URL 时调用 signoz_fetch_doc；这两个工具都不会猜测缺失的输入。 signoz://... URI 属于 MCP 资源：必须通过 MCP 资源 API 读取， 绝不能使用 signoz_fetch_doc；该工具只接受 https://signoz.io/docs/... URL 或 /docs/... 路径，并会拒绝其他范围。

切勿凭记忆构造 /docs/... URL。只有在 signoz_search_docs 返回 URL 后，才能将其传给 signoz_fetch_doc；即使你认为自己知道页面路径，也必须先搜索，再从结果中获取规范 URL。

备用方式：直接 HTTP 获取

如果无法使用 MCP 工具，SigNoz 文档原生支持 Accept: text/markdown。

通过站点地图发现：

GET https://signoz.io/docs/sitemap.md

获取特定页面：

GET https://signoz.io/docs/<path>/
Accept: text/markdown

工作流

1. 识别领域：根据用户的问题判断领域：埋点、OpenTelemetry 设置、查询、仪表板、告警、故障排除、部署或 API 文档。
2. 查看下方的启发规则表。如果有匹配的启发规则，回答前先阅读：启发规则包含产品决策（哪种路径或方法适合用户的环境），在两种路径中都很有用。
3. 搜索并获取文档：根据工具是否可用选择路径：
   • 使用 MCP 工具时：使用用户问题中的 2 到 6 个关键词（如果问题只有一个词，则使用该词）调用 signoz_search_docs；如果领域能明确映射到某个分类，则传入 section_slug。阅读排名靠前的 1 到 3 条结果，并对选定的 URL 调用 signoz_fetch_doc（如果页面较长且问题针对某个子部分，则使用 heading 缩小范围）。如果排名靠前的结果不相关，则使用更少或不同的词（单词问题则使用同义词）重试一次。
   • 不使用 MCP 工具时：在 sitemap.md 中 grep 候选页面，根据与任务的直接相关程度对最佳的 2 到 5 个页面排序，并且仅使用 Accept: text/markdown 获取站点地图中找到的 URL。启发规则覆盖范围有限；对于没有对应启发规则的主题，请按分类路径浏览站点地图，并优先选择设置、故障排除或 API 参考页面，而非概览页面。
   • 范围较窄的问题只获取 一个页面；涉及设置和故障排除，或方法选择和语言指南的任务则获取 多个页面。尽量精简页面数量。
4. 回答前处理截断的获取结果。 当 signoz_fetch_doc 返回 truncation_reason: "size" 时，将 content 视为不完整的前缀。从 available_headings 中选择最相关的条目，并使用该 heading 重新获取同一搜索结果 URL。如果没有标题涵盖问题，或缩小范围后的响应仍在所需内容之前被截断，请说明获取的文档不完整，不要推断被省略的内容或设置不存在。
5. 依据获取的文档作答，并引用规范的 https://signoz.io/docs/... URL。
6. 有意处理歧义：如果有多个可能的页面，优先选择最直接解决任务的页面；只有在其他页面会实质性改变答案时才提及。

消息操作

在最终回答中，根据 SigNoz Skills & MCP 规范发送 FE 移交操作：

• open_docs：使用主要引用页面的规范 URL。文档查询正是适合深层链接到来源页面的场景，方便用户查看上下文并核实答案。
• follow_up：提供 1 到 2 个可在文档解答基础上继续探索的提示。设置指南之后可问：“带我执行第一个命令”或“这里常见的陷阱是什么？”。概念页面之后可问：“给我看一个完整示例。”
• 不要发送 apply_filter。文档解答不会生成适用于探索器页面的查询；发送 apply_filter 会覆盖用户正在使用的查询。

原样保留的约束：回答 SigNoz 文档问题时，最终消息中必须包含指向主要引用页面规范 URL 的 open_docs 操作。

领域启发规则

获取文档前，先阅读匹配的启发规则文件。每个文件都包含引导用户选择合适指南的决策逻辑。

主题	触发关键词	启发规则文件
发送日志	logs、log collection、logging、send logs	sending-logs.md