diff --git a/docs/guide/13-pg_stat_cluster_activity.md b/docs/guide/13-pg_stat_cluster_activity.md new file mode 100644 index 0000000..eb0359c --- /dev/null +++ b/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全局视图来监控和诊断分布式数据库中的各种问题。 \ No newline at end of file diff --git a/docs/guide/14-opentenbase_memory_tools.md b/docs/guide/14-opentenbase_memory_tools.md new file mode 100644 index 0000000..2b691ba --- /dev/null +++ b/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管理员可以更好地管理和优化数据库的内存使用,提升数据库整体性能和稳定性。 \ No newline at end of file diff --git a/docs/guide/15-opentenbase_pooler_stat.md b/docs/guide/15-opentenbase_pooler_stat.md new file mode 100644 index 0000000..15ec30d --- /dev/null +++ b/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管理员可以有效地监控和优化数据库连接池的性能,确保数据库系统的高效稳定运行。 \ No newline at end of file diff --git a/docs/guide/16-opentenbase_gts_tools.md b/docs/guide/16-opentenbase_gts_tools.md new file mode 100644 index 0000000..f0bc7f5 --- /dev/null +++ b/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管理员可以有效地监控和优化数据库事务的时间戳和页面项的性能,确保数据库系统的高效稳定运行。 \ No newline at end of file