Owl CLI Tool Inventory¶

This document introduces the business tool capabilities that Owl CLI can directly execute, including tool scope, permission types, CLI usage conventions, tool overview, and tool descriptions categorized by type.

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 permissions for the relevant resources or operations, the corresponding tool may fail to execute or return empty results.

Tool Scope¶

The tools exposed by Owl CLI will be continuously updated along with platform capabilities. The actual visible tools are subject to the tool directory returned by owl list after completing owl sync locally.

The current 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 writes the data file and optionally includes a sample field in the execution result:

• sample: A numeric value (floating point), representing the sampling ratio for this query (e.g., 0.0077 indicates approximately 0.77% sampling). This field only appears when the backend returns sampling information, or when the sampling ratio can be parsed from the data file content; it is omitted when there is no sampling information.
• When sample is present, it means the results are estimated based on sampled data. When interpreting counts, sums, and other aggregates, they need to be scaled back according to the sampling ratio before judging 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 unified resource catalog entity type discovery, entity query, entity detail retrieval, and topology relationship query.

Dashboard¶

Used for dashboard creation, replacement, and detail retrieval.

Data¶

Used for full data query and query assistance, covering data domains such as Log, Metrics, RUM, APM, Network, Profile, Billing, etc.

Cross-Workspace Query Parameter within Same Organization same_org_workspace_uuids¶

Both owl.data.query and owl.data.simple_query_file support the optional parameter same_org_workspace_uuids, used to include other workspaces within the same organization in a single query, commonly seen in scenarios where a trace spans multiple workspaces.

• Type is a string array, elements are workspace_uuid of workspaces.
• Values come from workspace_uuid returned by owl workspace same-org list, do not pass the workspace_id returned by that command.
• Accepts up to 20 workspace UUIDs.
• Do not pass all same-organization spaces by default; final validation of same-organization accessibility is performed by the backend.

Errors¶

Used for Error Center issue list query, and comment addition, query, and update.

Event¶

Used for Event Center list query and event detail retrieval.

Incident¶

Used for incident list, incident comments, operation records, and on-call schedule query.

Infrastructure¶

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

LLM¶

Used for LLM observable application list query.

Member¶

Used for workspace member list query and search by name, email keywords.

Monitor¶

Used for monitor list query, detail retrieval, creation or update, and external event reception.

Pipeline¶

Used for Pipeline list query and sample validation.

mdsearch¶

Used for unified document library search, single document reading, and directory browsing, supporting Chinese, English, and mixed language queries.

CLI Usage Paths¶

Data Query Issues¶

Applicable to issues like "query metrics, logs, RUM, APM, Network, Profile, Billing data", etc.

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

2. 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 needing to confirm DQL syntax, first call owl.data.search_dql_docs to search documentation;

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

Profiling Analysis Issues¶

Applicable to issues like "already have a profile_id, want to view summary or parse detailed stack information", etc.

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 language, type, profile_start, profile_end from the summary result, then call owl.profiling.parse to parse detailed content.

Incident Troubleshooting Issues¶

Applicable to issues like "query incident tickets, track processing progress, add comments", etc.

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

2. Based on incident_uuid, continue calling:

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

Dashboard Management Issues¶

Applicable to issues like "create dashboard, replace dashboard content, view existing dashboard configuration", etc.

1. Call owl.dashboard.create when creating a new dashboard;
2. Call owl.dashboard.replace when replacing an existing dashboard;
3. Call owl.dashboard.get when needing to view current configuration.

Monitor Management Issues¶

Applicable to issues like "view monitors, create monitors, update monitors, send test events", etc.

1. First call owl.monitor.list to browse target monitors;
2. Call owl.monitor.get when details are needed;
3. Call owl.monitor.upsert when creating or updating;
4. Call owl.monitor.receive when needing to send external events to verify the reception pipeline.