bk-cli monitor 是蓝鲸（BlueKing）观测数据的命令行查询工具，面向研发、SRE 和自动化脚本，提供日志、指标、告警、调用链等观测数据的统一查询入口。用户可在终端完成排查，也可把同样的命令交给脚本或 Agent 使用，无需为每种数据分别编写接口调用。使用前须具备包含 monitor 的构建、已登录的数据来源及对应资源权限；配置和预检不替代执行时的服务端鉴权。
一、主要用途
- 查问题：检索错误日志、查看指标变化，从告警或单次调用继续查相关数据。
- 复用查询：通过团队维护的 Profile 保存常用数据来源与查询参数，减少反复查找业务、索引集与应用名称。
- 接入自动化：取得结构化 JSON 结果和明确的失败状态，供巡检脚本、排障工具或 Agent 处理。
二、Profile 配置 Profile 是一份有名字的观测配置，SRE 可提前确认业务、日志来源、指标表和 APM 应用，使用者选择名称即可。可通过环境变量 BK_CLI_MONITOR_PROFILE_FILE 或单次命令参数 --profile_file 指定配置文件，用 profile list 查看配置、profile show 查看详情、profile check 检查工具契约、权限和资源元数据（不读取日志正文，也不证明每条查询表达式有效）。V2 Profile 可分别配置后端、Worker 等组件，并把日志、指标和 Trace 指向各自数据来源，同类指标可命名为 traffic、latency 等查询绑定；多组件时需明确 --component，多绑定时明确 --binding。缺少配置或选择有歧义时会停止，不自动切换。Profile 不是凭据，也不是授权，共享配置文件不代表共享访问权限。
三、资源发现与查询 命令统一采用 bk-cli monitor <模块> <工具> [参数] 结构，日志位于 monitor log 而非独立的 bk-cli log。没有 Profile 时，先用 space search_spaces 按名称查找业务空间，再用 log list_index_sets 查看日志索引集、get_index_set_fields 确认可查询字段，然后检索。资源标识必须来自用户已确认的 Profile 或当前账号可见目录，不猜测业务、表、索引集、应用或 Trace ID；出现多个候选时应结合业务名称、数据来源和采集范围选择。
四、典型场景
- 日志：支持按索引集或已配置场景检索，可显式指定查询词、时间范围、返回条数和字段过滤。容器日志需区分 --scene 选择日志场景、--where 按场景标签选择来源、--filter 对日志行做字段短语过滤、--query_string 输入关键词或表达式；多个 --filter 按 AND 组合，不是权限隔离规则。查看命中日志上下文时，先保存检索结果（如 hit.json），再用 search_index_set_context 查询，--size 是每个方向的条数限制。日志结果可能包含业务内容，应保存到授权位置，不提交到代码仓库或公开文档。
- 指标：支持 PromQL 范围查询，提供指标组、字段目录与 SQL 查询入口，可查看错误率、耗时、吞吐等变化，具体取决于业务已接入的指标。CLI 不会根据表名自动生成或改写 PromQL，查询口径可由 SRE 在 V2 Profile 中维护为具名查询。
- 告警：列表和 TopN 限定在最终选择的业务中，归属不一致或无法确认时拒绝输出。可查询异常状态告警、告警详情及关联日志查询目标；关联查询返回日志目标和索引信息，不是日志正文，需继续用日志命令并结合告警时间缩小范围。
- 调用链：APM 提供应用、服务、Span、Trace 和性能剖析查询，可检索调用记录并用返回的 trace_id 查看调用链。应用内检索不会自动限定到某个服务，服务级过滤需使用工具支持的过滤条件或已验证的 V2 工具预设。
五、时间范围 支持 --since 15m、--since 1h30m 等相对时间，--start_time 'yesterday 10:00' --end_time 'yesterday 11:00' 等可读日期，以及带时区偏移的 RFC3339 时间。无时区偏移的日期默认按 Asia/Shanghai 解释，可用 --timezone 覆盖。--since 与具名起止时间二选一；提供 --body 时时间以 body 为准。--since 最大 24 小时，日志单次窗口也不超过 24 小时。
六、能力范围 当前提供 11 个业务模块、65 个只读工具：log（9）日志场景、索引集、字段、日志、上下文及聚类；metric（4）指标组、字段、PromQL 和 SQL 查询；alert（12）告警、详情、事件和关联观测数据；apm（11）应用、服务、Span、Trace 和性能剖析；event（3）自定义事件和日志关键字事件；relation（2）资源关系即时与时间段查询；space（2）业务空间和集群目录；dashboard（2）仪表盘目录及详情；alarm（8）告警策略、屏蔽、通知组及处理套餐配置只读查看；collect（8）日志采集、索引集分组及清洗预览只读查看；extract（4）日志提取范围及任务状态。另有 tools、permission、profile 和 status 辅助命令。不确定工具或参数时，可用 tools search、tools schema 和 --help 查看。
七、权限与错误处理 可用 permission list 查看权限状态、permission check 检查具体工具与索引集权限、permission apply 获取申请入口（不会自动提交申请）。CLI 根据错误类型给出处理建议：needs_resource 补齐资源；permission_missing/permission_denied 查看权限诊断；resource_not_visible/resource_not_found 重新核对可见目录；response_too_large 缩小范围；retry_later 保留请求 ID 排查；auth_failed 更新登录状态等。可用 status 或 status --offline 检查当前状态，离线检查不验证登录有效性。
八、结果使用与限制 命令返回结构化 JSON，脚本应同时检查退出码及结果。查询命令可加 --dry-run 预览请求但不发送查询，不证明权限或表达式有效。空结果只表示本次范围与条件没有命中，CLI 不会自动扩大时间、换索引或切换数据来源。当前只提供只读入口，不创建或修改告警策略、采集配置、屏蔽规则，不启动任务或提供文件导出下载。CLI 提供数据和可复用查询，不保证自动得出根因。建议从一个明确业务、一个短时间窗和一种数据开始，确认来源与结果后再加入其他观测数据或自动化流程。