| name | observer-sql-analysis |
| description | 标准 SOP：单条 SQL 性能、执行计划、trace 计划包、锁等待。用户问「为什么慢」、提供 trace_id、或描述锁/超时时使用；与 obdiag-performance（整体 ASH/AWR）、observer-log-analysis（observer 日志链）分工。 |
SQL 深度分析 — SOP
触发与边界
- 本 SOP：围绕 一条或少量 SQL、trace_id、执行计划、锁等待。
- 不替代：时段整体负载、会话堆积 →
obdiag-performance（gather_ash 等）；OBProxy 日志 → obproxy-log-analysis。
前置条件
- 尽量明确：SQL 文本 或 trace_id 或 sql_id（视工具能力）；多集群传
cluster_config_path。
分支：选主路径
| 情况 | 主路径 |
|---|
| 用户已给 trace_id，要计划/监控包 | 阶段 A 为主，必要时 阶段 C |
| 无 trace_id，要能直接在库上查计划 | 阶段 B（db_query EXPLAIN / 视图）为主 |
| 用户强调 锁等待、死锁、超时 | 阶段 B + 阶段 C（日志 grep 相关 trace/sql） |
| 既要计划又要和 observer 日志对齐 | 阶段 A 或 B → 阶段 C |
阶段 A：计划监控包（trace_id）
目的：拉取与 trace 关联的 SQL plan monitor 材料。
动作：
- 调用
gather_plan_monitor，传入 trace_id；时间参数格式：from_time="2024-01-01 10:00:00"（yyyy-mm-dd hh:mm:ss）；非默认集群 cluster_config_path。
完成标准：
- 工具成功返回且可知 输出目录或结果摘要；否则说明失败原因与下一步（时间窗、权限）。
阶段 B：库内计划与锁线索（db_query）
目的：在没有或未用 plan monitor 包时，从集群侧拿 执行计划、锁/会话 信息。
动作：
- 使用
db_query 执行 只读 SQL：EXPLAIN / EXPLAIN EXTENDED、相关 gv$/v$ 视图（锁、等待、sql_audit 等，以用户环境与版本为准）。
- 关注：访问路径、COST、ROWS、PARTITION、是否全表扫；锁场景关注 holder/waiter、资源 ID。
常用视图速查（以 OceanBase 4.x sys 租户或 DBA 权限为准）：
| 场景 | 推荐视图 |
|---|
| 锁等待、死锁 | gv$ob_locks、gv$ob_transaction_participants、information_schema.innodb_lock_waits |
| 活跃会话与等待 | gv$ob_processlist、gv$ob_active_session_history |
| SQL 审计、慢 SQL | gv$ob_sql_audit（elapsed_time > N、按 sql_id 过滤） |
| 执行计划缓存 | gv$ob_plan_cache_plan_explain、gv$ob_plan_cache_stat |
| 当前事务 | gv$ob_transaction_participants、v$ob_global_transaction |
完成标准：
- 有关键计划字段或锁/会话事实；若查不到，说明可能原因（计划已淘汰、租户权限、时间窗）。
阶段 C：日志侧证（observer）
目的：用 observer 日志 补充错误栈、重试、与 trace 相关的行级上下文。
动作：
gather_log 带 grep（trace_id、SQL 指纹片段、错误码）+ 时间范围；或 analyze_log 做聚合（仍仅集群侧，非 OBProxy）。- 详见
observer-log-analysis 的链式要求；若用户同时 OBProxy，切 obproxy-log-analysis。
完成标准：
- 日志与阶段 A/B 结论能 互证或解释矛盾；无日志命中时建议缩小/扩大时间或换关键词。
阶段 D：文档与参数（可选）
目的：参数含义、版本行为与官方表述对齐。
动作：调用 query_oceanbase_knowledge_base，query 中含 Observer/OBProxy 版本（若已知）；长上下文放 context_text。
完成标准：知识库结论与 现场数据 并列说明；冲突时以数据为准并点明差异。
输出格式（必填结构）
- 表格：计划关键指标（操作符、COST、ROWS、索引/分区等）或锁等待关键字段。
- 结论文本：1–3 条 可执行 建议（加索引条件、改写 SQL、调参、扩时间再采日志等）。
- 下一步：若需 ASH/AWR、巡检、RCA，指明 skill 或工具。
与其它 skill
| 需求 | 使用 |
|---|
| ASH/AWR/perf/整体慢 | obdiag-performance |
| observer 日志采集分析主流程 | observer-log-analysis |
| OBProxy | obproxy-log-analysis |
| 巡检 / RCA | obdiag-check-rca |
自检
- 是否把
gather_plan_monitor 当成「收普通日志」？（应 gather_log。）
- 有 trace_id 时是否优先
gather_plan_monitor 再视需要 db_query？
- 输出是否同时包含 表格 + 建议 + 可选下一步？
