[Intermediate][Document] * 4: opentenbase_gts_tools, pg_stat_cluster_activity, opentenbase_pooler_stat, opentenbase_memory_tools

docs/guide/13-pg_stat_cluster_activity.md

@@ -0,0 +1,102 @@
+# **OpenTenbase 集群状态监控扩展模块pg_stat_cluster_activity详解**
+
+## **安装 OpenTenbase 集群状态监控扩展模块**
+
+连接到 OpenTenbase 数据库的节点：
+
+```sql
+CREATE EXTENSION pg_stat_cluster_activity;
+```
+
+此命令会安装 `pg_stat_cluster_activity` 扩展，该扩展提供集群级别的监控功能，能够详细展示集群中各节点的查询和事务状态。
+
+## 背景介绍
+
+OpenTenbase作为一个分布式数据库，执行查询时需要多个协调节点（CN）和数据节点（DN）交互，复杂查询可能涉及多层调用。这种架构下，CN和DN之间存在生产者和消费者的依赖关系，可能导致死锁、程序挂起、节点报错等问题。在缺乏有效的定位工具时，这些问题难以快速解决。本文介绍的全局视图工具，是解决这些问题的有力工具，适用于以下场景：
+
+- 定位问题查询所在的CN节点
+- 通过错误ID定位对应的DN节点
+- 定位出现进程挂起的问题节点
+
+## 总体介绍
+
+OpenTenbase 在运行过程中，多个节点的参与使得问题定位复杂。全局视图通过内部消息，将所有节点的运行信息统一展示，用户可以通过不同的过滤条件来精确定位问题。全局视图 `pg_stat_cluster_activity` 提供了每个服务器进程的详细描述，包括关联的用户会话和查询信息，极大地方便了SQL任务的问题分析和排查。
+
+## 全局视图表介绍
+
+`pg_stat_cluster_activity` 视图包含多个重要字段，每个字段都是分析问题不可或缺的信息源：
+
+- `sessionid`: 全局会话标识，用于识别不同会话。
+- `queryid`: 查询标识，相同的查询在不同的CN和DN上会有相同的queryid。
+- `nodename`: 执行查询的节点名称。
+- `datname`: 数据库名。
+- `pid`: 进程ID，用于进程级的问题分析。
+- `query`: 正在执行的查询文本。
+- `state`: 查询的状态，如活跃、挂起等。
+- `wait_event_type`: 等待事件类型，用于分析进程等待的资源类型。
+- `wait_event`: 具体的等待事件，描述进程正在等待的具体资源。
+
+## 注意事项
+
+在使用全局视图时，需要注意以下几点：
+
+1. 全局视图修改了内存表列和系统视图，因此必须在每个节点的 `postgresql.conf` 中进行配置修改后重启集群，扩展才能生效。
+2. 只有超级用户（superuser）或进程的拥有者才能查询 `pg_stat_activity` 视图。
+
+## 使用场景
+
+### 查看连接信息
+
+通过以下SQL查询可以确认当前的连接用户和对应的连接机器：
+
+```sql
+SELECT datname, usename, client_addr, client_port
+FROM pg_stat_cluster_activity
+WHERE client_addr IS NOT NULL;
+```
+
+### 查看SQL运行信息
+
+获取当前用户执行的SQL信息：
+
+```sql
+SELECT queryid, nodename, datname, pid, query
+FROM pg_stat_cluster_activity
+WHERE query <> ''
+ORDER BY queryid, nodename;
+```
+
+### 查看耗时较长的查询
+
+查找当前运行中耗时较长的SQL语句：
+
+```sql
+SELECT current_timestamp - query_start AS runtime, queryid, nodename, datname, state, query
+FROM pg_stat_cluster_activity
+WHERE state != 'idle' AND query <> ''
+ORDER BY runtime DESC;
+```
+
+### Query执行过程中挂起的问题定位
+
+定位执行过程中挂起的Query的问题节点：
+
+```sql
+SELECT queryid, nodename, datid AS datid, datname AS datname, pid, wait_event_type, wait_event, wait_event_info, local_fid, state, query
+FROM pg_stat_cluster_activity
+WHERE
+
+ queryid = (
+    SELECT queryid
+    FROM pg_stat_cluster_activity
+    WHERE pid= ?  -- 替换 `?` 为挂起Query的PID
+);
+```
+
+例如输出可能包括：
+
+- CN节点等待数据的事件类型，如果 `wait_event_type` 为 FN，表明在等待网络数据。
+- DN节点的 `local_fid` 是40，且没有等待事件，可能指示该DN节点为问题源。
+- 另一DN节点的等待事件为 `ClientRead`，表明它在正常等待新的命令，因此是正常节点。
+
+通过上述工具和方法，用户可以有效地利用OpenTenbase全局视图来监控和诊断分布式数据库中的各种问题。

docs/guide/14-opentenbase_memory_tools.md

@@ -0,0 +1,69 @@
+# OpenTenbase 内存详细监控扩展使用指南
+
+## 背景介绍
+
+在处理复杂的数据库应用时，了解和管理OpenTenbase的内存使用情况是至关重要的。尤其在生产环境中，准确地监控内存分配和消耗可以帮助避免资源瓶颈，提高系统稳定性和性能。OpenTenbase内存详细监控扩展提供了深入到每个内存上下文的详细视图，使得数据库管理员能够精确地观测和调优内存使用。
+
+## 总体介绍
+
+此扩展提供了两个主要功能：
+
+1. **节点内存详情** (`pg_node_memory_detail`)：提供当前节点的内存使用详细信息，包括各个内存区域的使用情况。
+2. **会话内存详情** (`pg_session_memory_detail`)：展示当前会话中各内存上下文的详细使用情况，支持深入到子上下文。
+
+这些工具对于诊断内存相关的性能问题非常有用，特别是在出现内存泄漏或者过度分配的情况下。
+
+## 扩展的主要功能和视图字段
+
+### `pg_node_memory_detail`
+
+此函数展示节点级别的内存使用详情，字段包括：
+
+- **Node Name**：节点名称，标识当前内存使用信息所属的节点。
+- **Process ID** (`pid`)：相关进程的ID。
+- **Memory Context Type**：内存上下文的类型。
+- **Used Memory (KB)**：该进程已使用的内存量（单位：KB）。
+
+### `pg_session_memory_detail`
+
+此函数提供会话级别的内存使用详情，字段包括：
+
+- **Memory Context Name**：内存上下文的名称。
+- **Level**：内存上下文在内存层级中的层次。
+- **Parent Context**：父级内存上下文的名称。
+- **Total Space (bytes)**：总分配空间（单位：字节）。
+- **Free Space (bytes)**：空闲空间（单位：字节）。
+
+## 安装和使用方法
+
+### 安装扩展
+
+在任意主控节点（CN）上执行以下命令安装此扩展：
+
+```sql
+CREATE EXTENSION pg_memory_details;
+```
+
+### 使用示例
+
+#### 查看节点内存详情
+
+```sql
+SELECT * FROM pg_node_memory_detail();
+```
+
+#### 查看会话内存详情
+
+```sql
+SELECT * FROM pg_session_memory_detail();
+```
+
+这些查询将返回内存使用的详细信息，帮助数据库管理员识别高内存消耗的上下文，优化内存使用。
+
+## 注意事项
+
+1. 使用这些监控功能需要超级用户权限，因为它们可能访问敏感的内存操作数据。
+2. 扩展安装后可能需要配置相应的OpenTenbase参数并重启数据库以确保新的配置生效。
+3. 由于详细的内存监控可能会轻微影响性能，请在非高峰时间进行相关监控活动。
+
+通过以上工具和方法，OpenTenbase管理员可以更好地管理和优化数据库的内存使用，提升数据库整体性能和稳定性。

docs/guide/15-opentenbase_pooler_stat.md

@@ -0,0 +1,84 @@
+# OpenTenbase 连接池统计监控扩展使用指南
+
+## 背景介绍
+
+OpenTenbase数据库在处理大量并发连接时，有效的连接池管理是确保性能和资源利用最优化的关键。在分布式环境下，理解各节点上连接池的状态对于诊断问题、优化资源分配及提高查询响应时间至关重要。本扩展提供了全面的连接池统计信息，帮助数据库管理员监控和分析连接池的健康状况。
+
+## 总体介绍
+
+此扩展包括以下主要功能：
+
+1. **获取连接池命令统计** (`opentenbase_get_pooler_cmd_statistics`)：提供连接池命令处理的统计数据，包括请求次数、平均处理时间、最长和最短处理时间等。
+2. **重置连接池命令统计** (`opentenbase_reset_pooler_cmd_statistics`)：重置连接池统计信息，便于进行新的性能基准测试。
+3. **获取连接池连接统计** (`opentenbase_get_pooler_conn_statistics`)：展示每个数据库和用户在各节点上的连接详细信息，包括总连接数、空闲连接数等。
+
+## 扩展的主要功能和视图字段
+
+### `opentenbase_get_pooler_cmd_statistics`
+
+此函数展示连接池处理各种命令的统计信息，字段包括：
+
+- **command_type**：命令类型，如CONNECT、DISCONNECT等。
+- **request_times**：该命令的请求次数。
+- **avg_costtime**：平均处理时间（微秒）。
+- **max_costtime**：最长处理时间（微秒）。
+- **min_costtime**：最短处理时间（微秒）。
+
+### `opentenbase_get_pooler_conn_statistics`
+
+此函数提供各数据库和用户在各节点上的连接统计，字段包括：
+
+- **database**：数据库名。
+- **user_name**：用户名。
+- **node_name**：节点名称。
+- **oid**：节点的OID。
+- **is_coord**：节点是否为协调节点。
+- **conn_cnt**：总连接数。
+- **free_cnt**：空闲连接数。
+- **warming_cnt**：预热中的连接数。
+- **query_cnt**：当前正在处理查询的连接数。
+- **exceed_keepalive_cnt**：超过保活时间的连接数。
+- **exceed_deadtime_cnt**：超过死亡时间的连接数（为兼容保留，未使用）。
+- **exceed_maxlifetime_cnt**：超过最大生命周期的连接数。
+
+## 安装和使用方法
+
+### 安装扩展
+
+在任意主控节点（CN）上执行以下命令安装此扩展：
+
+```sql
+CREATE EXTENSION opentenbase_pooler_stat;
+```
+
+### 使用示例
+
+#### 获取连接池命令统计
+
+```sql
+SELECT * FROM opentenbase_get_pooler_cmd_statistics();
+```
+
+#### 重置连接池命令统计
+
+```sql
+SELECT opentenbase_reset_pooler_cmd_statistics();
+```
+
+#### 获取连接池连接统计
+
+```sql
+SELECT * FROM opentenbase_get_pooler_conn_statistics();
+```
+
+这些查询将返回连接池的详细统计信息，帮助数据库管理员识别潜在的瓶颈，优化连接池配置。
+
+## 注意事项
+
+1. 使用这些监控功能需要超级用户权限，因为它们可能访问敏感的系统操作数据。
+2. 扩展安装后可能需要配置相应的PostgreSQL参数并重启数据库以确保新的配置生效。
+3. 监控数据可以帮助进行故障
+
+诊断和性能优化，但获取数据时可能会对系统性能产生轻微影响，请在非高峰时间进行相关监控活动。
+
+通过以上工具和方法，OpenTenbase管理员可以有效地监控和优化数据库连接池的性能，确保数据库系统的高效稳定运行。

docs/guide/16-opentenbase_gts_tools.md

@@ -0,0 +1,90 @@
+# OpenTenbase 事务时间戳与页面项统计扩展使用指南
+
+## 背景介绍
+
+在高并发的数据库系统中，了解事务的时间戳与页面项的详细信息对于优化查询性能、诊断系统问题、及进行数据恢复活动至关重要。OpenTenbase事务时间戳与页面项统计扩展提供了精确的工具，用于检视和分析每个页面项的内部结构及其关联的事务信息，从而支持数据库管理员在复杂的事务环境中作出及时且有效的决策。
+
+## 总体介绍
+
+此扩展包括以下主要功能：
+
+1. **事务全局时间戳查询** (`txid_gts`)：根据事务ID查询其提交时间戳，用于事务可见性分析及故障恢复。
+2. **页面项详细查询**：
+   - **带时间戳的页面项** (`heap_page_items_with_gts`): 提供页面项的详细信息，包括事务ID和相应的全局时间戳。
+   - **页面项日志输出** (`heap_page_items_with_gts_log`): 为调试目的输出页面项的日志信息。
+   - **页面项ID查询** (`heap_page_ids`): 仅查询页面项的ID信息，用于快速识别页面布局。
+   - **页面项无数据查询** (`heap_page_items_without_data`): 提供页面项的统计信息而不包括数据内容，减少数据传输量。
+
+## 扩展的主要功能和视图字段
+
+### `txid_gts`
+
+此函数根据事务ID返回其全局提交时间戳，字段包括：
+
+- **XID**: 输入的事务ID。
+- **Global Timestamp**: 事务的全球提交时间戳。
+
+### 页面项查询功能
+
+这一系列函数提供页面内部结构的详细分析，主要字段包括：
+
+- **Item ID**: 页面项的标识符。
+- **Offset**: 项在页面中的偏移量。
+- **Length**: 项的长度。
+- **Transaction IDs**: 与该项关联的事务ID。
+- **Timestamps**: 事务的提交时间戳。
+- **Data**: 项包含的原始数据（可选）。
+
+## 安装和使用方法
+
+### 安装扩展
+
+在任意主控节点（CN）上执行以下命令安装此扩展：
+
+```sql
+CREATE EXTENSION page_item_details;
+```
+
+### 使用示例
+
+#### 查询事务的全球时间戳
+
+```sql
+SELECT * FROM txid_gts(48576);
+```
+
+#### 查询带时间戳的页面项
+
+```sql
+SELECT * FROM heap_page_items_with_gts(get_raw_page('my_table', 1));
+```
+
+#### 查询页面项的ID信息
+
+```sql
+SELECT * FROM heap_page_ids(get_raw_page('my_table', 1));
+```
+
+#### 查询页面项无数据信息
+
+```sql
+SELECT * FROM heap_page_items_without_data(get_raw_page('my_table', 1));
+```
+
+#### 输出页面项的日志信息
+
+```sql
+SELECT * FROM heap_page_items_with_gts_log(get_raw_page('my_table', 1));
+```
+
+这些查询将返回页面项的详细统计信息，帮助数据库管理员识别潜在的数据一致性问题，优化页面存储结构。
+
+## 注意事项
+
+1. 使用这些监控功能需要超级用户权限，因为它们可能访问敏感的系统操作数据。
+2. 扩展安装后可能需要配置相应的PostgreSQL参数并重启数据库以确保新的配置生效。
+3. 监控数据可以帮助进行故障诊断和性能优化，但获取数据时可能会对系统性能产生
+
+轻微影响，请在非高峰时间进行相关监控活动。
+
+通过以上工具和方法，OpenTenbase管理员可以有效地监控和优化数据库事务的时间戳和页面项的性能，确保数据库系统的高效稳定运行。