OWL

https://docs.guance.com/owl
Admin
Owl is a unified capability entry point for Guance Cloud, offering Owl CLI and Owl MCP Server...
Tokens:74,905
Snippets:439
Trust Score:8.3
Update:1 day ago
Show doc for...
Tokens:
Raw
### Example: Query metric sources

Source: https://docs.guance.com/owl/cli-reference/

Shows the tool definition and executes the tool with --mode source.

```bash
owl show owl.metric.list
owl exec owl.metric.list --mode source
```

--------------------------------

### Example: Query event list

Source: https://docs.guance.com/owl/cli-reference/

Shows the tool definition and executes the tool with start_time, end_time, and limit parameters.

```bash
owl show owl.event.list
owl exec owl.event.list --start_time 1712505600000 --end_time 1712592000000 --limit 20
```

--------------------------------

### View help for specific OWL CLI commands

Source: https://docs.guance.com/owl/cli-reference/

Use `owl help <command>` to view help for a specific command. Examples include `exec`, `sync`, and `data`.

```bash
owl help exec
owl help sync
owl help data
```

--------------------------------

### Example configuration file for Owl CLI

Source: https://docs.guance.com/owl/cli-reference/

Sample YAML configuration file for the Owl CLI. It sets registry endpoint, authentication token, cache and data directories, sync settings, execution timeouts, and logging. The `registry.request_timeout` controls the total timeout for a single Registry HTTP request in milliseconds; the default 150000 is higher than the 130-second server-side limit for data query tools.

```yaml
registry:
  endpoint: your-owl-endpoint
  insecure_skip_verify: false
  request_timeout: 150000
  sync_interval: 3600

auth:
  token: ""

cache:
  directory: ~/.owl/cache
  ttl: 86400

data:
  directory: ~/.owl/data
  max_age_days: 1

sync:
  parallel: true
  concurrency: 5
  incremental: true

execution:
  default_timeout: 30000
  max_output_size: 10485760

logging:
  level: info
  file: ~/.owl/logs/owl.log
```

--------------------------------

### List data files with owl data list

Source: https://docs.guance.com/owl/cli-reference/

Run `owl data list` to view the list of data files. Use `-f json` to get authoritative file IDs.

```bash
owl data list
```

--------------------------------

### owl.catalog.entity_get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets details of a single entity by its URN.

```APIDOC
## owl.catalog.entity_get

### Description
Gets details of a single entity by its URN.

### Parameters
- **urn** (string) - Required - The URN of the entity.

### Response
Returns the entity details.
```

--------------------------------

### owl.dashboard.get

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

Gets the details of a dashboard by its UUID. This is a read-only operation.

```APIDOC
## owl.dashboard.get

### Description
Gets the details of a dashboard by its UUID.

### Parameters
- **dashboard_uuid** - Required - The UUID of the dashboard.

### Permissions
Read-only
```

--------------------------------

### 写入本地配置文件（owl init 和 owl login）

Source: https://docs.guance.com/owl/quickstart-cli/

使用 owl init 写入 OWL CLI Endpoint，使用 owl login 写入访问令牌。未选择 Profile 时，本地配置写入 ${OWL_DIR}/config.yaml，默认是 ~/.owl/config.yaml。选中 Profile 后，init 和 login 写回所选配置。

```bash
owl init
owl login
```

--------------------------------

### owl.incident.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets an incident by UUID. Used when the incident UUID is known.

```APIDOC
## owl.incident.get

### Description
Gets an incident by UUID.

### Parameters
- **uuid** (string) - Required - UUID of the incident.

### Permissions
Read-only

```

--------------------------------

### View OWL CLI general help

Source: https://docs.guance.com/owl/cli-reference/

Use `owl --help` to display general help information for the OWL CLI.

```bash
owl --help
```

--------------------------------

### owl.logging.cluster_task.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets the result of a log clustering analysis task by task_id.

```APIDOC
## owl.logging.cluster_task.get

### Description
Gets the result of a log clustering analysis task by task_id.

### Parameters
- **task_id** (string) - Required - The ID of the clustering task.

### Response
Returns the clustering analysis result.
```

--------------------------------

### owl.dashboard.get

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

Gets the current configuration of a dashboard. Used for viewing dashboard configuration.

```APIDOC
## owl.dashboard.get

### Description
Gets the current configuration of a dashboard.

### Parameters
- **dashboard_id** (string) - Required - ID of the dashboard.

### Permissions
Read-only

```

--------------------------------

### Windows 离线安装 OWL CLI

Source: https://docs.guance.com/owl/install-owl/

在 Windows 上使用 install.ps1 脚本进行离线安装。需要指定 -LocalPackage、-RegistryEndpoint、-Token 和 -Yes 参数。

```powershell
powershell .\install.ps1 `
  -LocalPackage `
  -RegistryEndpoint "https://owl-api.guance.com" `
  -Token "your-token" `
  -Yes
```

--------------------------------

### owl.monitor.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets monitor details by rule_uuid. Used to view a specific monitor.

```APIDOC
## owl.monitor.get

### Description
Gets monitor details by rule_uuid.

### Parameters
- **rule_uuid** (string) - Required - UUID of the monitor rule.

### Permissions
Read-only

```

--------------------------------

### CLI 跨空间数据查询

Source: https://docs.guance.com/owl/cross-workspace-query/

使用 owl.data.simple_query_file 查询指定空间和站点的数据，时间戳为毫秒。

```bash
owl exec owl.data.simple_query_file -p '{"namespace":"L","source":"nginx","start_time":1772516130000,"end_time":1772516140000,"limit":100,"workspace_uuids":["wksp_b","wksp_c"],"target_region":"cn2"}'
```

--------------------------------

### 初始化与配置命令

Source: https://docs.guance.com/owl/cli-reference/

用于初始化 OWL CLI、登录、查看和设置配置。

```bash
owl init
owl login
owl config show
owl config set registry.endpoint "your-owl-endpoint"
```

--------------------------------

### owl.field_schema.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets field catalog information. Used to discover field schemas.

```APIDOC
## owl.field_schema.get

### Description
Gets field catalog information.

### Parameters
None specified in source.

### Permissions
Read-only

```

--------------------------------

### owl.infrastructure.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets details of an infrastructure object. Used after identifying the object via list.

```APIDOC
## owl.infrastructure.get

### Description
Gets details of an infrastructure object.

### Parameters
- **identifier** (string) - Required - Identifier of the object.

### Permissions
Read-only

```

--------------------------------

### Linux/macOS 离线安装 OWL CLI

Source: https://docs.guance.com/owl/install-owl/

在 Linux 或 macOS 上使用 install.sh 脚本进行离线安装。需要先赋予脚本执行权限，并指定 --local-package、--registry-endpoint、--token 和 --yes 参数。

```bash
chmod +x ./install.sh
./install.sh \
  --local-package \
  --registry-endpoint "https://owl-api.guance.com" \
  --token "your-token" \
  --yes
```

--------------------------------

### owl.catalog.entity_query

Source: https://docs.guance.com/owl/mcp-tools-reference/

Queries a list of entities by entity type. For example, query all host entities.

```APIDOC
## owl.catalog.entity_query

### Description
Queries a list of entities by entity type. For example, query all host entities.

### Parameters
- **entity_type** (string) - Required - The entity type to query.
- **page_size** (integer) - Optional - Number of results per page.
- **page_index** (integer) - Optional - Page index for pagination.

### Response
Returns a list of entities of the specified type.
```

--------------------------------

### 检查安装：owl --help 和 owl config show

Source: https://docs.guance.com/owl/install-owl/

安装完成后，重新打开终端，执行这些命令以确认本地可执行文件和配置文件已就绪。如果命令正常输出帮助信息和当前配置，则安装成功。

```bash
owl --help
owl config show
```

--------------------------------

### 新增和切换 Profile 的命令

Source: https://docs.guance.com/owl/profiles/

使用 `owl profile add` 交互输入 Endpoint、API Key 和可选空间信息，`--from` 复制已有配置。`owl switch` 切换默认 Profile，`owl profile current` 查看当前选择。新增 Profile 只保存配置，不切换当前选择；同名会报错。

```bash
# 交互输入 Endpoint、API Key，以及可选的空间 UUID 和名称
owl profile add customer-a

# 复制已有配置；后续修改不会影响源文件
owl profile add customer-b --from ./customer-b.yaml

owl profile list
owl switch customer-a
owl profile current
owl exec owl.metric.list --mode source
```

--------------------------------

### owl.data.search_dql_docs

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

Searches locally synchronized DQL documentation and example snippets. This is a local helper operation.

```APIDOC
## owl.data.search_dql_docs

### Description
Searches locally synchronized DQL documentation and example snippets. This is a local helper operation.

### Method
CLI tool

### Endpoint
owl.data.search_dql_docs

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query.
- **refresh_docs** (boolean) - Optional - Whether to refresh the local docs.
- **limit** (integer) - Optional - Maximum number of results.

### Response
#### Success Response
- **results** (array) - List of matching documentation snippets.

#### Response Example
```json
{
  "results": [
    {
      "title": "percentile",
      "snippet": "..."
    }
  ]
}
```
```

--------------------------------

### same-org 工作空间列表命令

Source: https://docs.guance.com/owl/cli-reference/

列出同组织的工作空间，支持分页、过滤和自动翻页。

```bash
owl workspace same-org list
owl workspace same-org list --page-size 50
owl workspace same-org list --before-id 12345
owl workspace same-org list --uuid wksp_xxx --uuid wksp_yyy
owl workspace same-org list --all
```

--------------------------------

### owl.dashboard.create

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

Creates a dashboard. For example, create a dashboard named 'APM Overview'. This is a write operation.

```APIDOC
## owl.dashboard.create

### Description
Creates a dashboard.

### Parameters
- **name** - Required - The name of the dashboard.
- **dashboard_json** - Required - The dashboard configuration in JSON format.

### Permissions
Write
```

--------------------------------

### owl.event.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets event content by event reference. Used to retrieve event details after listing incident events.

```APIDOC
## owl.event.get

### Description
Gets event content by event reference.

### Parameters
- **event_id** (string) - Required - ID of the event.

### Permissions
Read-only

```

--------------------------------

### 执行工具（owl exec）

Source: https://docs.guance.com/owl/quickstart-cli/

执行 owl.data.show_dql_namespace 命令，查看当前工作空间支持的 DQL 命名空间。这是使用 owl.data.query 前的第一步。

```bash
owl exec owl.data.show_dql_namespace
```

--------------------------------

### 独立文件与旧配置的目录结构

Source: https://docs.guance.com/owl/profiles/

默认存储在 `~/.owl`，设置 `OWL_DIR` 时跟随该目录。`state.yaml` 记录别名、稳定的目录标识及当前默认，不包含 Key。

```text
~/.owl/
├── config.yaml
├── state.yaml
└── profiles/
    └── profile-<id>/
        ├── config.yaml
        ├── cache/
        ├── data/
        └── logs/
```

--------------------------------

### 升级与同步工具目录

Source: https://docs.guance.com/owl/cross-workspace-query/

升级 CLI 至 v1.4.0 后执行全量同步，并列出 workspace 分类工具。

```bash
owl sync
owl tool list --category workspace
```

--------------------------------

### Verification question: list available metric sources

Source: https://docs.guance.com/owl/mcp-quickstart/

Ask this question in an MCP client after configuring OWL MCP Server. In facade mode, the client should discover list_catalogs, list_tools, and exec_tool, and can call owl.metric.list via exec_tool; in static mode, the client directly discovers owl.metric.list and other business tools. If the server has an exclusion list configured, some tools will not appear.

```text
列出当前可用的指标 source。
```

--------------------------------

### 使用环境变量配置 Endpoint 和访问令牌（bash/zsh）

Source: https://docs.guance.com/owl/quickstart-cli/

在 bash 或 zsh 终端中设置环境变量 OWL_REGISTRY_ENDPOINT 和 OWL_TOKEN。环境变量只在当前终端会话中生效，关闭终端后需重新设置。OWL_REGISTRY_ENDPOINT 只填写 Endpoint 根地址，不要拼接 /api/v1 或其他路径。

```bash
export OWL_REGISTRY_ENDPOINT="your-owl-endpoint"
export OWL_TOKEN="your-token"
```

--------------------------------

### Sync tools and list available tools

Source: https://docs.guance.com/owl/troubleshooting/

Run `owl sync` to refresh the local tool cache, then `owl list` to display available tools. This resolves 'tool not found' errors caused by missing cache or incorrect tool names.

```bash
owl sync
owl list
```

--------------------------------

### 创建首批查询任务：owl exec owl.data_forwarding.query.create

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

调用此命令创建数据转发查询任务，需原样传入选中的 rule_name、查询时间范围和过滤条件，取得 task_id。start_time 和 end_time 为 13 位毫秒时间戳，end_time 必须大于 start_time。

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

--------------------------------

### 取消 OWL_PROFILE 后切换

Source: https://docs.guance.com/owl/profiles/

如果设置了 `OWL_PROFILE`，必须先取消它才能执行 `owl switch`；`switch` 也不接受 `--profile` 或 `--conf`。

```bash
unset OWL_PROFILE
owl switch customer-b
```

--------------------------------

### Profile 管理命令

Source: https://docs.guance.com/owl/cli-reference/

用于添加、列出、切换和查看 Profile，支持从文件导入配置。

```bash
owl profile add customer-a
owl profile add customer-b --from ./customer-b.yaml
owl profile list
owl switch customer-a
owl --profile customer-b exec owl.data.show_dql_namespace
owl profile current -f json
```

--------------------------------

### 验证连通性：owl sync

Source: https://docs.guance.com/owl/install-owl/

执行 owl sync 以验证当前终端与 OWL CLI Endpoint 的连通性。如果命令正常完成，说明可以访问 Endpoint 且 OWL_TOKEN 可用于同步工具目录。若返回认证、权限或网络错误，请参考故障排查文档。

```bash
owl sync
```

--------------------------------

### 查询下一批数据：复用参数并传入 next_token

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

当 task_status 为 completed 且 next_token 非空时，再次调用 create 查询下一批。必须保留原来的 rule_name、start_time、end_time、search 和 page_size，并将 next_token 作为 token 传入。

```bash
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"
}'
```

--------------------------------

### View data file statistics with owl data stats

Source: https://docs.guance.com/owl/cli-reference/

Run `owl data stats` to view statistics about data files.

```bash
owl data stats
```

--------------------------------

### Show tool definition with owl show

Source: https://docs.guance.com/owl/troubleshooting/

Displays the definition of a tool, including its required parameters. Use this to resolve 'missing required parameter' errors by identifying and supplying the missing parameters.

```bash
owl show <工具名>
```

--------------------------------

### 临时选择和脚本使用

Source: https://docs.guance.com/owl/profiles/

使用 `--profile` 或 `OWL_PROFILE` 临时选择 Profile，不会修改持久化默认。选择顺序为 `--profile` > `OWL_PROFILE` > `owl switch` 保存的默认。`-f json` 输出可直接解析。

```bash
owl --profile customer-b exec owl.metric.list --mode source
OWL_PROFILE=customer-b owl exec owl.metric.list --mode source

owl profile list -f json
owl --profile customer-b profile current -f json
```

--------------------------------

### 常用 CLI 命令示例

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

展示 OWL CLI 的常用命令，包括同步工具目录、列出工具、按分类浏览、查看工具定义以及执行数据查询和事件查询。这些命令是使用 OWL CLI 的基础操作。

```bash
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
```
Tokens:
Raw