KingbaseES产品手册|金仓数据库 KingbaseES 插件参考手册 S(3) KingbaseES产品手册|kingbase

83. sys_freespacemap 83.1. 插件sys_freespacemap简介 sys_freespacemap提供了查看FSM页面的方法。插件提供函数来显示FSM页面中记录的指定关系指定页面的值或是指定关系全部页面的值。默认仅限超级用户、pg_stat_scan_tables 角色的成员使用。

插件名为 sys_freespacemap
插件版本 V1.2

83.2. 插件sys_freespacemap加载方式插件为内置插件，自动加载。
83.3. 插件sys_freespacemap的参数配置无需配置任何参数
83.4. 插件sys_freespacemap的使用方法 sys_freespacemap提供以下函数：
sys_freespace(rel regclass IN, blkno bigint IN) returns int2
返回指定关系指定块在FSM页面中记录的空闲空间值。
sys_freespace(rel regclass IN, blkno OUT bigint, avail OUT int2)
返回指定关系中每个块在FSM页面中记录的空闲空间值。返回(blkno bigint, avail int2)类型的集合，每一行对应关系中的一个块。
FSM页面中存储的空闲空间值并不是准确的。值会按块大小的1/256四舍五入，而且值在表页面被修改时不会实时更新。对于索引来说，FSM页面记录的是空闲页面而不是页面中的空闲空间，返回值只代表页面是否为整个空闲。
83.5. 插件sys_freespacemap卸载方法插件为内置插件，不允许卸载。
83.6. 插件sys_freespacemap升级方法通过 ALTER EXTENSION升级插件。
示例，升级到 1.1：

ALTER EXTENSION sys_freespacemap UPDATE TO '1.1';

84. sys_jieba 84.1. 插件sys_jieba简介 sys_jieba是一个KingbaseES的扩展，主要用于全文搜索的中文分词。sys_jieba中文分词插件支持utf8字符集。

插件名为 sys_jieba
插件版本 V1.0

84.2. 插件sys_jieba加载方式

CREATE EXTENSION sys_jieba;

84.3. 插件sys_jieba的参数配置无需配置任何参数
84.4. 插件sys_jieba的使用方法

CREATE EXTENSION sys_jieba; SELECT * FROM ts_parse('jieba', 'KingbaseES中文分词插件测试'); tokid |token -------+------------ 2 | KingbaseES 2 | 中文 2 | 分词 2 | 插件 2 | 测试 (5 rows)SELECT to_tsvector('jiebacfg','KingbaseES中文分词插件测试'); to_tsvector ---------------------------------------------------- 'kingbasees':1 '中文':2 '分词':3 '插件':4 '测试':5 (1 row)SELECT to_tsquery('jiebacfg', '分词'); to_tsquery ------------ '分词' (1 row)

84.5. 插件sys_jieba的卸载方法

drop extension sys_jieba;

84.6. 插件sys_jieba升级方法 sys_jieba扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。
85. sys_ksh 85.1. 插件sys_ksh简介插件sys_ksh是KingbaseES 的一个扩展插件。主要功能是会话历史的分析，并针对报告呈现的性能瓶颈进行优化。
KingbaseES 在 V8R6 中引入了明细会话历史(Kingbase Session History)和相应的报告工具。

插件名为 sys_ksh
插件版本 V1.0

85.2. 插件sys_ksh加载方式在使用 sys_ksh 之前，我们需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。
示例：

shared_preload_libraries = 'sys_stat_statements, sys_ksh'

进入 Kingbase 创建插件

create extension sys_ksh;

注：当sys_ksh.enable = on时由系统自动创建插件
85.3. 插件sys_ksh的参数配置 sys_ksh的参数在kingbase.conf中设置：

shared_preload_libraries ='sys_stat_statements, sys_ksh' track_activities = on sys_stat_statements.max = 10000 sys_stat_statements.track =all sys_ksh.enable = on# default = off sys_ksh.ringbuf_size = 200000# default = 100000 sys_ksh.history_days = 3# default = 8；最小 2，最大 31 sys_ksh.language = 'english'# default = ‘chinese’

上述参数的意义如下：

track_activities：跟踪活动会话的等待事件、执行SQL、状态等，默认：onsys_stat_statements.max：设置sys_stat_statement跟踪的最大语句数，默认：5000sys_stat_statements.track：跟踪统计SQL语句的访问，推荐用 'top'，默认为'none'sys_ksh.enable：启用或禁用sys_ksh数据收集sys_ksh.ringbuf_size：设置sys_ksh ringbuf大小sys_ksh.history_days：设置最大的sys_ksh历史数据存储sys_ksh.language：KSH报告展示中文/英语信息

注：采集报告需要在开启：track_activities，并至少设定 sys_ksh.enable=on 的情况下才可以查看。开启该参数会有一定的性能损耗。
85.4. 插件sys_ksh的使用方法 85.4.1. 概述
sys_ksh 以每秒采样的方式进行会话和数据收集，并将采集数据放入内存的 Ringbuf 队列中，采集的数据主要包括：会话、应用、等待事件、命令类型、QueryId等。其主要使用场景是：当前或历史某个时点，发生了什么样的异常，系统在执行/运行什么任务。
85.4.2. 采集数据说明
KSH采集的数据主要包括以下信息：

字段	类型	描述
ts	timestamptz	采样时间
pid	int	进程ID
【KingbaseES产品手册\|金仓数据库 KingbaseES 插件参考手册 S(3)】client_addr	inet	客户端IP地址
app_name	varchar(64)	应用名称
db_id	oid	数据库OID
db_name	varchar(64)	数据库名称
user_id	oid	用户OID
user_name	varchar(64)	用户名
phase	text	执行阶段，如：PARSE, PLAN, EXECUTION, UNKNOWN
event_type	text	等待事件类型
event	text	等待事件
query_id	uint8	QueryId
cmd_type	text	指令类型，如INSERT, SELECT, UPDATE, DELETE, UTILITY等
backend_type	text	后端类型，如：autovacuum, autovacuum worker等
state	text	运行状态如running, idle等
is_simple	bool	简单查询语句标志
table_id	oid	IO操作变量的表OID
func	text	运行plsql的函数名
learder_pid	int	父进程pid(针对并行)

保存于内存Ringbuf的数据可以通过视图perf.session_history查看：

SELECT * FROM perf.session_history;

保存于数据库的历史数据可以通过视图perf.ksh_history查看：

SELECT * FROM perf.ksh_history;

85.4.3. 生成报告

SELECT perf.ksh_report({start_ts}, {duration}, {slot_width}, {write_to_file});

上述参数说明：
start_ts: 报告开始时间，默认：当前时间-15分钟
duration: 报告时长，默认到15分钟，最大不超过60
slot_width: 报告最小区间，输入0时系统自动计算合适的宽度
write_to_file: 是否输出到sys_log目录，默认否

报告详细说明，请参考 sys_ksh 文档

85.5. 插件sys_ksh卸载方法进入 Kingbase 创建插件
示例：

drop extension sys_ksh CASCADE;

85.6. 插件sys_ksh升级方法 sys_ksh扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。
86. sys_kwr 86.1. 插件sys_kwr简介插件sys_kwr是KingbaseES 的一个扩展插件。主要功能是通过周期性自动记录性能统计相关的快照，分析出KES的操作系统运行环境、数据库时间组成、等待事件和TOP SQL等性能指标，为数据库性能调优提供指导。
sys_kwr 是 Kingbase Auto Workload Repertories 的简称，可以对 KingbaseES 的负载信息自动以快照的方式进行记录和保存，并提供负载相关的性能报告。

插件名为 sys_kwr
插件版本 V1.3

86.2. 插件sys_kwr加载方式 KingbaseES数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加载。
示例如下

shared_preload_libraries = 'sys_kwr'

86.3. 插件sys_kwr的参数配置要想使用 KWR 的全部报告功能，建议在kingbase.conf里添加以下6个参数

track_sql = on track_instance = on track_wait_timing = on track_counts = on track_io_timing = on track_functions = 'all' sys_stat_statements.track = 'top' sys_kwr.enable = on

上述参数的意义如下

track_sql:开启统计 sql 时间，等待事件，IO ，默认为offtrack_instance开启统计实例级IO，关键活动，锁，默认为offtrack_wait_timing开启累积式等待事件记录等待时间的功能，默认为offtrack_counts统计数据库活动，默认为ontrack_io_timing开启IO计时统计功能，默认为offtrack_functions开启函数统计功能，推荐用 'all'，默认为'none'sys_stat_statements.track跟踪统计SQL语句的访问，推荐用 'top'，默认为'none'sys_kwr.enable自动对收集到的数据生成快照并保存到kwr库里，默认为off

其他参数一般情况下使用默认值即可

sys_kwr.topnkwr报告显示topn条件记录，默认20条sys_kwr.history_dayskwr快照数据保留天数，默认8天sys_kwr.intervalkwr自动采集快照的间隔，默认60分钟sys_kwr.languageKWR报告使用语言，默认为中文（chinese 或 chn），可选为英文(english 或eng)sys_stat_statements.track_parsepg_stat_statements记录parse次数和时间，默认开启sys_stat_statements.track_planpg_stat_statements记录plan次数和时间，默认开启

86.4. 插件sys_kwr的使用方法 86.4.1. 概述
sys_kwr通过周期性自动记录性能统计相关的快照，分析出KES的操作系统运行环境、数据库时间组成、等待事件和TOP SQL等性能指标，为数据库性能调优提供指导。
1、SQL语句执行过程中产生的等待事件, IO 和执行时间
2、Top SQL
3、数据库对象统计信息
4、数据库实例统计信息
86.4.2. 自动快照
KingbaseES启动服务后，sys_kwr collector 后台进程后会每个小时采集一次负载信息，并保存到kwr库(test)。
查询快照列表

test=# select * from perf.kwr_snapshots; snap_id |snap_time| sess_count --------+------------------------+------------ 1 | 2021-12-07 17:51:02+08 |1 2 | 2021-12-07 17:51:03+08 |1 3 | 2021-12-07 17:51:04+08 |1 (3 rows)

86.4.3. 手动快照
手工快照通过SQL语句来执行

test=# select * from perf.create_snapshot(); create_snapshot ----------------- 5 (1 row)

86.4.4. 生成kwr报告
有了负载信息的快照数据后，就可以调用以下2个函数来生成kwr报告

select perf.kwr_report(start_id integer, end_id integer, format text = 'text'); select perf.kwr_report_to_file(start_id integer, end_id integer, formattext, file_path text); perf.kwr_report()生成报告并加报告内容自动保存到KingbaseES的data/sys_log目录下。perf.kwr_report_to_file()则生成报告并将内容保存指定的file_path路径下。

函数参数说明

start_id起始快照IDend_id结束快照IDformat报告的格式，只支持'text'和'html'格式，建议使用'html'格式。file_path在服务器上保存报告文件的全路径，必须有写文件的权限。

86.4.5. 生成html报告

select * from perf.kwr_report(1,2,'html');

查看 KWR 报告，请参考 KWR 文档。

86.5. 插件sys_kwr卸载方法进入 Kingbase 创建插件
示例

drop extension sys_kwr;

86.6. 插件sys_kwr升级方法通过 alter extension 来升级插件。
示例，由 1.2 升级到 1.3

ALTER EXTENSION sys_kwr UPDATE TO '1.3';

87. sys_prewarm 87.1. 插件 sys_prewarm 简介插件 sys_prewarm 是 KingbaseES 的一个扩展插件。提供了一种方便的方法把关系数据载入到操作系统缓冲区或者 KES 缓冲区。可以使用 sys_prewarm 函数手工执行预热，或者通过在 shared_preload_libraries 中包括 sys_prewarm 来自动执行预热。在后一种情况中，系统将运行一个后台工作者 autoprewarm master，它会周期性地把共享内存中的内容记录在一个名为 autoprewarm.blocks 的文件中，并且在重新启动后用两个后台工作者重新载入那些块。

插件名为 sys_prewarm
插件版本 V1.2

87.2. 插件 sys_prewarm 加载方式通过 create extension 来加载插件。
示例：

create extension sys_prewarm;

如果使用自动预热，则还需要设置 shared_preload_libraries：

shared_preload_libraries = 'sys_prewarm'

87.3. 插件 sys_prewarm 的参数配置手工预热无需配置任何参数。
自动预热包括 2 个参数：
sys_prewarm.autoprewarm (boolean)

控制服务器是否应该运行 autoprewarm 工作者。默认这个参数为 on。这个参数只能在服务器启动时设置。

sys_prewarm.autoprewarm_interval (int)

这是更新 autoprewarm.blocks 的间隔。默认是 300 秒。如果被设置为 0，该文件将不会以常规的间隔方式转储，而是只在服务器关闭时转储。

87.4. 插件 sys_prewarm 的使用方法 KingbaseES 加载 sys_prewarm 插件后，通过函数来对关系表进行手工预热或自动预热。
手工预热使用 sys_prewarm() 函数：

sys_prewarm(regclass, mode text default 'buffer', fork text default 'main', first_block int8 default null, last_block int8 default null) RETURNS int8

该函数第一个参数是要预热的关系。第二个参数是要使用的预热方法（prefetch、read 或者 buffer）。第三个参数是要被预热的关系分叉，通常是 main。第四个参数是要预热的第一个块号（NULL等同于零）。第五个参数是要预热的最后一个块号（NULL表示一直预热到关系的最后一个块）。返回值是被预热的块数。
手工预热示例：

select sys_prewarm('t1');

自动预热使用以下 2 个函数：

autoprewarm_start_worker() RETURNS void

该函数启动主要的autoprewarm工作者。这通常将会自动发生，但是如果没有在服务器启动时配置自动预热并且用户希望在稍晚的时候启动该工作者，这个函数就能发挥作用。

autoprewarm_dump_now() RETURNS int8

该函数立即更新 autoprewarm.blocks。如果 autoprewarm 工作者没有运行但用户希望它在下一次重启后运行，则这个函数会很有用。返回值是写入到 autoprewarm.blocks 中的记录数。
87.5. 插件 sys_prewarm 卸载方法通过 drop extension 来卸载插件。
示例：