OWL CLI Tool Inventory¶

This document describes the business tool capabilities that can be executed directly with the current OWL CLI, covering 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 corresponding to the current OWL_TOKEN. If the API Key lacks permission for the relevant resource or operation, the corresponding tool may fail or return empty results.

Tool Scope¶

The tools exposed by the OWL CLI evolve continuously with platform capabilities. The actual set of visible tools is determined by the tool catalog returned by owl list after running owl sync locally.

This document covers the following business categories:

Permission Types¶

CLI Usage Conventions¶

For authorized cross-workspace queries, when the target workspace is not yet determined, first call owl.workspace.data_authorized.list, 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; omitting the scope parameters queries the current workspace. List page numbers and data cursors are handled separately. See the Cross-Workspace Query Reference for details.

Sampling Field in Data Result Files¶

When the tool output type is data, the CLI optionally includes a sample field in the execution result while writing the data file:

• sample: a numeric value (floating point) indicating the sampling ratio of the 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 present, the results are estimated from sampled data. When interpreting aggregations such as counts or sums, restore the values by the sampling ratio before assessing magnitude.

Example CLI Commands:

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 Catalog.

Dashboard¶

Used for creating, replacing, and retrieving dashboards.

Data¶

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

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

Asynchronous Data Forwarding 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 that has been written to object storage through a rule. These three tools are single atomic calls; the CLI does not automatically select a rule, poll a task, or continue querying the next batch. rule.list and query.create return text results directly; query.get has an outputType of data, and every status query writes a new local data file.

Complete a query in the following order:

1. When the user has not provided an exact rule name, or it is not yet confirmed whether a rule is queryable, first call owl.data_forwarding.rule.list. In query scenarios, keep queryable_only=true, and select rule_name from results where queryable=true; 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 this task_id to call owl.data_forwarding.query.get. The file object in its execution result does not include the data file ID: run owl data list -f json, find the corresponding entry, save files[].id as-is, then run owl data show <file-id>. Do not derive 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 yet complete; even if items is empty, it cannot be treated as the final result. Continue calling get later with the same task_id, then repeat the data file listing step 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 unchanged, and pass next_token as token. The new create returns a new task_id.

Discovering queryable rules:

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

Creating the first batch query task:

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

Querying task status and results:

owl exec owl.data_forwarding.query.get -p '{"task_id":"task_xxx"}'
owl data list -f json
owl data show <file-id>

To query 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. Determine the reason via queryable and unsupported_reason; do not continue calling create to query these rules.
• rule.list supports fuzzy search of rule names via search, and filtering by data_type or store_type; pagination is limited to page_index >= 1 and page_size between 1 and 100.
• rule_name must use the exact value returned by rule.list and cannot be replaced with rule_uuid. The data type and object storage configuration are determined by the backend based on 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, with a default of 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, with a default of 20.
• query.get does not print the full result directly to the CLI, and its returned file information does not include the ID; run owl data list -f json, save the files[].id of the corresponding entry as-is, then use owl data show <file-id> to view the task status and desensitized results.
• DF-API-KEY is automatically injected by the CLI and should not be passed as a tool parameter. This query is not supported in Free Plan workspaces.
• S3, OSS, OBS, GCS, and TOS standard storage are supported; Kafka, platform built-in storage, cold storage, and archived data are not supported.

Same-Organization Cross-Workspace Trace Queries¶

owl.data.same_org.trace.query is a dedicated tool for querying Traces in the current workspace or workspaces within the same organization by trace_id. Call it directly for the current workspace without listing workspaces; when you need to query another workspace in the same organization and its UUID is not yet determined, run owl workspace same-org list to obtain candidate workspaces, then query:

• trace_id is a required parameter; the server enforces this condition, so do not add it again in where_clause.
• workspace_uuids is an optional array of strings; use the workspace_uuid values from the list results. workspace_id is used only for list pagination and cannot be used for queries.
• When workspace_uuids is omitted or passed as an empty array, only the workspace to which the current API Key belongs is queried.
• When the same-organization cross-workspace query feature is disabled, only the current workspace can be queried; passing the UUID of another workspace returns a parameter error.
• where_clause accepts only an additional DQL condition fragment, not including the outer braces.
• start_time and end_time use 13-digit millisecond timestamps; source and limit can also be used to narrow the query scope.
• The returned content retains the structure of the original DQL query results. 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 Error Center issue list, 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; status accepts fatal, critical, error, warning, and nodata; limit defaults to 20 with a maximum of 100. Returned items may include the event dimension tag field df_dimension_tags.
• timeRange of owl.event.get is an optional two-element array [start, end], where 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, with a maximum of 100; read subsequent pages via page_info.has_more and next_page_index, then call owl.event.get for each event reference. 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 in the incident; preserve and explain the evidence of any discrepancies.

Used for incident list and details, related event references, incident comments, operation logs, and on-call schedule queries.

Infrastructure¶

Used for listing infrastructure objects and querying details, covering resource objects such as hosts, containers, and processes.

LLM¶

Used for querying the list of LLM observability applications.

Workspace¶

Used for discovering the authorization scope of cross-workspace data queries, and for querying the current workspace member list with keyword search by name or email.

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 updating, and external event reception.

Notes and Runbooks¶

Used to manage the 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 operating procedures.

• page_index of owl.nbook_note.list defaults to 1; page_size defaults to 20 with a maximum of 100.
• type of owl.nbook_note.list accepts normal and runbook; when omitted, both types are returned.
• owl.nbook_note.get is the only tool that returns the Markdown 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 minimal result of the deletion operation.
• owl.nbook_note.add requires title and content; type accepts normal and runbook, and a regular note is created when omitted. 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.
• In addition to 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 retained.
• The content type cannot be changed after creation; get, modify, and delete do not accept type. To change the type, recreate the content with the target type.
• Retrieval, modification, and deletion all use the note_uuid returned by the 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. Supports queries in Chinese, English, and mixed languages.

CLI Usage Workflows¶

Data Query Tasks¶

For tasks such as "query metric, log, RUM, APM, Network, Profile, or Billing data".

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

2. Call the discovery tool 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 DQL syntax needs to be confirmed, first call owl.data.search_dql_docs to look up the documentation;

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

Profiling Analysis Tasks¶

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

1. First locate the target profile_id in the Profiling data domain via 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 results, then call owl.profiling.parse to parse the detailed contents.

Incident Troubleshooting Tasks¶

For tasks such as "query incident tickets, track handling progress, or add comments".

1. Call owl.incident.get when the incident UUID is known; when the target is not yet determined, first call owl.incident.list.
2. Read all related event references based on the returned pagination information, then call owl.event.get to get the event contents.
3. Use owl.incident_comment.list to view comments and owl.incident_operation.list to view operation logs.
4. When a progress update is needed, call owl.incident_comment.add.

Dashboard Management Tasks¶

For tasks such as "create a dashboard, replace dashboard contents, or view the configuration of an existing dashboard".

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 to view the current configuration.

Note and Runbook Management Tasks¶

For tasks such as "search, read, create, modify, or delete regular notes and Runbooks".

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

Monitor Management Tasks¶

For tasks such as "view a monitor, create a monitor, update a monitor, or send a test event".

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 an external event needs to be sent to verify the receiving path.