VeOps CLI：你的火山引擎可观测排障助手

线上排障最耗时间的环节是什么？往往不是判断本身，而是收集证据。

告警响了，工程师的第一反应是打开一堆系统：先去 APMPlus 看错误率和延迟曲线，再去日志服务搜报错，再翻几条 Trace 看慢在哪个 Span，再确认服务拓扑里有没有下游依赖异常。如果问题涉及云资源，还得去云监控翻 ECS、CLB、RDS 的指标；如果服务跑在 Kubernetes 上，还要查 Pod 状态、事件、重启次数和容器日志。

这些动作分散在不同产品、不同页面里。每一步都不复杂，但每一处都要重复输入服务名、时间范围、地域、workspace、topic、cluster id。问题稍微复杂一点，证据就散落在多个系统中，最后还得人工对齐时间线 ------

10:03 错误率升高
10:05 出现 timeout 日志
10:08 下游 Span 变慢
10:10 Pod 重启

一条完整的证据链，靠的是人肉拼接。

VeOps CLI 的出现，就是为了把这件事交给 AI。

VeOps CLI 是什么

VeOps CLI 是由火山引擎推出的一套面向 AI Agent 的可观测排障工具，把 APMPlus、托管 Prometheus（VMP）、云监控（CM）、日志服务（TLS）、容器服务（VKE），以及本地日志和指标分析能力，整理成 Agent 可以稳定调用的命令行接口。

装好之后，通过 Claude Code、Codex、Cursor、Trae、OpenClaw、Hermes 等 Agent，你就可以直接查指标、翻日志、看 Trace、排告警、巡检集群，把排障过程中大量重复的查询和证据整理工作分担出去。

VeOps CLI 不替工程师做最终判断，它做的事更基础也更实在：把"到处查、反复筛、手动对齐"这个过程交给 AI：工程师描述问题，AI 去查数据、整理证据、给出结论和下一步建议。

这也是它天然适合做成 Agent 工具的原因。排障场景里充斥着大量固定动作 ------ 查服务指标、查错误日志、查 Trace、查告警历史、查资源指标、查 Pod 事件。这些动作输入输出明确、组合方式相对稳定，交给 Agent 自动执行，工程师只需要做最后的判断和决策。

安装与配置

VeOps CLI 不是一个新的聊天机器人，而是一套可以被通用 Agent 调用的工具能力。你不需要换掉正在使用的 AI 助手，只需要把这套能力装进去。

安装方式很简单，把下面这句话发给你的 AI 助手即可：

arduino 复制代码

帮我安装 veops-cli：https://veops-cli.tos-cn-beijing.volces.com/public/install.md

AI 会读取安装文档，自动判断操作系统和 CPU 架构，下载对应二进制，完成路径配置和能力注册，并做一次基础自检。安装完成后，完整退出并重新打开 Agent，让它重新加载新能力。

💡 安装工具

AI 自动下载 veops-cli，放到合适的位置，并完成 Agent 能力注册。

💡 完成登录

支持控制台 OAuth 的方式，以及 AK / SK 环境变量。

如果是在远程机器、SSH、容器这类没有浏览器的环境中，VeOps CLI 也支持两步式登录。AI 会先生成授权链接，你在本机浏览器里完成登录，再把页面返回的授权结果交给 AI 完成登录。

VeOps CLI 本身也是标准命令行工具。你可以让 AI 调用它，也可以直接在 shell、cron、CI 中调用它。Agent 负责把自然语言问题转成查询动作，工程师仍然可以在需要时直接拿 CLI 做自动化巡检和脚本化分析。

使用方式

使用 VeOps CLI 时，不需要记命令。把问题描述清楚即可。

css 复制代码

帮我看一下 order-api 最近 1 小时为什么错误率升高。

收到这个问题后，AI 不会只跑一条命令。它会先判断应该查哪些数据线，然后按排障路径逐步收集证据：先看 APM 指标确认错误率是否真的升高，再找慢 Span 或错误 Span，再查错误日志看具体报错，看是否集中在某个下游，再结合服务拓扑确认依赖关系。如果服务跑在 VKE 上，还会继续看 Pod 重启、事件和容器日志。

一次比较完整的结果通常会包含五类信息：

💡 注意：

VeOps CLI 目前只有查询能力，不会对你的云资源做任何修改
权限跟随火山引擎账号，不会看到权限范围外的数据
VeOps CLI面向 Agent 设计，如果遇到问题，直接描述现象让 AI 排查即可，不需要记命令

覆盖的数据源

VeOps CLI 目前覆盖火山引擎可观测排障中最常用的几类数据源：APMPlus、VMP、CM、TLS、VKE，以及本地日志 / 指标异常检测。下面这张表可以快速理解它能帮你查什么。

更多详细操作，可以查看官方文档：

docs.volcengine.com/docs/86845/...

典型使用场景

VeOps CLI 的使用方式，不是"查一个接口、返回一段 JSON"，而是围绕排障任务组织多步查询，把分散的数据串成一条完整的证据链。

下面我们以七个常见场景为例，看它是怎么工作的。

场景一：告警排查

⚠️ 服务告警：order-api 错误率超过 5%，持续 3 分钟。

告警来了，最重要的是得快速回答三个问题：为什么触发、影响多大、现在好了没。

用 VeOps CLI，你可以直接把告警规则 ID、告警名称或大致时间告诉 AI，AI 会自己去查告警规则、告警历史、指标曲线、日志、服务信息，还原完整时间线：

diff 复制代码

帮我排查这个告警 rule-xxx：
- 时间范围：今天 10:00 到 11:00
- 关联服务：order-api
请说明触发原因、影响范围、是否恢复，以及下一步建议。

以前，你得先点进告警页看规则说明，再切到指标页拉曲线确认异常，再去日志平台筛报错，最后靠自己把这几条线对齐，手动整理一份结论。现在 AI 直接把触发原因、指标变化、日志样本、影响范围、建议动作打包成一份完整的排查报告，省掉的是"翻五个页面""手动对时间线"的那些重复活。

场景二：接口变慢

⚠️ checkout-api P99 延迟在 14:00 后从 200ms 升至 3s。

接口变慢这事，往往不是单点问题 ------ 代码本身慢、下游依赖堵了、数据库响应变长、资源不够用，甚至可能是半个小时前刚发上去的一个小改动引入的。APMPlus 的指标曲线能告诉你"慢了"，但很难直接告诉你"慢在哪"。

用 VeOps CLI 查，只需要把问题描述清楚：

复制代码

checkout-api 最近 2 小时 P99 明显升高。
请帮我定位慢在哪一层，是否和下游服务或发布有关。

AI 会同时拉取 APMPlus 指标、Trace、Span、服务拓扑和日志，先确认延迟是从哪个时间点开始升高的，再找出这个时间段内的慢请求，按 Span 耗时排个序，看耗时是集中在某个下游服务、某条数据库查询，还是某个时间点之后才出现的。

查出来的结果可能是"payment-service 的 create 接口超时从 200ms 涨到 3s"，也可能是"MySQL 慢查询集中在 order_detail 表"。你拿到的是一条明确的排查线索，不是一句"P99 升高了"，也不是一堆待你自己分析的原始数据。

场景三：发布后验证

⚠️ payment-api 新版本于 20:00 发布上线。

发布之后最磨人的状态是"看着没报错，但心里不踏实"。有没有变差、差了多少、要不要回滚 ------ 这些问题通常要人工对比发布前后的错误率、延迟、QPS、资源指标和日志，截图、对齐、写结论，一套流程下来不轻松。

用 VeOps CLI 做发布复盘：

diff 复制代码

帮我做一次发布复盘：
- 服务：payment-api
- 发布时间：20:00
- 对比窗口：发布前后各 30 分钟
- 关注：错误率、P99、QPS、CPU、错误日志
请判断发布后是否有劣化。

AI 把发布前后两个时间段的指标拉到一起对比。如果发现错误率升高或延迟变差，再往下钻一层，翻对应时间段的日志和 Trace。最终输出的不是一句"有变化"，而是"哪些指标变差、幅度多大、是否有代表性错误、建议继续观察还是回滚"。你不需要盯着监控面板反复刷、不用自己截图对比、不用纠结怎么判断 ------ 报告直接给到手里。

场景四：云资源异常定位

⚠️ order-api 从 14:00 开始超时增多。

很多应用问题最终会落到资源层。CPU 突然打满、磁盘空间不足、网络包量异常，都可能表现为业务接口超时。但应用团队和基础设施团队之间，常因为"到底是应用问题还是资源问题"来回沟通。

通过 VeOps CLI，AI 可以同时查 APMPlus 指标、错误日志，以及关联 ECS 的 CPU、内存、网络指标：

css 复制代码

order-api 从 14:00 开始超时增多。
帮我同时看 APMPlus 指标、错误日志，以及关联 ECS 的 CPU、内存、网络指标。

AI 把应用层和资源层的异常时间线放在一起对比。如果两边的异常时间点吻合，证据链就串起来了。工程师拿到的是对齐后的完整画像，不需要自己两边查、两边问，直接判断责任边界和处理方案。

场景五：VKE 集群巡检

⚠️ 凌晨 2:00，收到 ccvke-xxx 集群告警。

集群巡检涉及大量对象：节点、节点池、Pod、Deployment、Event、日志。人工逐个检查很耗时，也容易漏掉某些异常。

用 VeOps CLI 做一次集群巡检：

diff 复制代码

帮我巡检 ccvke-xxx 集群：
- 看节点池、节点、插件状态
- 找出异常 Pod 和最近重启的 Pod
- 汇总 namespace 下的 Warning Event
- 对异常项给出处理建议

AI 会输出一份结构化巡检报告：哪些节点 NotReady，哪些 Pod CrashLoopBackOff，哪些事件集中在镜像拉取失败，哪些 Deployment 副本数不满足预期。所有异常汇总成一张清单，值班巡检不用再逐个 namespace 翻查。

场景六：日志异常模式归类

⚠️ user-service 最近 1 小时产生大量 error 日志。

查日志最怕什么？可能不是没日志，而是日志太多。几千条 error 堆在屏幕上，让人很难快速抓住重点 ------ 看起来每条都在报错，但没有一条能告诉你"主要问题是什么"。

交给 VeOps CLI 来归类：

css 复制代码

搜 user-service 最近 1 小时的 error 日志。
请按错误模式归类，列出 Top 5，每类给 2 条代表样本。

AI 会把几千条日志按错误模式自动归类，输出一份分布摘要：数据库连接超时占 62%、参数校验失败 21%、下游 5xx 占 12%、未知异常 5%。让你几秒钟就能判断：今天最该查的是 DB 连接池，不是盯着那堆偶尔出现的校验报错一条一条看。

场景七：AI 应用可观测排查

⚠️ 智能助手最近 1 小时用户反馈"答非所问"。

业务一旦接了大模型，排障的姿势跟普通微服务就不太一样了。模型调用失败、工具调用超时、长链路 session 中断、多轮对话上下文溢出 ------ 这类问题在传统链路追踪里往往看不出所以然，因为链路太长了，节点也跟普通 HTTP 调用不太一样。

这时，用 VeOps CLI 调一下 APMPlus 的 GenAI session 能力：

复制代码

帮我看最近 1 小时智能助手的失败 session。
请分析是模型调用失败、工具调用失败，还是业务服务返回异常。

AI 会在 session 链路中标记出失败节点，把模型层、工具层、业务层各自的状态拆开，告诉你问题出在哪儿。AI 应用的可观测性，不再是黑盒。

带来的价值

VeOps CLI 的价值，可以从几个不同角色来看：

再深一层，VeOps CLI 不是简单给 AI 接一个可观测后端。它在解决的是 Agent 排障中更实际的工程问题：数据怎么稳定获取、结果大了怎么处理、跨产品怎么关联、结论怎么审计：

结语

可观测系统已经积累了足够多的数据：指标、日志、Trace、告警、事件、资源状态、容器状态。但数据本身不是答案，答案需要被串起来。

VeOps CLI 做的，就是把分散在不同入口的可观测能力整理成 Agent 可以稳定调用的工具。它不替工程师做判断，也不试图替代人对业务和系统的理解 ------ 它做的事情更基础：把该查的数据查出来，把散落的证据整理好，把可能的方向列出来。剩下的事情，还是工程师来定。

值班、发布验证、排障、巡检、云资源定位，这些场景里的重复劳动，VeOps CLI 已经能解决大部分。下次告警再响，不妨先让装好这个工具的 AI 助手跑一遍证据链，你再决定下一步怎么处理。

现在就让你的 AI 助手装一个试试：

arduino 复制代码

帮我安装 veops-cli：https://veops-cli.tos-cn-beijing.volces.com/public/install.md

另外预告一下：火山引擎全栈可观测平台正在公测智能运维助手，后续会提供更多可观测深度沉淀的知识和能力，部分功能正在分阶段上线，敬请期待。