OWL CLI Tool List¶

This document describes the business tools currently directly executable by the OWL CLI, including tool scope, permission types, CLI usage conventions, tool overview, and tool descriptions organized by category.

The visibility of tools and their execution results depend on the permissions of the API Key corresponding to the current OWL_TOKEN. If the API Key does not have the appropriate resource or operation permissions, the corresponding tool may fail to execute or return empty results.

Tool Scope¶

The tools exposed by the OWL CLI will be continuously updated as the platform capabilities evolve. The actual visible tools are based on the tool catalog returned by owl list after running owl sync locally.

The current document covers the following business categories:

Permission Types¶

CLI Usage Conventions¶

Sample Field in Data Result Files¶

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

• sample: Numeric value (floating point), indicating the sampling ratio of this query (e.g., 0.0077 means approximately 0.77% sampling). It only appears when the backend returns sampling information or the sampling ratio can be parsed from the data file content; if no sampling information is available, this field is omitted.
• When sample is obtained, it means the result is estimated based on sampled data. When interpreting aggregations such as counts or sums, the sampling ratio needs to be restored first to determine 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 query, entity detail retrieval, and topology relationship query in the unified resource catalog.

Dashboard¶

Used for dashboard creation, replacement, and detail retrieval.

Data¶

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

Data Forwarding Async Query¶

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 forwarded 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 each status query writes a new local data file.

Complete a query in the following order:

1. If the user does not have an exact rule name or it is not confirmed whether the rule is queryable, first call owl.data_forwarding.rule.list. Keep queryable_only=true for the query scenario, and select rule_name from the results with 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 exactly as obtained, and get the task_id.
3. Use that task_id to call owl.data_forwarding.query.get. Its execution file object has no data-file ID: run owl data list -f json, identify the matching record, capture files[].id verbatim, then execute owl data show <file-id>. Do not derive or guess the ID from a path.
4. Check the task_status in the file. When the value is created or running, the task is not yet complete; even if items is empty, it should not be considered the final result. Continue calling get with the same task_id later, then repeat the data-list step to view the latest status.
5. Stop polling when task_status is completed or failed. When completed, read the desensitized items; when failed, investigate based on the returned failure information.
6. When completed and next_token is not empty, call create again to query the next batch. You must keep the original rule_name, start_time, end_time, search, and page_size, and pass next_token as the token. The new create will return 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 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
}'

Query task status and result:

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

To query the next batch, reuse the original query parameters and pass 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, returning only queryable rules. When set to false, it will also return rules that do not support querying; you should determine the reason via queryable and unsupported_reason, and cannot continue calling create to query these rules.
• rule.list supports fuzzy search of rule names via search, and can also be filtered by data_type or store_type; pagination range is page_index >= 1, page_size 1 to 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 maximum query duration is determined by the workspace configuration, defaulting to 24 hours; query_time_limit_hours in the create response is the current effective limit.
• search.conditions[].logic only supports match and notMatch; multiple conditions are combined via search.operator with and or or.
• page_size ranges from 1 to 1000, default 20.
• query.get does not print the full result directly to the CLI. Its returned file information has no ID; run owl data list -f json, capture the matching files[].id verbatim, and use it with owl data show <file-id>.
• DF-API-KEY is automatically injected by the CLI and should not be passed as a tool parameter. Free Plan workspaces do not support this query.
• Supports S3, OSS, OBS, GCS, and TOS standard storage; does not support Kafka, platform built-in storage, cold storage, and archive data.

Cross-Workspace Trace Query within the Same Organization¶

owl.data.same_org.trace.query is a dedicated tool for querying Traces in the current or same-organization workspace by trace_id. When performing a cross-workspace query, first run owl workspace same-org list to get candidate workspaces, then call this tool:

• trace_id is a required parameter; the server will forcibly add this condition, so do not repeat it in where_clause.
• workspace_uuids is an optional string array. Use the workspace_uuid from the list results for values; workspace_id is only used for list pagination and cannot be used for queries.
• When workspace_uuids is omitted or passed as an empty array, only the workspace of the current API Key is queried.
• When the cross-workspace query feature within the same organization is disabled, only the current workspace can be queried; passing other workspace UUIDs will return a parameter error.
• where_clause only passes additional DQL condition fragments, without the outer curly braces.
• start_time, end_time use 13-digit millisecond timestamps; you can also narrow the query scope via source and limit.
• The returned content retains the original DQL query result structure. 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, as well as adding, querying, and updating comments.

Event¶

Used for event center list query and event detail retrieval.

• owl.event.list must provide start_time and end_time; optional status values are fatal, critical, error, warning, and nodata; limit defaults to 20, maximum 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], both elements are 13-digit millisecond timestamps, and end must be greater than start. The parameter name is timeRange, do not change it to time_range.

Incident¶

Used for querying incident lists, incident comments, operation records, and on-call schedules.

Infrastructure¶

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

LLM¶

Used for querying the LLM observability application list.

Member¶

Used for querying the workspace member list and searching by name or email keyword.

Monitor¶

Used for querying the monitor list, retrieving details, creating or updating, and receiving external events.

Notes and Runbooks¶

Used for managing normal notes and Runbooks visible to the current API Key account. Normal notes are suitable for recording conclusions and reference information, while Runbooks are suitable for saving reusable operation procedures.

• page_index of owl.nbook_note.list defaults to 1, page_size defaults to 20, maximum 100.
• type of owl.nbook_note.list has optional values normal and runbook; when omitted, both types are returned.
• owl.nbook_note.get is the only tool that returns Markdown content content, but does not return path, etag, or version; list, add, and modify only return basic information such as title, type, and tags, and do not return content, path, ETag, or version information; delete returns a simplified result of the delete operation.
• owl.nbook_note.add must provide title and content; type has optional values normal and runbook, and when omitted, a normal note is created. This tool does not accept path; created_source is fixed by the server to ai, and the creator account is taken from the current API Key.
• owl.nbook_note.modify must provide at least one of title, content, tags, or tag_kv in addition to note_uuid; when content is omitted, the original content is retained.
• The content type cannot be modified after creation; get, modify, and delete do not accept type. If you need to change the type, recreate it with the target type.
• Get, modify, and delete all use the note_uuid returned by the list. Do not pass fields managed by the backend such as path, etag, if_match, version, creator, or created_source.
• tagkv_query is a TagKV expression string used by the list tool; tag_kv is a key-value object used by the create and modify tools. Do not mix them.

Pipeline¶

Used for Pipeline list query and sample validation.

mdsearch¶

Used for searching the unified document library, reading a single document, and browsing the directory, supporting queries in Chinese, English, and mixed languages.

CLI Usage Paths¶

Data Query Problems¶

Applicable to problems like "querying metrics, logs, RUM, APM, Network, Profile, Billing data".

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

2. Call discovery tools based on the 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 documentation;

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

Profiling Analysis Problems¶

Applicable to problems like "already have the profile_id, want to view the summary or parse 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 summary information;
3. Reuse the language, type, profile_start, profile_end from the summary results, then call owl.profiling.parse to parse the detailed content.

Incident Troubleshooting Problems¶

Applicable to problems like "querying incident tickets, tracking processing progress, adding comments".

1. First call owl.incident.list to query incident tickets;

2. Based on the incident_uuid, continue calling:

   • owl.incident_comment.list to view comments
   • owl.incident_operation.list to view operation records
   • When processing progress needs to be added, call owl.incident_comment.add.

Dashboard Management Problems¶

Applicable to problems like "creating dashboards, replacing dashboard content, 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 to view the current configuration.

Notes and Runbook Management Problems¶

Applicable to problems like "searching, reading, creating, modifying, or deleting normal notes and Runbooks".

1. First call owl.nbook_note.list to search for content and get the note_uuid; when you need to narrow the scope, filter by type=normal or type=runbook;
2. When you need to read the Markdown content, call owl.nbook_note.get;
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 existing note type cannot be modified;
4. Call owl.nbook_note.delete to delete; before executing a write operation, you should confirm the target note or Runbook and its impact scope.

Monitor Management Problems¶

Applicable to problems like "viewing monitors, creating monitors, updating monitors, sending test events".

1. First call owl.monitor.list to browse the target monitors;
2. Call owl.monitor.get for details;
3. Call owl.monitor.upsert to create or update;
4. Call owl.monitor.receive to send an external event to verify the reception chain.