OWL CLI 工具清单¶

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

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

v1.8.0 新增字段搜索、分页和笔记 expected_etag。完整参数以当前工具 schema 为准；升级顺序与写入恢复规则见 v1.8.0 更新说明。

工具范围¶

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

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

权限类型¶

CLI 使用约定¶

授权跨空间查询在目标未确定时，先调用 owl.workspace.data_authorized.list，再将 workspace_uuids 和 target_region 传给 owl.data.query 或 owl.data.simple_query_file。一次查询限制在一个目标站点内，省略范围参数时查询当前空间。列表页码与数据游标分别处理，详见跨空间查询说明。

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

当工具输出类型为 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 --start_time 1792548000000 --end_time 1792551600000
owl exec owl.event.list --start_time 1712505600000 --end_time 1712592000000 --limit 20

工具总览¶

Account¶

v1.6.0 起可通过 owl exec owl.account.workspace.same_org.list 调用，与 owl workspace same-org list 和 MCP 共享列表契约。结果包含 items 和 page_info；page_size 默认 20，范围 1–100。下一页原样传入 next_before_workspace_id 作为正整数 before_workspace_id，不要从数组索引推导。workspace_uuids 可过滤结果，空数组表示不过滤。仅将返回的 workspace_uuid 用于同组织 Trace 查询，该列表不建立普通数据查询授权。

owl exec owl.account.workspace.same_org.list -p '{"page_size":20}'

Catalog¶

统一目录实体创建与修改

用于统一目录的实体类型发现、实体查询、创建、修改和拓扑关系查询。创建、修改实体时，所用 API Key 需具有目录管理权限。

entity_query 必须指定 entity_type。name 用于精确匹配，search 用于模糊搜索名称、展示名或 URN，两者不能同时使用；也可以通过完整 urn 或 filters 缩小范围。

创建和修改实体¶

1. 调用 owl.catalog.entity_type_query，确认可用类型及该类型的字段要求；需要设置所属团队时，先用 owl.workspace.member.group_list 查找团队名称。
2. 调用 owl.catalog.entity_query 查找目标，避免重复创建。修改已有实体时，使用查询返回的完整 urn，并通过 owl.catalog.entity_get 核对当前配置。
3. 核对要写入的内容后，调用 owl.catalog.entity_create 或 owl.catalog.entity_modify，完成后可返回平台的统一目录查看实体。

创建必须提供 request_id、entity_type 和 name，并按类型要求补齐 attributes。修改必须提供 request_id 和 urn，同时至少指定一项要修改的内容。request_id 使用一个 UUID 标识本次操作；display_name 为展示名，修改工具不支持更改实体名称或类型。未提交的属性和关系会保留，所属团队 owner 使用团队名称。

修改依赖、组件等关系时，为提交的关系字段设置 relation_modes：add 表示追加，replace 表示整体替换；replace 配合空数组表示清空。仅提交实体类型支持的字段和关系。

结果提示待确认时，请保留原 request_id 和参数，按返回提示核对，不要更换 UUID 重复创建或修改；结果提示审计状态不确定时，应先联系管理员核查。

owl sync
owl show owl.catalog.entity_create
owl show owl.catalog.entity_modify
owl exec owl.catalog.entity_query -p '{"entity_type":"service","name":"checkout-api"}'

Dashboard¶

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

Data¶

v1.6.0 统一校验 13 位整数毫秒时间戳，要求结束时间大于开始时间。需要成对提供的参数不能只传一端；必填要求与最大跨度以各工具 schema 为准。owl.data.query 的时间范围最长为 7 天。

owl.data.query 的 DQL 可以省略内联时间窗口，由 start_time / end_time 提供查询窗口。内联绝对窗口必须与外部窗口一致，相对窗口会被拒绝。PromQL 范围选择器表示回看时长，不作为查询窗口，也不进入 DQL 校验。Registry 需要可用的 dqlcheck；校验不可用时不会执行 DQL 查询。请求窗口不等同于后端实际执行或结果覆盖的时间范围。

v1.5.0 起，owl.metric/rum/apm/network/profile/logging/billing.list 和 owl.infrastructure.list/get 必须传入 13 位毫秒级 start_time / end_time，时间窗口不得超过 7 天。owl.llm.list 的时间范围可选；两者都省略时使用最近 24 小时。

owl.data.show_dql_namespace 返回的 dql_namespace 是查询别名，不是后端原始类型名。调用 owl.data.query 时传给 dql_namespace；调用 simple query 或日志聚类工具时，将同一值原样传给 namespace。

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

外部数据源查询应先用 list 按 datasource_id 或名称发现数据源，再把唯一结果的 datasource_uuid 原样传给 query。datasource_id 不能代替 UUID；原始行查询应带确定性的 ORDER BY 和 SQL LIMIT，且 truncated=true 只代表部分结果。语句类型必须以 list 返回的 capabilities.statement_types 为准。

owl.data.simple_query_file 的 limit 为可选整数，取值范围是 1 到 10000；省略时由后端使用默认值。超出范围的值会在请求执行前被拒绝。

数据转发异步查询¶

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 的专用工具。本空间直接调用，不列空间；需要查询其他同组织空间且 UUID 未确定时，运行 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。

事件 ID 与链接解析¶

owl.event.get 的 doc_id 不能为空或全为空白，使用 owl.event.list 返回的 data.items[].doc_id 原值。事件 ID、故障 ID、兼容的不透明 ID 或 HTTP(S) 事件链接可交给 owl.event.resolve。链接仅用于提取标识和时间，不会被访问，不会切换空间或凭据；链接时间与显式 timeRange 必须一致。

文档 ID 和不透明 ID 先尝试直接读取详情；仅识别到空结果时才继续搜索，事件或故障 ID 直接进入精确标识搜索。搜索省略时间时使用最近 7 天，显式搜索范围最多 7 天，最多返回 20 条候选。直接详情读取不受 7 天上限限制；过长范围下详情为空时会停止，不会缩窄搜索范围。检查 resolution_status、candidates 和 may_have_more；multiple_matches 表示仍有歧义，附带的最新候选详情不能作为唯一解析结果。

owl exec owl.event.resolve -p '{"doc_id":"event-example","timeRange":[1792548000000,1792551600000]}'

Incident¶

owl.incident.get 接受故障 UUID（incident_*），返回详情及 related_event_refs。关联引用每页默认及上限 100，按 page_info.has_more 和 next_page_index 读取后续页，再根据事件引用调用 owl.event.get；不要将故障 UUID 当作事件文档 ID。引用总数与故障报告的事件总数可能不同，应保留并说明缺失的证据。

用于故障列表与详情、关联事件引用、故障评论、操作记录和值班排班查询。

Infrastructure¶

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

owl.infrastructure.list 的 limit 默认 20，范围 1–100。每条 filters 必须包含 field、op、value，op 仅支持 =、!=、in。in 的值必须为非空数组；其余操作符使用非 null 的字符串、数字或布尔值。值按 JSON 传递，不要预先拼接或转义成 DQL。

LLM¶

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

Workspace¶

用于跨空间数据查询授权范围发现，以及当前空间成员和团队查询。成员支持按姓名、邮箱关键字检索，团队支持按名称关键字检索。

owl.member.list 保留为显式调用的兼容别名，不作为独立工具列出；CLI 需升级到支持别名的版本后执行 owl sync。

owl.workspace.member.group_list 不传 search 时返回全部可见团队，不分页；免费版工作空间不支持此工具。owl.member.group_list 为兼容别名。

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. 已知故障 UUID 时调用 owl.incident.get；目标未确定时先调用 owl.incident.list。
2. 按返回的分页信息读取全部关联事件引用，再调用 owl.event.get 获取事件内容。
3. 使用 owl.incident_comment.list 查看评论、owl.incident_operation.list 查看操作记录。
4. 需要补充处理进展时，调用 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。

DQL 文档搜索与正文读取¶

owl.data.search_dql_docs 在 Registry 服务端执行，返回 results 中的片段、document_id、version 和 read_reference。references_dir 是兼容保留的服务端诊断路径，不是 Agent 本地目录，不要交给 read_file、cat 或 grep。

owl exec owl.data.search_dql_docs -p '{"query":"BY host","limit":1}' -f json

把所选结果的 read_reference.arguments 原样作为 JSON 参数传给 read_reference.tool；CLI 可使用 owl exec owl.data.read_dql_docs --stdin -f json。不要从服务器路径自行构造 document_id。搜索和读取工具返回的 .output 是 JSON 文本，本身没有内层 success 字段。

读取参数为 document_id、返回的 version、start_line（从 1 开始）及 line_count（默认 80，最多 200）。正文位于 content，每页最多 65536 个 UTF-8 字节。需要后续内容且 has_more=true 时，保持相同 ID/version，将 start_line 设为 next_start_line，直到所需章节完整或 has_more=false。这里按行分页，不使用文件读取的 next_offset。

遇到 document.version_changed 时重新搜索并使用新引用，不省略 version 绕过校验，也不混合不同版本的页面。空 results 仅表示没有匹配片段。工具拒绝路径越界、符号链接、非 Markdown 或非 UTF-8 文件、超过 4 MiB 的文档及超过 65536 字节的单行。该能力属于 CLI 文档辅助工具，不保证在所有 MCP 暴露模式中可见。