OWL CLI Tool Inventory¶

This document describes the business tool capabilities that OWL CLI can execute directly, including tool scope, permission types, CLI usage conventions, a tool overview, and categorized tool descriptions.

The visibility and execution results of tools depend on the permissions of the API Key associated with the current OWL_TOKEN. If the API Key lacks the required resource or operation permissions, the corresponding tool may fail to execute or return empty results.

Tool Scope¶

The tools exposed by OWL CLI are continuously updated along with platform capabilities. The actual visible tools are determined by the tool catalog returned by owl list after you run owl sync locally.

This document covers the following business categories:

Permission Types¶

CLI Usage Conventions¶

For authorized cross-workspace queries, when the target has not been determined, call owl.workspace.data_authorized.list first, then pass workspace_uuids and target_region to owl.data.query or owl.data.simple_query_file. Each query is limited to one target site; when scope parameters are omitted, the current workspace is queried. List page numbers and data cursors are handled separately. For details, see Cross-Workspace Query Guide.

Sample Field in Data Result Files¶

When the tool output type is data, the CLI writes the data file and may optionally include a sample field in the execution result:

• sample: a numeric value (float) indicating the sampling ratio of this query (for example, 0.0077 means approximately 0.77% sampling). It appears only when the backend returns sampling information or the sampling ratio can be parsed from the data file contents; when no sampling information is available, this field is omitted.
• When sample is returned, the result is estimated from sampled data. When interpreting aggregations such as counts and sums, restore the values according to the sampling ratio before assessing the magnitude.

Common CLI command examples:

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

Tool Overview¶

Catalog¶

Used for entity type discovery, entity queries, entity detail retrieval, and topology relationship queries in the unified resource catalog.

Dashboard¶

Used for creating, replacing, and retrieving details of dashboards.

Data¶

As of v1.5.0, owl.metric/rum/apm/network/profile/logging/billing.list and owl.infrastructure.list/get require 13-digit millisecond start_time / end_time values, and the time window must not exceed 7 days. The time range for owl.llm.list is optional; when both are omitted, the last 24 hours are used.

The dql_namespace returned by owl.data.show_dql_namespace is a query alias, not the backend raw type name. Pass it to dql_namespace when calling owl.data.query; when calling simple query or log clustering tools, pass the same value as-is to namespace.

Used for full data queries and query assistance, covering logs, metrics, RUM, APM, Network, Profile, Billing, configured external data sources, and data forwarded to object storage.

For external data source queries, first use list to discover the data source by datasource_id or name, then pass the datasource_uuid of the unique result as-is to query. datasource_id cannot replace UUID. Raw row queries must include a deterministic ORDER BY and an SQL LIMIT, and truncated=true only indicates partial results. The statement type must follow the capabilities.statement_types returned by list.

The limit of owl.data.simple_query_file is an optional integer ranging from 1 to 10000; when omitted, the backend uses the default value. Values outside this range are rejected before the request is executed.

Data Forwarding Async Queries¶

owl.data_forwarding.rule.list, owl.data_forwarding.query.create, and owl.data_forwarding.query.get are used to discover queryable rules and query data already written to object storage through those rules. These three tools are single atomic calls; the CLI does not automatically select rules, poll tasks, or continue querying the next batch of data. rule.list and query.create return text results directly; query.get has an outputType of data and writes a new local data file on each status query.

Complete a query in the following order:

1. When the user has not provided an exact rule name, or when it has not yet been confirmed whether a rule is queryable, call owl.data_forwarding.rule.list first. Keep queryable_only=true in query scenarios, select rule_name from results with queryable=true, and do not pass rule_uuid to create.
2. Call owl.data_forwarding.query.create, passing the selected rule_name, query time range, and filter conditions as-is, and obtain the task_id.
3. Use that task_id to call owl.data_forwarding.query.get. The file object in its execution result does not contain the data file ID: run owl data list -f json, find the corresponding entry, save files[].id as-is, and then run owl data show <file-id>. Do not infer or guess the ID from the path.
4. Check task_status in the file. When the value is created or running, the task is not complete yet; even if items is empty, it cannot be treated as the final result. Continue calling get with the same task_id later, then repeat the data file listing steps to view the latest status.
5. Stop polling when task_status is completed or failed. When completed, read the desensitized items; when failed, troubleshoot based on the returned failure information.
6. When completed and next_token is not empty, call create again to query the next batch. Keep the original rule_name, start_time, end_time, search, and page_size, and pass next_token as token. The new create call returns a new task_id.

Discover queryable rules:

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

Create the first batch of query tasks:

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
}'

Query task status and results:

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

When querying the next batch, reuse the original query parameters and pass in 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"
}'

Parameters and limitations:

• rule.list defaults to queryable_only=true and returns only queryable rules. When set to false, rules that do not support querying are also returned; use queryable and unsupported_reason to determine the reason and do not call create to query those rules.
• rule.list supports fuzzy search on rule names via search and filtering by data_type or store_type. Pagination ranges are page_index >= 1 and page_size from 1 to 100.
• rule_name must use the exact value returned by rule.list and cannot be replaced by rule_uuid. The data type and object storage configuration are determined by the backend according to the rule.
• start_time and end_time are 13-digit millisecond timestamps, and end_time must be greater than start_time.
• The query duration limit is determined by the workspace configuration and defaults to 24 hours; query_time_limit_hours in the create response is the currently effective limit.
• search.conditions[].logic supports only match and notMatch; multiple conditions are combined via and or or in search.operator.
• page_size ranges from 1 to 1000 and defaults to 20.
• query.get does not print the full result directly to the CLI, and the file information it returns does not include the ID. Run owl data list -f json, save the files[].id of the corresponding entry as-is, and then view the task status and desensitized results with owl data show <file-id>.
• DF-API-KEY is automatically injected by the CLI and should not be passed as a tool parameter.
• S3, OSS, OBS, GCS, and TOS standard storage are supported; Kafka, platform built-in storage, cold storage, and archived data are not supported.

Cross-Workspace Trace Queries Within the Same Organization¶

owl.data.same_org.trace.query is a dedicated tool for querying a Trace by trace_id in the current workspace or in workspaces of the same organization. Call it directly in the current workspace without listing workspaces. When you need to query other workspaces in the same organization and the UUID has not been determined, run owl workspace same-org list to get candidate workspaces before querying:

• trace_id is a required parameter. The server forcibly adds this condition, so do not add it again in where_clause.
• workspace_uuids is an optional string array; use the workspace_uuid from list results as values. workspace_id is only used for list pagination and cannot be used for querying.
• When workspace_uuids is omitted or an empty array is passed, only the workspace to which the current API Key belongs is queried.
• When the cross-workspace query feature within the same organization is disabled, only the current workspace can be queried; passing UUIDs of other workspaces returns a parameter error.
• where_clause accepts only additional DQL condition fragments and does not include outer curly braces.
• start_time and end_time use 13-digit millisecond timestamps. You can also narrow the query scope with source and limit.
• The returned content preserves the structure of the original DQL query result. Do not fall back to owl.data.query or owl.data.simple_query_file for cross-workspace Trace queries.

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

Errors¶

Used for querying the issue list in the error center, and for adding, querying, and updating comments.

Event¶

Used for event center list queries and event detail retrieval.

• owl.event.list requires start_time and end_time. The valid values for status are fatal, critical, error, warning, and nodata. limit defaults to 20 and has a maximum of 100. Returned items may include the event dimension tag field df_dimension_tags.
• The timeRange of owl.event.get is an optional two-element array [start, end]; both elements are 13-digit millisecond timestamps, and end must be greater than start. The parameter name is timeRange; do not rename it to time_range.

Incident¶

owl.incident.get accepts an incident UUID (incident_*) and returns details along with related_event_refs. Related references default to 100 per page, which is also the maximum. Read subsequent pages using page_info.has_more and next_page_index, then call owl.event.get based on the event references. Do not treat the incident UUID as an event document ID. The total number of references may differ from the total number of events reported by the incident; preserve and explain any missing evidence.

Used for incident list and detail queries, related event references, incident comments, operation records, and on-call schedules.

Infrastructure¶

Used for infrastructure object list and detail queries, covering resource objects such as hosts, containers, and processes.

LLM¶

Used for LLM observability application list queries.

Workspace¶

Used for discovering the authorization scope for cross-workspace data queries, and for querying the current workspace member list and searching by name or email keywords.

owl.member.list is retained as a compatibility alias for explicit invocation and is not listed as a standalone tool. Upgrade the CLI to a version that supports aliases, then run owl sync.

Monitor¶

Used for monitor list queries, detail retrieval, creation or update, and external event receiving.

Notes and Runbooks¶

Used to manage regular notes and Runbooks visible to the current API Key account. Regular notes are suitable for recording conclusions and reference information, while Runbooks are suitable for storing repeatable operational procedures.

• For owl.nbook_note.list, page_index defaults to 1, and page_size defaults to 20 with a maximum of 100.
• The valid values for type in owl.nbook_note.list are normal and runbook; when omitted, both types are returned.
• owl.nbook_note.get is the only tool that returns the Markdown body content, but it does not return path, etag, or version. list, add, and modify return only basic information such as title, type, and tags, and do not return content, path, ETag, or version information. delete returns a concise result of the deletion operation.
• owl.nbook_note.add requires title and content. The valid values for type are normal and runbook; when omitted, a regular note is created. This tool does not accept path. created_source is always set to ai by the server, and the creator account is taken from the current API Key.
• Besides note_uuid, owl.nbook_note.modify requires at least one of title, content, tags, or tag_kv. When content is omitted, the original body is preserved.
• The content type cannot be modified after creation; get, modify, and delete do not accept type. To change the type, create the content again with the target type.
• Get, modify, and delete operations all use the note_uuid returned by list. Do not pass backend-managed fields such as path, etag, if_match, version, creator, or created_source.
• tagkv_query is the TagKV expression string used by the list tool; tag_kv is the key-value object used by the create and modify tools. Do not mix them up.

Pipeline¶

Used for Pipeline list queries and sample validation.

mdsearch¶

Used for searching the unified documentation library, reading a single document, and browsing the catalog. Chinese, English, and mixed-language queries are supported.

CLI Usage Paths¶

Data Query Problems¶

Applies to questions such as "querying metric, log, RUM, APM, Network, Profile, and Billing data".

1. First run owl.data.show_dql_namespace to confirm the target namespace.

2. Then call discovery tools by data domain:

   • Metrics: 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
   • Log indexes: owl.log_index.list
   • Field catalog: owl.field_schema.get

3. When you need to confirm DQL syntax, call owl.data.search_dql_docs first to look up the documentation.

4. After writing a full DQL, call owl.data.check_dql first for local validation.
5. Finally, call owl.data.query to run the formal query.

Profiling Analysis Problems¶

Applies to questions such as "I already have a profile_id and want to view the summary or parse detailed stack information".

1. First locate the target profile_id in the Profiling data domain using owl.data.query.
2. Call owl.profiling.get_summary to get the summary information.
3. Reuse language, type, profile_start, and profile_end from the summary result, then call owl.profiling.parse to parse the detailed contents.

Incident Troubleshooting Problems¶

Applies to questions such as "querying incident tickets, tracking the handling process, and adding comments".

1. When the incident UUID is known, call owl.incident.get; when the target has not been determined, call owl.incident.list first.
2. Read all related event references according to the returned pagination information, then call owl.event.get to get the event content.
3. Use owl.incident_comment.list to view comments and owl.incident_operation.list to view operation records.
4. When you need to add handling progress, call owl.incident_comment.add.

Dashboard Management Problems¶

Applies to questions such as "creating dashboards, replacing dashboard content, and viewing existing dashboard configurations".

1. Call owl.dashboard.create to create a new dashboard.
2. Call owl.dashboard.replace to replace an existing dashboard.
3. Call owl.dashboard.get when you need to view the current configuration.

Note and Runbook Management Problems¶

Applies to questions such as "searching, reading, creating, modifying, or deleting regular notes and Runbooks".

1. First call owl.nbook_note.list to search content and obtain the note_uuid; to narrow the scope, filter with type=normal or type=runbook.
2. Call owl.nbook_note.get when you need to read the Markdown body.
3. Call owl.nbook_note.add to create a note, using type to create normal or runbook. Call owl.nbook_note.modify to update; the type of an existing note cannot be modified.
4. Call owl.nbook_note.delete to delete. Before performing write operations, confirm the target note or Runbook and its scope of impact.

Monitor Management Problems¶

Applies to questions such as "viewing monitors, creating monitors, updating monitors, and sending test events".

1. First call owl.monitor.list to browse the target monitors.
2. Call owl.monitor.get when details are needed.
3. Call owl.monitor.upsert to create or update.
4. Call owl.monitor.receive when you need to send external events to verify the event receiving channel.