使用 gp_toolkit Schema 查看系统信息
Apache Cloudberry 提供了一个名为 gp_toolkit
的管理 Schema,你可以用它查询系统目录、日志文件和操作环境中的系统状态信息。gp_toolkit
Schema 包含多个视图,可以通过 SQL 命令访问这些视图。所有数据库用户都能访问 gp_toolkit
Schema,虽然某些对象可能需要超级用户权限。为了方便使用,你可以将 gp_toolkit
Schema 添加到你的 Schema 搜索路径中。例如:
=> ALTER ROLE myrole SET search_path TO myschema,gp_toolkit;
本文档描述了 gp_toolkit
中一些最有用的视图和用户定义函数(UDF)。你可能会发现 gp_toolkit
Schema 中还有其他对象(视图、函数和外部表),这些对象是为了支持本节中描述的视图而存在,本文件中未具体描述它们。
请勿更改 gp_toolkit
Schema 中的数据库对象,也不要在该 Schema 中创建新的数据库对象,否则可能会影响这些对象所返回信息的准确性。通过 gpbackup
和 gprestore
工具进行数据库备份和恢复时,对 gp_toolkit
Schema 所做的任何更改都会丢失。
gp_toolkit
Schema 中的视图可以分为以下几类:
检查需要例行维护的表 检查锁 检查 ao 表 查看 apache cloudberry 服务器日志文件 检查服务器配置文件 检查下线的 segment 检查资源组活动和状态 检查资源队列活动和状态 查询磁盘溢出空间使用情况 查看用户和角色 检查数据库对象大小和磁盘空间 检查缺失和孤立数据文件 移动孤立数据文件 检查不均匀的数据分布 维护分区
关于扩展
gp_toolkit
是在 Apache Cloudberry 中作为扩展实现的。因为此扩展在 template1
数据库中注册,所以你在创建的每个 Apache Cloudberry 数据库中都可以立即使用它。
升级扩展
安装或升级 Apache Cloudberry 时,gp_toolkit
扩展会自动安装。即使升级了 Apache Cloudberry,之前版本的扩展仍可在现有数据库中使用。要将扩展升级到最新版本,你需要在每个使用该扩展的数据库中执行以下命令:
ALTER EXTENSION gp_toolkit UPDATE TO '1.4';
检查需要例行维护的表
以下视图可以帮助识别需要进行例行维护的表(如 VACUUM
和/或 ANALYZE
)。
VACUUM
或 VACUUM FULL
命令用于回收被删除或过期行占用的磁盘空间。由于 Apache Cloudberry 使用的是 MVCC 事务并发模型,被删除或更新的数据行虽然对新事务不可见,但仍然占用磁盘空间。过期的行会增加表在磁盘上的体积,进而降低表的扫描速度。
ANALYZE
命令用于收集查询优化器所需的列级统计信息。Apache Cloudberry 使用基于成本的查询优化器,依赖于数据库统计信息。准确的统计信息有助于查询优化器更好地估计选择性和查询操作将检索的行数,从而选择最有效的查询计划。
gp_bloat_diag
该视图显示了存在膨胀问题的常规堆存储表(即实际磁盘页数超过表统计信息中预期的页数)。这些膨胀的表需要执行 VACUUM
或 VACUUM FULL
操作,以回收被删除或过期行占用的磁盘空间。所有用 户都可以访问该视图,但非超级用户只能查看他们有权限访问的表。
有关返回更多表优化信息的诊断功能,请参见检查 AO 表视图。
该视图的列说明如下:
bdirelid
:表对象 ID。bdinspname
:Schema 名称。bdirelname
:表名称。bdirelpages
:磁盘上的实际页数。bdiexppages
:表数据预期的页数。bdidiag
:膨胀诊断信息。
gp_stats_missing
该视图显示了没有统计信息的表,这些表可能需要执行 ANALYZE
操作。
该视图的列说明如下:
smischema
:Schema 名称。smitable
:表名称。smisize
:该表是否具有统计信息?如果表没有记录行计数和行大小统计信息,则此值为假,表明该表可能需要分析。如果表中没有任何行,这个值也 会为假。例如,分区表的父表始终是空的,因此始终返回假值。smicols
:表中的列数。smirecs
:表中记录了统计信息的列数。
检查锁
当事务访问某个关系(如表)时,会获取一个锁。根据获取的锁类型,后续事务可能需要等待才能访问相同的关系。有关锁类型的更多信息,请参见事务中的并发控制的多版本并发控制机制。Apache Cloudberry 的资源队列(用于资源管理)也使用锁来控制查询进入系统。
gp_locks_*
系列视图可以帮助诊断由于锁而导致查询和会话等待访问对象的情况。
gp_locks_on_relation
该视图显示当前在关系上持有的任何锁,以及与该锁相关的查询的会话信息。有关锁类型的更多信息,请参见事务中的并发控制。所有用户都可以访问该视图,但非超级用户只能看到他们有权限访问的关系的锁。
该视图的列说明如下:
lorlocktype
:可锁对象的类型:relation
、extend
、page
、tuple
、transactionid
、object
、userlock
、resource queue
或advisory
。lordatabase
:对象所在数据库的对象 ID,如果对象是共享对象,则为零。lorrelname
:关系名称。lorrelation
:关系对象 ID。lortransaction
:受锁影响的事务 ID。lorpid
:持有或等待此锁的服务器进程的进程 ID。如果锁被准备事务持有,则为NULL
。lormode
:当前进程持有或期望的锁模式名称。lorgranted
:显示锁是否已授予(true
)或未授予(false
)。lorcurrentquery
:当前会话中的查询。
gp_locks_on_resqueue
gp_locks_on_resqueue
视图只有在基于资源队列的资源管理启用时才有效。
该视图显示当前在资源队列上持有的锁及相关查询会话的信息。所有用户都可以访问该视图,但非超级用户只能看到与自己会话相关的锁。
该视图的列描述如下:
lorusename
:运行会话的用户名称。lorrsqname
:资源队列名称。lorlocktype
:锁对象的类型:resource queue
。lorobjid
:锁定事务的 ID。lortransaction
:受锁影响的事务 ID。lorpid
:受锁影响事务的进程 ID。lormode
:该进程持有或期望的锁模式名称。lorgranted
:显示锁是否被授予(true
)或未被授予(false
)。lorwaiteventtype
:等待事件的类别(例如 I/O、锁定、网络等)。lorwaitevent
:具体等待事件的名称或描述(例如某个文件的 I/O 操作或锁的对象)。
检查 AO 表
gp_toolkit
Schema 包含一组诊断函数,用于检查 AO 表(即 Append-Optimized 表)的状态。
创建 AO 表(或列式 AO 表)时,会自动创建一张表来存储该表的元数据信息。元数据包括每个表 Segment 中的记录数量等信息。
AO 表中可能包含不可见行——这些是已更新或删除的行,在表执行 VACUUM
压缩前,这些行仍保留在存储中。隐藏行通过辅助的可见性映射表(visimap)进行跟踪。
以下函数可以让你访问 AO 表和列式表的元数据,并查看其中的不可见行。
大多数函数的输入参数是 regclass
,可以是表的 name
或表的 oid
。
__gp_aovisimap_compaction_info(oid)
该函数显示 AO 表的压缩信息,针对存储表数据的数据库 Segment 上的磁盘数据文件。你可以利用这些信息确定 VACUUM
操作将压缩哪些 AO 表的数据文件。
在 VACUUM
操作删除数据文件中的行之前,尽管这些行对新事务不可见,已删除或更新的行仍会占用磁盘空间。配置参数 gp_appendonly_compaction
控制 VACUUM
的功能。
下表描述了 __gp_aovisimap_compaction_info
函数输出的列信息:
content
:数据库 Segment ID。datafile
:Segment 上的数据文件 ID。compaction_possible
:此值为t
或f
,值为t
表示执行VACUUM
时可以对数据文件进行压缩。服务器配置参数gp_appendonly_compaction_threshold
会影响此值。hidden_tupcount
:数据文件中隐藏(已删除或更新)行的数量。total_tupcount
:数据文件中的行总数。percent_hidden
:数据文件中隐藏行占总行数的百分比。
__gp_aoseg(regclass)
该函数返回 AO 表磁盘 Segment 文件的元数据。
输入参数是 AO 表的名称或 OID。输出的列描述如下:
segment_id
:数据分片在集群中的 Segment ID。segno
:文件 Segment 编号。eof
:该文件 Segment 的有效文件结束位置。tupcount
:Segment 中的元组总数,包括不可见的元组。varblockcount
:文件 Segment 中的可变块总数。eof_uncompressed
:如果文件 Segment 未压缩,则显示文件结束的位置。modcount
:数据修改操作的次数。formatversion
:AO 文件的存储格式版本,用于指示文件所使用的格式版本。state
:文件 Segment 的状态,指示该 Segment 是否处于活动状态或在压缩后等待删除。
__gp_aoseg_history(regclass)
该函数返回 AO 表磁盘 Segment 文件的元数据历史信息,显示所有不同版本(堆元组)的 aoseg
元数据。虽然数据较复杂,但对于有系统深入理解的用户来说,可能在调试时有用。
输入参数是 AO 表的名称或 OID。输出的列描述如下:
segment_id
:数据分片在集群中的 Segment ID。segno
:文件 Segment 编号。tupcount
:Segment 中的元组总数,包括不可见的元组。eof
:该文件 Segment 的有效文件结束位置。eof_uncompressed
:如果文件 Segment 未压缩,则显示文件结束的位置。modcount
:数据修改操作的次数。formatversion
:AO 文件的存储格式版本,用于指示文件所使用的格式版本。state
:文件 Segment 的状态,指示该 Segment 是否处于活动状态或在压缩后等待删除。
__gp_aocsseg(regclass)
该函数返回列存储的 AO 表的磁盘 Segment 文件中的元数据信息,不包括不可见行。每行描述表中某列的 Segment 信息。
输入参数是列存储 AO 表的名称或 OID。输出的列描述如下:
segment_id
:数据分片在集群中的 Segment ID。segno
:文件 Segment 编号。column_num
:列号。physical_segno
:Segment 文件中的 Segment 编号。tupcount
:Segment 中的元组总数,包括不可见的元组。eof
:该文件 Segment 的有效文件结束位置。eof_uncompressed
:如果文件 Segment 未压缩,则显示文件结束的位置。modcount
:数据修改操作的次数。formatversion
:AO 文件的存储格式版本,用于指示文件所使用的格式版本。state
:文件 Segment 的状态,指示该 Segment 是否处于活动状态或在压缩后等待删 除。
__gp_aocsseg_history(regclass)
此函数返回列式 AO 表的磁盘 Segment 文件中的元数据信息。每一行描述表中某列的一个 Segment。数据较为复杂,但对于深入了解系统的用户来说,这些信息可能对调试有所帮助。
输入参数为列式 AO 表的名称或 oid。输出的列描述如下:
segment_id
:数据分片在集群中的 Segment ID。segno
:文件 Segment 编号。column_num
:列号。physical_segno
:包含列数据的 Segment。tupcount
:Segment 中的元组总数。eof
:该文件 Segment 的有效文件结束位置。eof_uncompressed
:如果文件 Segment 未压缩,则显示文件结束的位置。modcount
:数据修改操作的次数。formatversion
:AO 文件的存储格式版本,用于指示文件所使用的格式版本。state
:文件 Segment 的状态,指示该 Segment 是否处于活动状态或在压缩后等待删除。
__gp_aovisimap(regclass)
此函数根据可见性映射返回每个不可见元组的元组 ID、Segment 文件和行号。
输入参数为 AO 表的名称或 oid。输出的列描述如下:
tid
:元组 ID。segno
:Segment 文件的编号。row_num
:被删除或更新行的行号。
__gp_aovisimap_hidden_info(regclass)
此函数返回 AO 表的 Segment 文件中隐藏和可见元组的数量。
输入参数为 AO 表的名称或 oid。输出的列描述如下:
segno
:Segment 文件的编号。hidden_tupcount
:Segment 文件中隐藏元组的数量。total_tupcount
:Segment 文件中的元组总数。
__gp_aovisimap_entry(regclass)
此函数返回有关表的每个可见性图条目的信息。
输入参数是 AO 表的名称或 OID。输出列的描述如下:
segno
:可见性图条目的 Segment 号。first_row_num
:条目的首行编号。hidden_tupcount
:条目中隐藏元组的数量。bitmap
:可见性位图的文本表示。
__gp_aoblkdir(regclass)
对于具有或曾经具有索引的 AO/AOCO 表,此函数返回在块目录关系中记录的每个块目录条目的行;它将块目录关系的 minipage
列扁平化,并为每个 minipage
条目返回一行。
输入参数是 AO 表的名称或OID。
你必须在实用模式下 对每个 Segment 执行此函数,或使用 gp_dist_random()
,如以下示例所示:
SELECT (gp_toolkit.__gp_aoblkdir('<table_name>')).*
FROM gp_dist_random('gp_id');
输出列的描述如下:
tupleid
:包含此块目录条目的块目录行的元组 ID。segno
:物理 Segment 文件编号。columngroup_no
:此minipage
条目所描述列的attnum
(对于面向行的表始终为0
)。entry_no
:此minipage
内包含此块目录条目的条目序列号。first_row_no
:此块目录条目所覆盖行的首行编号。file_offset
:此块目录条目所覆盖行的起始文件偏移量。row_count
:此块目录条目所覆盖行的数量。
get_column_size(oid)
对于给定的 AOCO 表,此函数返回表中所有列的列大小和压缩比。
输入参数是列式 AO 表的对象标识符。输出列的描述如下:
segment
:Segment ID。attnum
:列的属性编号。size
:列的大小(以字节为单位)。size_uncompressed
:如果列未压缩,则列的大小(以字节为单位)。compression_ratio
:压缩比。
gp_column_size
该视图汇总了所有 Segment 中列式 AO 表的列大小和压缩比。视图的列说明如 下:
gp_segment_id
:Segment ID。relid
:表的 OID(对象标识符)。schema
:表所属的 schema 名称。relname
:表名。attnum
:列的属性编号。attname
:列名。size
:列的大小(以字节为单位)。size_uncompressed
:如果列未被压缩,则列的大小(以字节为单位)。compression_ratio
:压缩比。
gp_column_size_summary
该视图展示了 gp_column_size
视图的汇总信息。它聚合了所有 Segment 中每个列式 AO 表的每列的大小和压缩比。视图的列说明如下:
relid
:表的 OID(对象标识符)。schema
:表所属的 schema 名称。relname
:表名。attnum
:列的属性编号。attname
:列名。size
:列的大小(以字节为单位)。size_uncompressed
:如果列未压缩,则列的大小(以字节为单位)。compression_ratio
:压缩比。
查看 Apache Cloudberry 服务器日志文件
Apache Cloudberry 系统的每个组件(Coordinator、Standby Coordinator、主 Segment 和镜像 Segment)都会保留自己的服务器日 志文件。gp_log_*
系列视图允许你对服务器日志文件发出 SQL 查询,以查找特定感兴趣的条目。使用这些视图需要超级用户权限。
gp_log_command_timings
该视图使用外部表读取 Coordinator 上的日志文件,并报告数据库会话中 SQL 命令的运行时间。使用该视图需要超级用户权限。视图的列描述如下:
logsession
:会话标识符(以 "con" 为前缀)。logcmdcount
:会话中的命令编号(以 "cmd" 为前缀)。logdatabase
:数据库名称。loguser
:数据库用户名称。logpid
:进程 ID(以 "p" 为前缀)。logtimemin
:此命令的第一个日志消息的时间。logtimemax
:此命令的最后一个日志消息的时间。logduration
:从开始到结束的语句持续时间。
gp_log_database
该视图使用外部表读取整个 Apache Cloudberry 系统(Coordinator、Segment 和镜像)的服务器日志文件,并列出与当前数据库相关的日志条目。相关的日志条目可以通过会话 ID(logsession
)和命令 ID(logcmdcount
)识别。使用该视图需要超级用户权限。视图的列描述如下:
logtime
:日志消息的时间戳。loguser
:数据库用户名称。logdatabase
:数据库名称。logpid
:关联的进程 ID(以 "p" 为前缀)。logthread
:关联的线程计数(以 "th" 为前缀)。loghost
:Segment 或 Coordinator 主机名。logport
:Segment 或 Coordinator 端口。logsessiontime
:会话连接打开的时间。logtransaction
:全局事务 ID。logsession
:会话标识符(以 "con" 为前缀)。logcmdcount
:会话中的命令编号(以 "cmd" 为前缀)。logsegment
:Segment 内容标识符(主 Segment 以 "seg" 为前缀,镜像以 "mir" 为前缀, Coordinator 的内容 ID 始终为 -1)。logslice
:切片 ID(正在运行的查询计划部分)。logdistxact
:分布式事务 ID。loglocalxact
:本地事务 ID。logsubxact
:子事务 ID。logseverity
:日志级别,包括LOG
、ERROR
、FATAL
、PANIC
、DEBUG1
或DEBUG2
。logstate
:与日志消息关联的 SQL 状态代码。logmessage
:日志或错误消息文本。logdetail
:与错误消息关联的详细信息文本。loghint
:与错误消息关联的提示信息文本。logquery
:系统生成的查询文本。logquerypos
:系统生成的查询文本中的游标索引。logcontext
:生成此消息的上下文。logdebug
:用于调试的查询字符串,包含详细信息。logcursorpos
:查询字符串中的游标索引。logfunction
:生成此消息的函数。logfile
:生成此消息的日志文件。logline
:生成此消息的日志文件中的行。logstack
:与此消息相关的堆栈跟踪的完整文本。
gp_log_coordinator_concise
该视图使用外部表从 Coordinator 日志文件中读取一部分日志字Segment。使用该视图需要超级用户权限。视图的列描述如下:
logtime
:日志消息的时间戳。logdatabase
:数据库的名称。logsession
:会话标识符(以 "con" 为前缀)。logcmdcount
:会话中的命令编号(以 "cmd" 为前缀)。logseverity
:日志的严重性级别。logmessage
:日志或错误消息文本。
gp_log_system
该视图使用外部表读取整个 Apache Cloudberry 系统(Coordinator 、Segment 和镜像)的服务器日志文件,并列出所有日志条目。相关日志条目可以通过会话 ID(logsession
)和命令 ID(logcmdcount
)进行识别。使用该视图需要超级用户权限。视图的列描述如下:
logtime
:日志消息的时间戳。loguser
:数据库用户的名称。logdatabase
:数据库的名称。logpid
:相关的进程 ID(以 "p" 为前缀)。logthread
:相关的线程计数(以 "th" 为前缀)。loghost
:Segment 或 Coordinator 的主机名称。logport
:Segment 或 Coordinator 的端口。logsessiontime
:会话连接打开的时间。logtransaction
:全局事务 ID。logsession
:会话标识符(以 "con" 为前缀)。logcmdcount
:会话中的命令编号(以 "cmd" 为前缀)。logsegment
:Segment 内容标识符(对于主 Segment 以 "seg" 为前缀,镜像 Segment 以 "mir" 为前缀。Coordinator 的内容 ID 始终为 -1)。logslice
:切片 ID(运行中的查询计划的一部分)。logdistxact
:分布式事务 ID。loglocalxact
:本地事务 ID。logsubxact
:子事务 ID。logseverity
:LOG、ERROR、FATAL、PANIC、DEBUG1 或 DEBUG2。logstate
:与日志消息关联的 SQL 状态码。logmessage
:日志或错误消息文本。logdetail
:与错误消息相关的详细消息文本。loghint
:与错误消息相关的提示消息文本。logquery
:内部生成的查询文本。logquerypos
:内部生成的查询文本中的游标索引。logcontext
:生成此消息的上下文。logdebug
:包含完整调试信息的查询字符串。logcursorpos
:查询字符串中的游标索引。logfunction
:生成此消息的函数。logfile
:生成 此消息的日志文件。logline
:生成此消息的日志文件中的行。logstack
:与此消息关联的堆栈跟踪的完整文本。
检查服务器配置文件
每个 Apache Cloudberry 系统的组件(Coordinator、Standby Coordinator、主 Segment 和镜像 Segment)都有自己的服务器配置文件(postgresql.conf
)。可以使用以下 gp_toolkit
对象检查系统中所有主 postgresql.conf
文件的参数设置:
gp_param_setting('parameter_name')
该函数接收一个服务器配置参数的名称,并返回 Coordinator 和每个活动 Segment 的 postgresql.conf
值。此函数对所有用户可用。视图的列描述如下:
paramsegment
:Segment 内容 ID(仅显示活动 Segment )。Coordinator 内容 ID 始终为-1
。paramname
:参数名称。paramvalue
:参数值。
示例:
SELECT * FROM gp_toolkit.gp_param_setting('max_connections');
gp_param_settings_seg_value_diffs
被分类为 local 参数的服务器配置参数(即每个 Segment 从其自己的 postgresql.conf
文件中获取参数值)应该在所有 Segment 上设置为相同的值。该视图显示了不一致的本地参数设置。预期有不同值 的参数(例如 port
)不包括在内。该视图对所有用户可用。
视图的列描述如下:
psdname
:参数名称。psdvalue
:参数值。psdcount
:拥有该值的 Segment 的数量。
检查下线的 Segment
可以使用 gp_pgdatabase_invalid
视图检查处于下线状态的 Segment。
gp_pgdatabase_invalid
该视图显示系统目录中标记为下线 Segment 的信息。该视图对所有用户可用。视图的列描述如下:
pgdbidbid
:Segment 的 dbid。每个 Segment 都有一个唯一的 dbid。pgdbiisprimary
:该 Segment 当前是否作为主 Segment (活动 Segment)?(t
或f
)。pgdbicontent
:此 Segment 的内容 ID。主 Segment 和镜像 Segment 将具有相同的内容 ID。pgdbivalid
:此 Segment 是否在线并有效?(t
或f
)。pgdbidefinedprimary
:此 Segment 在系统初始化时是否被分配为主 Segment 角色?(t
或f
)。
检查资源组活动和状态
本节描述的资源组活动和状态视图仅在基于资源组的资源管理处于激活状态时有效。
资源组用于管理事务,以避免耗尽系统的 CPU 和内存资源。每个数据库用户都被分配到一个资源组。Apache Cloudberry 在执行用户提交的事务之前,会根据用户资源组的配置限制来评估该事务。
你可以使用 gp_resgroup_config
视图查看每个资源组的配置情况。你可以使用 gp_resgroup_status*
视图来显示每个资源组的当前事务状态和资源使用情况。
gp_resgroup_config
gp_resgroup_role
gp_resgroup_status
gp_resgroup_status_per_host
gp_resgroup_status_per_segment