OWL CLI 工具清单¶

本文档介绍当前 OWL CLI 可直接执行的业务工具能力，包含工具范围、权限类型、CLI 使用约定、工具总览以及按分类整理的工具说明。

工具的可见范围和执行结果取决于当前 OWL_TOKEN 对应 API Key 的权限。如果 API Key 不具备相应资源或操作权限，对应工具可能执行失败或返回空结果。

工具范围¶

OWL CLI 暴露的工具会随着平台能力持续更新。实际可见工具以本地完成 owl sync 后，通过 owl list 返回的工具目录为准。

当前文档覆盖以下业务分类：

权限类型¶

CLI 使用约定¶

数据结果文件中的采样字段¶

当工具输出类型为 data 时，CLI 在写出数据文件的同时，会在执行结果中可选地带出一个 sample 字段：

• sample：数值（浮点数），表示本次查询的采样比例（例如 0.0077 表示约按 0.77% 采样）。仅当后端返回了采样信息、或数据文件内容里能解析出采样比例时才会出现；没有采样信息时该字段会被省略。
• 拿到 sample 时，意味着结果是基于采样数据估算的，做计数、求和等聚合解读时需要按采样比例还原后再判断量级。

常用 CLI 命令示例：

owl sync
owl list
owl list -c data
owl show owl.data.query
owl exec owl.metric.list --mode source
owl exec owl.event.list --start_time 1712505600000 --end_time 1712592000000 --limit 20

工具总览¶

Catalog¶

用于统一资源目录的实体类型发现、实体查询、实体详情获取和拓扑关系查询。

Dashboard¶

用于仪表板的创建、替换和详情获取。

Data¶

用于完整数据查询与查询辅助，覆盖日志、指标、RUM、APM、Network、Profile、Billing 以及已转发到对象存储的数据。

数据转发异步查询¶

owl.data_forwarding.rule.list、owl.data_forwarding.query.create 和 owl.data_forwarding.query.get 用于发现可查询规则，并查询已经通过规则写入对象存储的数据。这三个工具都是单次原子调用，CLI 不会自动选择规则、轮询任务或继续查询下一批数据。rule.list 和 query.create 直接返回文本结果；query.get 的 outputType 为 data，每次状态查询都会写入一个新的本地数据文件。

按以下顺序完成一次查询：

1. 用户没有提供准确规则名，或规则是否可查询尚未确认时，先调用 owl.data_forwarding.rule.list。查询场景保持 queryable_only=true，从 queryable=true 的结果中选择 rule_name；不要把 rule_uuid 传给 create。
2. 调用 owl.data_forwarding.query.create，原样传入选中的 rule_name、查询时间范围和过滤条件，取得 task_id。
3. 使用该 task_id 调用 owl.data_forwarding.query.get。其执行结果中的文件对象不包含数据文件 ID：运行 owl data list -f json，找到对应条目，原样保存 files[].id，再执行 owl data show <file-id>。不要根据路径推导或猜测 ID。
4. 检查文件中的 task_status。值为 created 或 running 时，任务尚未完成；即使 items 为空也不能当作最终结果，应稍后继续使用同一个 task_id 调用 get，然后重复数据文件列表步骤查看最新状态。
5. task_status 为 completed 或 failed 时停止轮询。completed 时读取脱敏后的 items；failed 时根据返回的失败信息排查。
6. completed 且 next_token 非空时，再次调用 create 查询下一批。必须保留原来的 rule_name、start_time、end_time、search 和 page_size，并将 next_token 作为 token 传入。新的 create 会返回新的 task_id。

发现可查询规则：

owl exec owl.data_forwarding.rule.list -p '{
  "queryable_only": true,
  "page_index": 1,
  "page_size": 20
}'

创建首批查询任务：

owl exec owl.data_forwarding.query.create -p '{
  "rule_name": "forward-rule",
  "start_time": 1784800000000,
  "end_time": 1784886400000,
  "search": {
    "conditions": [
      {
        "key": "status",
        "value": "error",
        "logic": "match"
      }
    ],
    "operator": "and"
  },
  "page_size": 20
}'

查询任务状态和结果：

owl exec owl.data_forwarding.query.get -p '{"task_id":"task_xxx"}'
owl data list -f json
owl data show <保存的文件-ID>

查询下一批时，复用原查询参数并传入 next_token：

owl exec owl.data_forwarding.query.create -p '{
  "rule_name": "forward-rule",
  "start_time": 1784800000000,
  "end_time": 1784886400000,
  "search": {
    "conditions": [
      {
        "key": "status",
        "value": "error",
        "logic": "match"
      }
    ],
    "operator": "and"
  },
  "page_size": 20,
  "token": "next_xxx"
}'

参数与限制：

• rule.list 默认 queryable_only=true，只返回可查询规则。设为 false 时也会返回不支持查询的规则，应通过 queryable 和 unsupported_reason 判断原因，不能继续调用 create 查询这些规则。
• rule.list 支持通过 search 模糊搜索规则名称，也可以通过 data_type 或 store_type 过滤；分页范围为 page_index >= 1、page_size 1 到 100。
• rule_name 必须使用 rule.list 返回的准确值，不能替换为 rule_uuid。数据类型和对象存储配置由后端根据规则确定。
• start_time 和 end_time 是 13 位毫秒时间戳，且 end_time 必须大于 start_time。
• 查询时长上限由工作空间配置决定，默认 24 小时；create 响应中的 query_time_limit_hours 是当前实际生效的上限。
• search.conditions[].logic 只支持 match 和 notMatch；多个条件通过 search.operator 的 and 或 or 组合。
• page_size 范围为 1 到 1000，默认 20。
• query.get 不直接把完整结果打印到 CLI，其返回的文件信息不包含 ID；应运行 owl data list -f json，原样保存对应条目的 files[].id，再通过 owl data show <file-id> 查看任务状态和脱敏结果。
• DF-API-KEY 由 CLI 自动注入，不应作为工具参数传入。免费版工作空间不支持该查询。
• 支持 S3、OSS、OBS、GCS，以及 TOS 标准存储；不支持 Kafka、平台内置存储、冷存和归档数据。

同组织跨工作空间 Trace 查询¶

owl.data.same_org.trace.query 是按 trace_id 查询当前或同组织工作空间 Trace 的专用工具。跨工作空间查询时，先运行 owl workspace same-org list 获取候选工作空间，再调用该工具：

• trace_id 为必填参数，服务端会强制加入该条件，不要在 where_clause 中重复添加。
• workspace_uuids 为可选字符串数组，取值使用列表结果中的 workspace_uuid；workspace_id 只用于列表分页，不能用于查询。
• workspace_uuids 省略或传空数组时，只查询当前 API Key 所属工作空间。
• 同组织跨工作空间查询功能关闭时，只允许查询当前工作空间；传入其他工作空间 UUID 会返回参数错误。
• where_clause 只传附加 DQL 条件片段，不包含外层花括号。
• start_time、end_time 使用 13 位毫秒时间戳；还可通过 source 和 limit 缩小查询范围。
• 返回内容保留原始 DQL 查询结果结构。跨工作空间 Trace 查询不要回退到 owl.data.query 或 owl.data.simple_query_file。

owl workspace same-org list
owl exec owl.data.same_org.trace.query -p '{"trace_id":"TRACE-XXXX","workspace_uuids":["wksp_xxx"]}'

Errors¶

用于错误中心的问题列表查询，以及评论的新增、查询和更新。

Event¶

用于事件中心列表查询和事件详情获取。

• owl.event.list 必须提供 start_time 和 end_time；status 可选值为 fatal、critical、error、warning 和 nodata，limit 默认值为 20、最大值为 100；返回项可能包含事件维度标签字段 df_dimension_tags。
• owl.event.get 的 timeRange 为可选的二元素数组 [start, end]，元素均为 13 位毫秒时间戳，且 end 必须大于 start。参数名为 timeRange，不要改写为 time_range。

Incident¶

用于故障列表、故障评论、操作记录和值班排班查询。

Infrastructure¶

用于基础设施对象列表和详情查询，覆盖主机、容器、进程等资源对象。

LLM¶

用于 LLM 可观测应用列表查询。

Member¶

用于空间成员列表查询和按姓名、邮箱关键字检索。

Monitor¶

用于监控器列表查询、详情获取、创建或更新，以及外部事件接收。

笔记与 Runbook¶

用于管理当前 API Key 账号可见的普通笔记与 Runbook。普通笔记适合记录结论和参考信息，Runbook 适合保存可重复使用的操作流程。

• owl.nbook_note.list 的 page_index 默认值为 1，page_size 默认值为 20、最大值为 100。
• owl.nbook_note.list 的 type 可选值为 normal 和 runbook；省略时返回两种类型。
• owl.nbook_note.get 是唯一返回 Markdown 正文 content 的工具，但不返回 path、etag 或 version；list、add 和 modify 只返回标题、类型、标签等基础信息，也不返回 content、path、ETag 或版本信息；delete 返回删除操作的精简结果。
• owl.nbook_note.add 必须提供 title 和 content；type 可选值为 normal 和 runbook，省略时创建普通笔记。该工具不接受 path；created_source 固定由服务端设为 ai，创建账号取自当前 API Key。
• owl.nbook_note.modify 除 note_uuid 外，至少还要提供 title、content、tags 或 tag_kv 中的一项；省略 content 时保留原正文。
• 内容类型在创建后不可修改；get、modify 和 delete 均不接受 type。如需更改类型，请按目标类型重新创建。
• 获取、修改和删除都使用列表返回的 note_uuid。不要传 path、etag、if_match、version、creator 或 created_source 等由后端管理的字段。
• tagkv_query 是列表工具使用的 TagKV 表达式字符串；tag_kv 是创建和修改工具使用的键值对象，两者不要混用。

Pipeline¶

用于 Pipeline 列表查询和样例验证。

mdsearch¶

用于统一文档库的检索、单篇文档读取和目录浏览，支持中文、英文及混合语言查询。

CLI 使用路径¶

数据查询类问题¶

适用于“查询指标、日志、RUM、APM、Network、Profile、Billing 数据”等问题。

1. 先执行 owl.data.show_dql_namespace 确认目标 namespace；

2. 按数据域调用发现类工具：

   • 指标：owl.metric.list
   • RUM：owl.rum.list
   • APM：owl.apm.list
   • Network：owl.network.list
   • Profile：owl.profile.list
   • Logging：owl.logging.list
   • Billing：owl.billing.list
   • 日志索引：owl.log_index.list
   • 字段目录：owl.field_schema.get

3. 需要确认 DQL 语法时，先调用 owl.data.search_dql_docs 查文档；

4. 手写完整 DQL 后，先调用 owl.data.check_dql 做本地校验；
5. 最后调用 owl.data.query 执行正式查询。

Profiling 分析类问题¶

适用于“已拿到 profile_id，希望查看摘要或解析详细栈信息”等问题。

1. 先通过 owl.data.query 在 Profiling 数据域中定位目标 profile_id；
2. 调用 owl.profiling.get_summary 获取摘要信息；
3. 复用摘要结果中的 language、type、profile_start、profile_end，再调用 owl.profiling.parse 解析详细内容。

故障排查类问题¶

适用于“查询故障单、追踪处理过程、补充评论”等问题。

1. 先调用 owl.incident.list 查询故障单；

2. 基于 incident_uuid 继续调用：

   • owl.incident_comment.list 查看评论
   • owl.incident_operation.list 查看操作记录
   • 需要补充处理进展时，调用 owl.incident_comment.add。

仪表板管理类问题¶

适用于“创建仪表板、替换仪表板内容、查看已有仪表板配置”等问题。

1. 创建新仪表板时调用 owl.dashboard.create；
2. 替换已有仪表板时调用 owl.dashboard.replace；
3. 需要查看当前配置时调用 owl.dashboard.get。

笔记与 Runbook 管理类问题¶

适用于“搜索、读取、创建、修改或删除普通笔记与 Runbook”等问题。

1. 先调用 owl.nbook_note.list 搜索内容并取得 note_uuid；需要缩小范围时，通过 type=normal 或 type=runbook 筛选；
2. 需要读取 Markdown 正文时，调用 owl.nbook_note.get；
3. 创建笔记时调用 owl.nbook_note.add，可用 type 创建 normal 或 runbook；更新时调用 owl.nbook_note.modify，已有笔记类型不可修改；
4. 删除时调用 owl.nbook_note.delete，执行写入操作前应确认目标笔记或 Runbook 及其影响范围。

监控器管理类问题¶

适用于“查看监控器、创建监控器、更新监控器、发送测试事件”等问题。

1. 先调用 owl.monitor.list 浏览目标监控器；
2. 需要详情时调用 owl.monitor.get；
3. 创建或更新时调用 owl.monitor.upsert；
4. 需要发送外部事件验证接收链路时调用 owl.monitor.receive。