用自然语言驱动观测云：OWL 从查询诊断到资源创建

OWL(Observability Workflow Layer) 是观测云面向工具调用、自动化编排和 AI Agent 提供的统一能力入口，支持 OWL CLI 和 OWL MCP Server 两种接入形态。本文聚焦 OWL CLI：让支持终端操作的 AI Agent 通过自然语言调用工作空间中的日志、指标、链路、RUM、事件和基础设施等能力，关联诊断证据，并在明确授权后创建监控器和仪表板。

本文从安装和授权开始，带你完成第一次只读查询，并通过告警链路、API 5xx、主机与容器、Pipeline、监控器和仪表板六个场景，展示如何从问题描述走到可复核的结论或经过确认的资源变更。

完成安装后，日常使用不需要手动组织复杂命令。你只需要说明问题、时间范围、关注对象、操作边界和期望结果。自动安装会一并配置基础 Skill（owl-diagnostics）；已有环境可先按安装章节末尾的说明检查 CLI、Skill 和工具目录。

安装与配置：让 AI 接入观测云

开始安装前，核心需要准备两项信息：工作空间所属站点的 OWL_REGISTRY_ENDPOINT，以及在观测云控制台右上角「个人 API 密钥」中生成的短期 OWL_TEMP_CODE。

请打开 OWL 自动安装说明，在「Endpoint 列表」中按工作空间所属站点查找对应地址，并将其填入 OWL_REGISTRY_ENDPOINT；私有部署版以实际部署提供的地址为准。填写时只保留 Endpoint 根地址，不要自行追加 /api/v1 或其他路径。同时确保使用的 AI 工具能够执行终端命令，且当前环境可以访问该 Endpoint。

准备好 Endpoint 和临时授权码后，把下面的任务发送给支持终端操作的 AI 工具，让它按照官方说明完成安装、认证和工具目录同步：

阅读 https://static.guance.com/owl/skill.md，按照文档在当前环境中安装并配置 OWL CLI 和基础 OWL Skill。

安装参数如下：
OWL_REGISTRY_ENDPOINT="<工作空间所属站点的 Endpoint>"
OWL_TEMP_CODE="<控制台生成的临时授权码>"

安装完成后，请验证 OWL CLI 可以运行、工具目录已经同步，并列出当前授权范围内可用的 OWL 能力。

安装成功后，AI 应确认 OWL CLI 可用、工具目录已经同步，并列出当前授权范围内可调用的能力。若出现认证、网络或同步错误，应先处理错误，再继续查询。临时授权码和 API Key 都属于敏感信息，不要写入仓库、共享文档、截图或长期日志；OWL 可访问的资源和可执行的操作由当前 API Key 权限决定。

已有环境检查与进阶配置。

基础 Skill 帮助 AI 使用 OWL 查询、诊断并整理报告；其他场景 Skill 可按需补充。OWL CLI 提供数据查询、DQL 校验以及监控器和仪表板等资源操作接口，实际可执行的操作以当前工具目录和 API Key 权限为准。

• owl-diagnostics（基础）：提供 OWL 使用、查询诊断和报告输出的通用规则，自动安装流程会配置此 Skill。
• owl-monitor（可选）：补充基于真实指标生成监控器 JSON 的配置规范和验证流程。
• owl-dashboard（可选）：补充基于在线数据生成仪表板 JSON 的图表、变量、布局和验证规范。
• dql（可选）：提供专门的 DQL 生成、修复、审查和校验流程。

上述可选 Skill 用于补充配置规范和校验流程，不是调用对应 OWL 接口的前提。创建监控器或仪表板前，AI 需生成完整配置、完成校验并获得你的确认，创建后再核对结果。本文的 Pipeline 场景仅生成草案和验证样例，不执行线上创建。

如果已经安装过 OWL，可以把下面的检查任务发送给当前使用的 AI 工具，确认环境是否就绪：

请检查当前环境的 OWL CLI 和基础 OWL Skill（owl-diagnostics）是否可用。若 CLI 尚未安装，请说明缺少的准备项；若已安装，请同步工具目录，查看当前可用工具及参数，并列出查询、DQL 校验、Pipeline 验证、监控器和仪表板相关能力。

若缺少 owl-diagnostics，请阅读 https://github.com/GuanceCloud/ai-skills 的安装说明，根据当前 AI 工具选择正确的 agent adapter 补充安装，避免重复安装。

本次只检查环境和工具能力，不创建或修改工作空间资源，也不默认安装其他场景 Skill。请说明已就绪的能力、缺失项和下一步。

第一次使用：生成可复核的事件摘要

安装完成后，不必先研究工具目录和查询语法。复制下面这段话，让 AI 用 OWL 完成第一个只读任务：

请使用 OWL 查询最近 1 小时的观测云事件，只执行只读操作，并注明实际查询的起止时间及时区。

先按发生时等级和当前状态汇总事件记录数，区分事件记录数与独立故障数，避免将同一故障的异常和恢复记录重复计为多个故障。当前状态注明核查时间，无法确认时标记为“待核实”。

再列出最值得关注的 5 条事件，包括发生时间、标题、关联资源和当前状态，最后分成“需要立即处理”“建议继续观察”“暂不需要动作”三组。

如果没有数据，请说明实际检查的时间范围和筛选条件，不要把空结果直接解释为系统正常。

在权限和数据完整的情况下，AI 会基于 OWL 返回的数据，生成包含时间范围、汇总结果和重点事件的摘要。返回后，可以在观测云事件中心使用相同的时间范围、等级和状态进行抽查。第一次成功的标准不是看到命令执行完，而是结果能够与页面数据对应，并可以继续追问或用于日报。

接下来可以继续告诉 AI：“展开第 1 条事件”“补查关联日志和指标”“把结果整理成 Markdown”。下图展示的是从事件查询继续形成结构化结果的过程：重点检查实际时间范围、筛选条件和重点事件是否完整。

把观测云页面上的常用操作交给 OWL

理解 OWL 不必从工具名开始。先确定平时在页面上完成的任务，再把目标、范围和输出要求交给 AI。AI 负责理解任务、编排步骤和整理结论，通过 OWL 调用观测云的查询与资源操作能力：

优先交给 OWL 的任务通常有三个特征：目标和筛选口径明确、需要跨数据域补充证据、结果需要复用或交付。第一次尝试应从只读查询开始，确认结果可靠后再扩展到监控器、仪表板等写入操作。

如何描述一个可执行、可验证的任务

不需要记住工具名。把五件事说清楚即可：问题是什么、查看哪个时间范围、关注哪些对象、允许执行什么操作、希望得到什么结果。

可以直接套用下面的结构：

请使用 OWL 处理“<问题>”。

范围：<时间范围和关注对象>
操作边界：本轮只执行只读操作。如需写入，先输出变更预览和验证方法，待我另行明确确认后再执行。
输出：已确认事实、证据、推断、证据缺口和下一步建议。

如果没有数据，请说明实际检查的时间范围、筛选条件和权限，不要把空结果直接解释为系统正常。

AI 根据任务目标、当前可用工具、工作空间数据和权限选择查询与验证路径，并通过 OWL 执行。检查结果时，重点确认三个问题：结论是否回答了原始问题，关键判断是否有证据，证据不足时是否明确说明了缺口。

从排查到创建：六个典型场景

前面的“第一次使用：生成可复核的事件摘要”已经完成一次只读查询。下面的前三个场景聚焦只读排查，后三个场景展示从配置草案到受控创建的过程；凡是涉及写入，都应先检查预览和影响范围，再明确确认。

场景 1｜告警链路诊断：为什么没有收到告警

已经存在监控器，但没有收到预期告警时，让 AI 通过 OWL 沿“规则—数据—事件—通知”链路只读排查：

请使用 OWL 排查“<监控器名称>为什么没有收到告警”，只执行只读操作。

排查范围：<起止时间及时区>。如果期间发生过规则变更，请核对预期触发时生效的配置及变更时间；无法获取历史配置时，说明证据缺口。

按顺序检查：规则是否存在并启用，检测条件和时间窗口是什么；对应检测窗口内源日志、指标或链路是否有数据；条件是否满足，是否生成事件；告警策略和通知对象是否配置。请判断问题位于“规则配置、源数据、事件生成、通知配置”中的哪一段，并列出证据。观测云无法证明的外部渠道送达情况，标记为证据缺口。

检查结果。确认 AI 是否基于 OWL 返回的证据定位到“规则配置、源数据、事件生成、通知配置”中的具体环节，并为判断提供证据。外部渠道是否最终送达仍需结合通知系统回执；如果监控器缺失或规则已经不符合当前目标，可以继续使用场景 5 的监控器创建流程。下图展示了按四段链路整理诊断结论的结果。

场景 2｜API 5xx 上升：关联 Trace、日志与资源

API 5xx 上升时，让 AI 通过 OWL 从错误 Trace 出发补齐关联证据：

请使用 OWL 排查“<服务名称>最近 30 分钟 API 5xx 上升”，只执行只读操作。

与前一个 30 分钟窗口比较，注明两个窗口的起止时间及时区，分别统计请求总量、5xx 数量和错误率。说明请求统计口径和采样情况，避免将同一请求的多个 Span 重复计数；采样情况无法确认时，说明对结论的限制。

确认受影响的接口、错误类型和趋势，选择代表性 Trace 并关联日志；只有证据指向容量、重启或网络变化时，再补查指标、基础设施和事件。输出已确认事实、疑似原因、置信度、证据缺口和下一步建议，不要把相关性直接写成根因。

检查结果。确认输出是否包含受影响接口、错误类型、趋势、代表性 Trace 和关联日志。数据和关联字段完整时，可以形成故障记录；证据不足时，应列出缺失信息和验证方向。下图展示了跨数据域取证后的结构化诊断结果。

场景 3｜主机与容器巡检：批量发现异常资源

当资源数量较多，逐个打开页面检查效率很低。让 AI 通过 OWL 按统一口径批量巡检主机与容器：

请使用 OWL 巡检“<环境或资源范围>”最近 1 小时的主机与容器，只执行只读操作。

先确认目标范围和实际可用字段；检查 CPU、内存、磁盘、负载、网络、容器状态与重启情况，并结合事件或关联日志识别异常。

按异常程度输出资源名称、异常指标、当前值、对比基线、关联证据和建议动作；明确列出因字段、权限或数据缺失而无法完成的检查项。

检查结果。确认异常资源清单是否包含资源名称、异常指标、当前值、对比基线和关联证据。字段或数据不完整时，应明确说明未检查项，避免把“未发现”写成“正常”。下图展示了批量巡检后的异常对象和优先级。

场景 4｜Pipeline 生成与验证：从真实日志提取字段

日志已进入工作空间但缺少结构化字段时，让 AI 通过 OWL 读取实际日志，生成 Pipeline 草案并调用样例验证接口：

请使用 OWL 读取“<日志索引或服务>”最近 30 分钟的日志。

本轮允许读取日志、生成本地 Pipeline 草案和调用样例验证接口，不创建或更新线上 Pipeline。

识别主要日志格式，选择正常、异常和边界样例并脱敏；根据实际日志生成 Pipeline 草案，不要补造不存在的字段。随后通过 OWL 调用样例验证接口，列出各组样例解析后的字段、类型和值，标记未匹配、类型错误和字段覆盖风险。输出草案、验证结果和适用范围。

检查结果。主要日志格式应能够稳定匹配，字段名称、类型和值符合预期，异常和边界样例不会被误解析。当前场景中，OWL 用于读取真实日志并完成样例验证；确认草案后，再在观测云中创建或更新 Pipeline。下图展示了多组日志样例的解析与验证结果。

场景 5｜监控器创建：从监控需求到可验证配置

当监控目标、检测周期、分组维度和告警条件已经明确时，可以让 AI 通过 OWL 检查数据，并将自然语言需求转化为可验证的监控器配置。与场景 1 的只读排查不同，这一场景会写入平台资源，因此创建前必须先完成数据检查、查询校验和配置预览。

请使用 OWL 为“<监控目标>”准备一个观测云监控器。

先只读检查当前工作空间中的数据域、检测对象、字段和单位，确认存在可用于监控的真实数据；不要猜测字段、单位或分组维度。

根据我的监控目标，设计监控器名称、检测周期、分组维度、告警等级、阈值、事件内容和告警策略，并校验最终查询。先输出完整配置预览和验证方法，在我明确确认前不要创建监控器。

我确认后再执行创建，并读回监控器详情，核对名称、启用状态、检测周期、分组、阈值、查询和告警策略。如果监控目标中缺少阈值、通知对象或告警策略，请列出需要补充的信息，不要自行选择。

检查结果。创建后应读回监控器详情，确认名称、状态、周期、分组、阈值、查询和告警策略与预览一致。查询校验通过并不代表通知一定能够送达，还需要实际触发事件并检查最终通知内容。下图展示了基于真实数据生成并验证监控器配置的结果；完整案例可参考 自然语言生成观测云监控器最佳实践。

场景 6｜仪表板创建：根据真实数据生成观测视图

OWL 可以读取、创建或替换仪表板。这个场景会写入平台资源，因此应先检查真实数据和现有仪表板，再让 AI 输出创建预览：

请使用 OWL 为“<服务或系统名称>”准备一份观测仪表板。

先只读检查是否已有同名或同用途仪表板，并确认需要的数据源、指标和字段存在。然后设计变量、图表、查询口径和默认时间范围，输出仪表板名称、配置预览和验证方法。

在我明确确认前，不要创建或替换仪表板。我确认后再创建，并读回详情核对名称、变量、图表和查询配置；如果存在同名仪表板，不要直接替换。

创建结果与配置核对。创建前，先确认数据源、指标和字段真实存在、查询能够返回数据，并检查配置预览中的名称、变量、图表、查询口径和默认时间范围。确认后，由 AI 通过 OWL 创建仪表板并读回详情，核对实际配置与预览是否一致。下图展示了创建完成后的仪表板信息、配置验证结果和创建回执。

运行总览与资源排行。创建后，在观测云页面检查仪表板能否正常打开，概览数值、资源排行和资产明细是否有数据，并与相同时间范围内的源数据抽查核对。下图展示了仪表板的运行总览、风险定位和主机资产明细。

资源趋势与网络指标。继续检查 CPU、内存、负载、进程数和网络指标的趋势是否正常展示。图表为空时，先检查数据源、字段、时间范围和权限，再核对查询配置。下图展示了仪表板中的资源趋势与网络指标。

将查询结果沉淀为日报与故障记录

完成查询或诊断后，可以继续把结果整理成可复核、可交付的材料：

请把刚才的结果整理成一份 Markdown 报告。
报告必须包含：查询目标、绝对时间范围、筛选条件、关键发现、证据、疑似原因、证据缺口和下一步建议。事实与推断分开写；每条建议说明对应依据。最后附上一段适合发送到工作群的 200 字以内摘要。

一次性问题可以形成诊断结论，重复性工作可以沉淀成固定任务。涉及写入时，先预览变更和验证方法，得到授权后再执行并读回确认。OWL 的价值在于让验证过的方法持续复用。

OWL 与观测云 UI 如何配合

当问题、时间范围和输出目标明确，或者任务需要批量查询、跨数据域取证、重复复用和生成报告时，可以优先使用 OWL。需要交互式探索数据、观察图形趋势或精细调整可视化布局时，可以继续使用观测云 UI。

OWL 在当前 API Key 的授权范围内调用观测云能力，可以根据任务需要与观测云 UI 自然切换。任何可能创建、更新或替换平台资源的操作，都应先预览变更并确认影响范围；执行后再读回配置，或在观测云页面检查实际结果。

从一次只读查询开始

现在就从一次只读查询开始：

1. 打开 OWL 自动安装文档，准备工作空间 Endpoint 和临时授权码。
2. 将“安装与配置：让 AI 接入观测云”中的安装任务发送给支持终端操作的 AI，确认 OWL CLI 可用且工具目录已经同步。
3. 复制“第一次使用：生成可复核的事件摘要”中的任务，获得第一份基于工作空间真实数据生成的结果。
4. 在事件中心使用相同时间范围和筛选条件抽查结果。

当结果能够回答问题、关键判断有证据、空结果说明了检查范围，就完成了第一次可复核的 OWL 实践。后续再逐步扩展到跨域诊断、监控器和仪表板创建。