OWL CLI Tool Catalog¶

This document describes the business tool capabilities currently available for direct execution via OWL CLI, including the tool scope, permission types, CLI usage conventions, a tool overview, and tool descriptions organized by category.

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 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 as the platform capabilities evolve. The actual visible tools are 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¶

Sampling Field in Data Result Files¶

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

• sample: A numeric (float) value indicating the sampling ratio for this query (e.g., 0.0077 means approximately 0.77% sampling). This field appears only 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 present, it means the result is estimated based on sampled data. When interpreting aggregated results such as counts or sums, you need to scale back by 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 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 complete 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 from 1 to 10000. When omitted, the backend applies its default. Values outside this range are rejected before execution.

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 via 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 outputType of data, and each status query writes a new local data file.

Complete a single query using the following steps:

1. If the user does not have an exact rule name, or the rule's queryability is not yet confirmed, first call owl.data_forwarding.rule.list. Keep queryable_only=true for the query scenario, and select a rule_name from the 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 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 the files[].id as-is, then run owl data show <file-id>. Do not derive or guess the ID from the path.
4. Check the task_status in the file. If the value is created or running, the task is not yet complete. Even if items is empty, it should not be treated as a final result. Retry using the same task_id with get later, then repeat the data file list step to view the latest status.
5. Stop polling when task_status is completed or failed. When completed, read the masked 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 the token parameter. The new create call 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 results:

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

When querying the next batch, reuse the original query parameters and pass the 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. If set to false, it will also return rules that do not support queries. You should check queryable and unsupported_reason to determine the reason; you cannot proceed to call create to query these rules.
• rule.list supports fuzzy search on rule names via search, and can also be filtered by data_type or store_type. Pagination range: page_index >= 1, page_size 1 to 100.
• rule_name must be the exact value returned by rule.list; it 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. The query_time_limit_hours in the create response is the currently effective limit.
• search.conditions[].logic only supports match and notMatch. Multiple conditions are combined using search.operator with and or or.
• page_size range is 1 to 1000, default is 20.
• query.get does not print the full result directly to the CLI. The returned file information does not contain 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 masked results.
• The DF-API-KEY is automatically injected by the CLI and should not be passed as a tool parameter. This query is not supported for Free Plan workspaces.
• Supported storage types: S3, OSS, OBS, GCS, and TOS standard storage. Kafka, platform built-in storage, cold storage, and archive data are not supported.

Cross-Workspace Trace Query within the Same Organization¶

owl.data.same_org.trace.query is a dedicated tool for querying a trace by trace_id in the current or same-organization workspace. When querying across workspaces, 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 include this condition; do not add it again in where_clause.
• workspace_uuids is an optional string array. Use the workspace_uuid from the list results as values. workspace_id is only used for list pagination and cannot be used for queries.
• If workspace_uuids is omitted or 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 UUIDs of other workspaces will return a parameter error.
• where_clause should only contain additional DQL condition fragments, without outer curly braces.
• start_time and end_time use 13-digit millisecond timestamps. You can also narrow the query scope using 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 tracking issue list, as well as adding, querying, and updating comments.

Event¶

Used for event center list query and event detail retrieval.

• owl.event.list requires start_time and end_time. The status optional values are fatal, critical, error, warning, and nodata. The default value of limit is 20, maximum is 100. The returned items may include the event dimension tag field df_dimension_tags.
• timeRange in 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 the incident list, incident comments, operation records, and on-call schedules.

Infrastructure¶

Used for querying the infrastructure object list and details, covering resources 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, getting details, creating or updating monitors, and receiving external events.

Notes and Runbooks¶

Used for managing notes and Runbooks visible to the current API Key account. Notes are suitable for recording conclusions and reference information, while Runbooks are suitable for storing reusable operational procedures.

• The default value of page_index in owl.nbook_note.list is 1, the default value of page_size is 20, maximum is 100.
• The type optional values in owl.nbook_note.list are normal and runbook. If omitted, both types are returned.
• owl.nbook_note.get is the only tool that returns the Markdown body 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 concise result of the deletion operation.
• owl.nbook_note.add requires title and content. The type optional values are normal and runbook. If omitted, a note is created. This tool does not accept path. The created_source is fixed to ai by the server, and the creator account is taken from the current API Key.
• owl.nbook_note.modify requires at least note_uuid and one of title, content, tags, or tag_kv. If content is omitted, the original body is preserved.
• 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.
• All retrieval, modification, and deletion 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 catalog. Supports queries in Chinese, English, and mixed languages.

CLI Usage Paths¶

Data Query Issues¶

Suitable for problems like "Query metrics, logs, RUM, APM, Network, Profile, Billing data".

1. First, run 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 Index: owl.log_index.list
   • Field Catalog: owl.field_schema.get

3. If DQL syntax needs to be confirmed, first call owl.data.search_dql_docs to look up documentation.

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

Profiling Analysis Issues¶

Suitable for problems like "Already have a profile_id, 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 summary information.
3. Reuse the language, type, profile_start, profile_end from the summary result, then call owl.profiling.parse to parse the detailed content.

Incident Troubleshooting Issues¶

Suitable for problems like "Query incidents, track processing progress, add comments".

1. First, call owl.incident.list to query incidents.

2. Based on the incident_uuid, continue calling:

   • owl.incident_comment.list to view comments
   • owl.incident_operation.list to view operation records
   • If you need to add processing progress updates, call owl.incident_comment.add.

Dashboard Management Issues¶

Suitable for problems like "Create a dashboard, replace dashboard content, view existing dashboard configuration".

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 Issues¶

Suitable for problems like "Search, read, create, modify, or delete notes and Runbooks".

1. First, call owl.nbook_note.list to search for content and obtain the note_uuid. To narrow the scope, filter by type=normal or type=runbook.
2. If you need to read the Markdown body, call owl.nbook_note.get.
3. Call owl.nbook_note.add to create a note, using the type parameter to create a normal or runbook type. Call owl.nbook_note.modify for updates. Note that 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 impact scope.

Monitor Management Issues¶

Suitable for problems like "View monitors, create monitors, update monitors, send test events".

1. First, call owl.monitor.list to browse the target monitors.
2. If details are needed, call owl.monitor.get.
3. Call owl.monitor.upsert to create or update.
4. If you need to send an external event to verify the reception pipeline, call owl.monitor.receive.