# Observer SQL Analysis

> 标准 SOP：单条 SQL 性能、执行计划、trace 计划包、锁等待。用户问「为什么慢」、提供 trace_id、或描述锁/超时时使用；与 obdiag-performance（整体 ASH/AWR）、observer-log-analysis（observer 日志链）分工。

- Skill: `oceanbase/observer-sql-analysis` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oceanbase/observer-sql-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oceanbase/observer-sql-analysis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: oceanbase (https://skillmd.com/u/oceanbase)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oceanbase/observer-sql-analysis

---


# 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`**。

**完成标准**：知识库结论与 **现场数据** 并列说明；冲突时以数据为准并点明差异。

## 输出格式（必填结构）

1. **表格**：计划关键指标（操作符、COST、ROWS、索引/分区等）或锁等待关键字段。
2. **结论文本**：1–3 条 **可执行** 建议（加索引条件、改写 SQL、调参、扩时间再采日志等）。
3. **下一步**：若需 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`**？
- 输出是否同时包含 **表格 + 建议 + 可选下一步**？