bk-cli-monitor

bk-cli monitor — usage and troubleshooting

Before starting, read shared usage rules. This Skill is intended for Agents executing observability tasks; for manual preparation of configuration, see Profile initialization. Resource identifiers must come from a Profile already confirmed by the user or from the catalog visible to the current account; do not guess businesses, tables, index sets, applications, or Trace IDs.

bk-cli monitor is aimed at developers, SREs, and automation scripts, providing a unified query entry point for observability data such as logs, metrics, alerts, and call chains. Users can complete troubleshooting in the terminal, or hand the same commands to scripts or Agents, without writing interface calls separately for each type of data.

It suits three kinds of daily work:

Investigating issues: searching error logs, viewing metric changes, and continuing to query related data from an alert or a single call.
Reusing queries: saving commonly used data sources and query parameters through team-maintained Profiles, reducing repeated lookups of business, index set, and application names.
Integrating with automation: obtaining structured JSON results and explicit failure statuses for inspection scripts, troubleshooting tools, or Agents to process.

Before use, you must have a build that includes monitor , a logged-in data source, and the corresponding resource permissions. Configuration and prechecks do not replace server-side authentication at execution time.

1. Quick start: prefer team Profiles

A Profile is a named observability configuration. The SRE confirms the business, log sources, metric tables, and APM applications in advance, so users only need to choose a name instead of filling in these identifiers manually each time.

Assume the team provides team-profiles.yaml, which contains a Profile named checkout-prod :

# 指定本次终端使用的观测配置文件
export BK_CLI_MONITOR_PROFILE_FILE=./team-profiles.yaml

# 看有哪些配置，再确认目标业务和数据来源
bk-cli monitor profile list
bk-cli monitor profile show --profile checkout-prod

# 查询最近 15 分钟的错误日志，最多返回 20 条
bk-cli monitor log search_logs --profile checkout-prod \
  --query_string 'ERROR OR WARN' --since 15m --limit 20

The file name and Profile name are examples; defer to the team's actual delivery. You can also use --profile_file ./team-profiles.yamlin a single command without setting an environment variable.

On first use or after a configuration update, you can run the following check:

bk-cli monitor profile check --profile checkout-prod

It checks the tool contract, permissions, and resource metadata; it does not read log bodies, nor does it prove that every query expression is valid. Ordinary queries do not need to be preceded by a check each time; when actually executed, the server will still re-authenticate.

What if a business has multiple components or data sources?

A V2 Profile can configure components such as the backend and Worker separately, and point logs, metrics, and Traces to their respective data sources. Metrics of the same kind can also be named as query bindings such as traffic、latency .

# 示例 V2 文件由团队另行提供；先查看 backend 组件的配置
bk-cli monitor profile show --profile_file ./multi-source-profiles.yaml \
  --profile game-production --component backend

# 执行该组件预设的 traffic 指标查询
bk-cli monitor metric execute_range_query \
  --profile_file ./multi-source-profiles.yaml \
  --profile game-production --component backend --binding traffic --since 1h

When there are multiple components, explicitly specify --component; when the same module has multiple bindings, explicitly specify --binding。
If configuration is missing or the selection is ambiguous, it stops and does not automatically switch businesses or data sources.
Profile is not a credential, nor is it authorization. Sharing a configuration file does not mean sharing access permissions, and the credential directory must certainly not be shared.

For the configuration format, templates, and override rules, see Profile usage and delivery。

2. No Profile: find resources first, then query

Commands uniformly adopt the following structure, with logs located under monitor log, not as an independent bk-cli log：

bk-cli monitor <模块> <工具> [参数]

Below, the <业务ID>、<索引集ID> etc. are placeholders; replace them with the actual values visible to the current account before execution. Do not copy the example identifiers directly, and do not let the Agent guess resource IDs.

# 按名称查找业务空间
bk-cli monitor space search_spaces --space_name '<业务名称关键词>'

# 查看该业务的日志索引集
bk-cli monitor log list_index_sets --bk_biz_id '<业务ID>'

# 确认所选索引集有哪些可查询字段
bk-cli monitor log get_index_set_fields \
  --bk_biz_id '<业务ID>' --index_set_id '<索引集ID>'

# 开始检索
bk-cli monitor log search_logs \
  --bk_biz_id '<业务ID>' --index_set_id '<索引集ID>' \
  --query_string 'ERROR OR WARN' --since 15m --limit 20

When multiple candidates appear, choose based on the business name, data source, and collection scope, rather than treating the first item in the list as the default answer. When the correct identifier is already known, you can query it directly without rediscovering the resource every time.

3. Typical troubleshooting scenarios

3.1 Logs: from keyword to context

Logs support retrieval by index set and by configured scenario. Query terms, time range, number of returned entries, and field filtering can all be specified explicitly.

For container logs, distinguish between "which log sources to select" and "which records within the sources to filter":

Parameter	Purpose	Example
`--scene`	Select log scenario	`--scene k8s`; the scenario must be supported by the target service
`--where`	Select data sources by scenario label	`--where 'cluster_id=<集群ID>'`
`--filter`	Filter log lines by field phrase	`--filter '__ext.io_kubernetes_pod_namespace=checkout-prod'`
`--query_string`	Enter keywords or a complex query expression	`--query_string 'ERROR OR WARN'`

The clusters, namespaces, and field names in the table only illustrate the syntax. Actual scenarios and fields should be obtained from list_log_scenes、get_scene_log_fields or get_index_set_fields . Multiple --filter are combined with AND and then combined with the query term; they are not permission isolation rules.

When you need to view the content before and after a matched log entry, first save that record, then query the context:

bk-cli monitor log search_logs \
  --bk_biz_id '<业务ID>' --index_set_id '<索引集ID>' \
  --query_string ERROR --since 15m --limit 1 > hit.json

bk-cli monitor log search_index_set_context \
  --bk_biz_id '<业务ID>' --from hit.json --size 5

hit.json must come from a successful search result with matches, and the original location fields must be retained; simulated records, guessed timestamps, or records from other businesses must not be used as substitutes.--size 5 is the limit on the number of entries per direction, not the total number of returned entries.

Log results may contain business content. When saving files, use an authorized location and do not commit them to code repositories or public documents.

3.2 Metrics: view changes over a period of time

Metrics support PromQL range queries and also provide entry points for metric groups, field catalogs, and SQL queries. They can be used to view changes in error rate, latency, throughput, etc., depending on the metrics already integrated by the business.

# 查看可用的指标组；这不是所有监控数据的总目录
bk-cli monitor metric list_time_series_groups --bk_biz_id '<业务ID>'

# 查看选定指标表的字段
bk-cli monitor metric list_time_series_metrics \
  --bk_biz_id '<业务ID>' --table_id '<指标表ID>'

# 按已确认的表达式查询最近一小时，每分钟一个查询步长
bk-cli monitor metric execute_range_query \
  --bk_biz_id '<业务ID>' --promql '<PromQL表达式>' --since 1h --step 1m

The CLI does not automatically generate or rewrite PromQL based on table names. When a fixed query definition is needed, SRE can maintain named queries in the V2 Profile; the meaning and calculation method of the metrics still need to be confirmed by the business.

3.3 Alerts: continue from alert details to related logs

The alert list and TopN queries are limited to the finally selected business. The alerts returned by the list must belong to the same business; if the ownership is inconsistent or cannot be confirmed, the CLI will refuse to output the results. Subsequent details use the alert IDs returned by that business's list, without automatically switching businesses based on the returned content.

# 最近一小时仍处于异常状态的告警
bk-cli monitor alert list_alerts \
  --bk_biz_id '<业务ID>' --status ABNORMAL --since 1h

# 查看一条告警的详情
bk-cli monitor alert get_alert_info \
  --bk_biz_id '<业务ID>' --id '<告警ID>'

# 获取该告警关联的日志查询目标
bk-cli monitor alert get_alert_log_relations \
  --bk_biz_id '<业务ID>' --alert_id '<告警ID>'

The correlation query returns log targets and index information, not the log body. Continue using log commands and narrow the query range based on the alert occurrence time.

3.4 Call chains: view a complete Trace from a single call

APM (Application Performance Monitoring) provides queries for applications, services, Spans, Traces, and performance profiling. A Span is a record of a single call, and a Trace is a call chain composed of multiple Spans.

# 查看当前业务的 APM 应用
bk-cli monitor apm list_apm_applications --bk_biz_id '<业务ID>'

# 检索某个应用最近 15 分钟的调用记录
bk-cli monitor apm search_spans \
  --bk_biz_id '<业务ID>' --app_name '<应用名称>' --since 15m --limit 20

# 使用查询返回的 trace_id 查看调用链
bk-cli monitor apm get_trace_detail \
  --bk_biz_id '<业务ID>' --app_name '<应用名称>' --trace_id '<Trace ID>'

In-application search is not automatically limited to a specific service. When service-level filtering is needed, use the filter conditions supported by that tool, or use team-validated V2 tool presets; do not assume that all APM tools accept the same service parameter.

4. Time ranges: prefer relative time or readable dates

Common formats:

Input	Meaning
`--since 15m`	Query the 15 minutes before the current execution time
`--since 1h30m`	The last 90 minutes
`--start_time 'yesterday 10:00' --end_time 'yesterday 11:00'`	Yesterday from 10:00 to 11:00
`--start_time today --end_time now`	From today's midnight to the current execution time
With `Z` or `+08:00` RFC3339 time	Absolute time with an explicit timezone offset

For example, query logs for a fixed time period yesterday:

bk-cli monitor log search_logs \
  --bk_biz_id '<业务ID>' --index_set_id '<索引集ID>' \
  --start_time 'yesterday 10:00' --end_time 'yesterday 11:00' --limit 20

Dates without a timezone offset are interpreted by default as Asia/Shanghai (Beijing time) , and can be overridden with names such as --timezone UTC .
--since is mutually exclusive with named start and end times; when --body is provided, the time is based on the body, and--since does not rewrite the body.
--since is at most 24 hours, and a single log window also does not exceed 24 hours; other queries are also constrained by server-side retention periods and query limits.
Bare integers are interpreted in the second or millisecond unit of the specific tool, not guessed by digit count. Date formats are usually easier to verify.
Nested times in resource association batches and log context location fields are not subject to the above automatic conversion rules.

See Query time。

5. Capability scope and command discovery

Currently provides 11 business modules and 65 read-only tools. The table below shows command coverage and does not mean every tool is available in all deployments; actual availability also depends on the service version, data ingestion, and current user permissions.

Module	Tool count	What can be queried
`log`	9	Log scenarios, index sets, fields, logs, context, and clustering results
`metric`	4	Metric groups, fields, PromQL, and SQL queries
`alert`	12	Alerts, details, events, and related observability data
`apm`	11	APM applications, services, Spans, Traces, and profiling
`event`	3	Custom events and log keyword events
`relation`	2	Instant and time-range queries of resource relationships
`space`	2	Business spaces and cluster directories
`dashboard`	2	Dashboard directories and details
`alarm`	8	Alert policies, silences, notification groups, and handling package configurations, read-only view
`collect`	8	Log collection, index set grouping, and cleaning preview, read-only view
`extract`	4	Log extraction scope and task status, without initiating extraction or download

Additionally provides tools、permission、profile and status auxiliary commands, not counted among the above 65 tools.

If you do not know which tool to use, or are unsure about parameters:

# 按业务和类别查看服务端工具目录
bk-cli monitor tools search --bk_biz_id '<业务ID>' --category log

# 从服务端读取某个工具的当前参数契约
bk-cli monitor tools schema --tool search_logs

# 查看本地命令参数、示例和所需权限
bk-cli monitor log search_logs --help

In directory results, command indicates a provided CLI entry point. The server-side directory may contain tools that have not yet been wrapped, and this cannot be used to infer that the CLI supports execution of arbitrary tools.

6. Permissions and issue troubleshooting

Queries are possible only with permission; when permission is missing, provide the next step

# 查看当前用户在业务下的日志权限状态
bk-cli monitor permission list --bk_biz_id '<业务ID>' --module log --missing_only

# 检查具体工具与索引集的权限，不读取日志正文
bk-cli monitor permission check --bk_biz_id '<业务ID>' \
  --tool get_index_set_fields --body '{"index_set_id":<索引集ID>}'

# 获取申请入口，不会自动提交申请
bk-cli monitor permission apply --bk_biz_id '<业务ID>' --tool search_logs \
  --body '{"target_type":"index_set","index_set_id":<索引集ID>}'

The index set ID in the JSON here should be replaced with an integer, without quotes. The above single-tool permission check/apply requires server-side determination and does not support --dry-run。

The CLI will explain which type of permission is missing based on the server-side result and return an available application link. Users open the link themselves to apply; passing the pre-check and obtaining the link do not mean authorization has been granted. The MCP permissions and native permission paths supported by specific tools are subject to their help and the server-side contract.

The legacy business permission API may return only authorized, without state. The CLI is compatible only when the server-side Schema explicitly indicates legacy business permissions, a unique tool, a matching Action and business, and a consistent authorization conclusion; conflicting responses are still rejected. SQL uses BkBase result tables, which can be found from the same business collect list_result_tables --scenario_id bkdata . Do not treat time-series grouped tables as BkBase tables; a passed precheck does not mean the query or platform table ownership validation has passed.

Handle according to the error type, rather than retrying blindly

Hint	What to do
`needs_resource`	Fill in specific resources such as index sets and applications; this does not mean you lack permission
`permission_missing` / `permission_denied`	Check permission diagnostics and server-side application guidance
`resource_not_visible` / `resource_not_found`	Re-check resources from the directories visible to the current account, and contact the maintainer if necessary
`resource_blocked`	Contact the maintainer to verify resource metadata; do not repeatedly apply for more permissions
`profile_context_mismatch` / `profile_business_mismatch`	Profile conflicts with explicit scope; confirm the configuration before querying
`needs_component` / `needs_binding`	Use `profile show` to view the configuration, then choose explicitly
`response_scope_mismatch`	The business ownership of the list is inconsistent with the request or cannot be confirmed; verify the Profile, business selection, and server-side interface
`invalid_response`	The interface response is missing the agreed structure; contact the maintainer to verify the interface contract
`api_not_found`	Verify the stage, gateway frontend path, backend mapping, and service route/version
`response_too_large`	Narrow the query scope or reduce fields; when only discovering event sources, pass `--return_dimensions=false`
`relation_route_unavailable`	The business lacks an available associated storage route; contact the platform administrator to check data ingestion and routing
`retry_later`	The server did not return successfully; do not assert a permission denial based on this, and retain the request ID for troubleshooting
`permission_response_invalid`	The permission response remains inconsistent or the target cannot be determined; stay stopped and do not bypass the precheck
`auth_failed`	Update the login state at the corresponding data source; do not mask the error by switching accounts or sources

Available status to check the current state, or perform an offline check first:

bk-cli monitor status
bk-cli monitor status --offline

Offline checks do not verify whether the login is valid;skipped means not checked, andwarn also does not mean that item passed. An online status check with --profile also checks the resource metadata of that configuration.

7. Result usage and product boundaries

Output is machine-processable. The command returns structured JSON containing a success status and data; errors carry error codes and, where applicable, provide a next-step command. Scripts should check both the exit code and the result, not just whether JSON was output.
Requests can be previewed first. Add --dry-runafter the query command to check the actual business, resources, and time range without sending the query; this does not prove that permissions or the query expression are valid. The preview and execution with now / since take the clock separately; to reproduce precisely, fix both time boundaries.
An empty result is not "no faults". It only means this scope and these conditions matched nothing; the CLI does not automatically expand the time, switch indexes, or switch data sources.
Only read-only entry points are provided. Currently it does not create or modify alert policies, collection configurations, or silence rules, nor does it start tasks or provide file export downloads. Read-only commands also do not mean the user credentials themselves have only read permission.
It does not replace analytical judgment. The CLI provides data and reusable queries and does not guarantee automatic root cause conclusions; metric definitions, filter conditions, and remediation actions still need to be confirmed in the business context.
Migration is not forced. It can be used in parallel with the Observability page and existing MCP entry points; they jointly respect server-side permissions, but this does not mean that login states and configurations of different entry points can be directly interchanged.

It is recommended to start with one clear business scenario, one short time window, and one type of data; after confirming the source and results, then add other observability data or automation processes.

Common request parameters and output

Business commands call the corresponding HTTP API one by one; GET parameters are placed in the query (arrays are sent as repeated keys), and POST parameters are placed in the JSON body.--body Accepts a complete business parameter object,@file or stdin; when --body is provided, it is the request parameters; named parameters,--since、--scene/--where/--filter、--from and other local compositions will not rewrite it; only the Profile fills in missing fields and checks for range conflicts. Pass structured parameters as JSON according to the current command help.

--stage Selects the gateway stage, default prod; context selects the deployment, and the two are independent.
--header can be repeated to support tenant and other header overrides for this request; the same option is also used for intermediate requests in permission and Profile prechecks. See the shared Skill for authentication rules and masking conventions.
--jq Projects the final complete envelope, including the source information of the explicit Profile, and is not executed on intermediate requests. Expression syntax errors fail before the request; projection execution failures preserve the complete original result and return non-zero without resending the query.

bk-cli monitor log search_logs --profile checkout-prod --since 15m \
  --stage testing --header 'X-Example:probe' --jq '.data'

bk-cli monitor log search_logs --profile checkout-prod --since 15m \
  --dry-run --jq '{source:.profile.name,args:.request.body}'

Profile check Validates the resource ultimately resolved by the current tool. Only metadata tools themselves (such as list_time_series_metrics、get_index_set_fields) perform metadata checks; tables or indexes overridden by tool presets are checked according to the overridden values;execute_sql_query uses the BkBase result table and cannot be validated with the time-series grouping interface; the result remains permission_only。permission_only indicates that metadata validation for that resource has not been completed, and it cannot be stated that the resource has been validated or that SQL has been executed.