sys_kwr 介绍
sys_kwr 是 Kingbase Auto Workload Repertories 的简称，是 KingbaseES 的一个扩展插件，类似于oracle的awr。主要功能是通过周期性自动记录性能统计相关的快照，分析出 KingbaseES 的操作系统运行环境、数据库时间组成、等待事件和TOP SQL等性能指标，为数据库性能调优提供指导。包括：
1、SQL语句执行过程中产生的等待事件, IO 和执行时间
2、Top SQL
3、数据库对象统计信息
4、数据库实例统计信息
sys_kwr 基于性能快照提供的性能报告包括：KWR、KWR Diff、KSH、KDDM，本文主要讲述KWR、KSH的使用，详细资料可以参考《KingbaseES数据库性能调优指南》。
插件 sys_kwr 使用
插件sys_kwr安装
#查看预加载的共享库
kingbase=# show shared_preload_libraries ;
shared_preload_libraries
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------
synonym, plsql, force_view, kdb_flashback,plugin_debugger, plsql_plugin_debugger, plsql_plprofiler, kdb_ora_expr, sepapower, dblink, sys_kwr, sys_spacequota, sys_stat_statements, backtrace, kdb_utils_function, auto_bmr, sys_squeeze, src
_restrict
(1 行记录)
#查看库中已安装的插件
kingbase=# \dx
已安装扩展列表
名称 | 版本 | 架构模式 | 描述
---------------------+------+--------------+---------------------------------------------------------------------------------------------------------------------
dbms_ddl | 1.0 | sys | DBMS_DDL system package
dbms_output | 1.0 | sys | DBMS_OUTPUT system package
dbms_utility | 1.0 | sys | dbms_utility extension package
kdb_cast | 1.0 | sys | kdb_cast extension
kdb_charbyte | 1.0 | sys | module for type bpcharbyte and varcharbyte
kdb_license | 1.0 | pg_catalog | kdb_license extension
kdb_oracle_datatype | 1.8 | sys | kdb_oracle_datatype extension
kdb_tinyint | 1.0 | pg_catalog | Create a new data type tinyint and its functions operators and indexes
kingbase_version | 1.0 | pg_catalog | This is a utility that provides function related to version number, it is used to get the Kingbase version number.
owa_util | 1.0 | sys | owa_util system package
plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
plsql | 1.0 | pg_catalog | PL/SQL procedural language
src_restrict | 1.0 | src_restrict | src restrict plugin
sys_anon | 1.0 | anon | provides data masking functionality
sys_freespacemap | 1.3 | sys | examine the free space map (FSM)
sys_hm | 1.0 | pg_catalog | Kingbase Healthy Check
sys_stat_statements | 1.11 | public | track parsing, planning and execution statistics of all SQL statements executed
sysaudit | 1.0 | sysaudit | provides auditing functionality
sysmac | 1.0 | sysmac | Mac for Kingbase
xlog_record_read | 1.0 | pg_catalog | xlog_record_read functions
(20 行记录)
#安装插件
kingbase=# CREATE EXTENSION sys_kwr;
CREATE EXTENSION
kingbase=# \dx
已安装扩展列表
名称 | 版本 | 架构模式 | 描述
---------------------+------+--------------+---------------------------------------------------------------------------------------------------------------------
dbms_ddl | 1.0 | sys | DBMS_DDL system package
dbms_output | 1.0 | sys | DBMS_OUTPUT system package
dbms_utility | 1.0 | sys | dbms_utility extension package
kdb_cast | 1.0 | sys | kdb_cast extension
kdb_charbyte | 1.0 | sys | module for type bpcharbyte and varcharbyte
kdb_license | 1.0 | pg_catalog | kdb_license extension
kdb_oracle_datatype | 1.8 | sys | kdb_oracle_datatype extension
kdb_tinyint | 1.0 | pg_catalog | Create a new data type tinyint and its functions operators and indexes
kingbase_version | 1.0 | pg_catalog | This is a utility that provides function related to version number, it is used to get the Kingbase version number.
owa_util | 1.0 | sys | owa_util system package
plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
plsql | 1.0 | pg_catalog | PL/SQL procedural language
src_restrict | 1.0 | src_restrict | src restrict plugin
sys_anon | 1.0 | anon | provides data masking functionality
sys_freespacemap | 1.3 | sys | examine the free space map (FSM)
sys_hm | 1.0 | pg_catalog | Kingbase Healthy Check
sys_kwr | 1.8 | public | KingbaseES auto workload repository and report builder
sys_stat_statements | 1.11 | public | track parsing, planning and execution statistics of all SQL statements executed
sysaudit | 1.0 | sysaudit | provides auditing functionality
sysmac | 1.0 | sysmac | Mac for Kingbase
xlog_record_read | 1.0 | pg_catalog | xlog_record_read functions
(21 行记录)
kingbase=#
sys_kwr的参数配置
要想使用 KWR 的报告功能，建议在 kingbase.conf 里添加以下参数：
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统计，默认为 off track_instance：开启统计实例级别IO，关键活动，锁统计，默认为 off track_wait_timing：开启累积式等待事件记录等待时间的功能，默认为 on track_counts：统计数据库活动，默认为 on track_io_timing：开启IO计时统计功能，默认为 off track_functions：开启函数统计功能，推荐用 'all'，默认为 'none' sys_stat_statements.track：跟踪SQL语句统计，推荐用 'top'，默认为 'none' sys_kwr.enable：自动采集数据库性能快照，默认为 off
其他参数一般情况下使用默认值即可，说明如下:
sys_kwr.history_days：kwr快照数据保留天数，默认8天 sys_kwr.interval：kwr自动采集快照的间隔，默认60分钟 sys_kwr.language：kwr报告语言，默认为中文（chinese 或 chn），可选为英文(english 或eng) sys_kwr.database：KWR 1.8新增参数，用于指定自动快照的数据库。配置该参数后，自动快照进程会连接目标数据库，并周期性创建KWR快照，同时采集包括数据库对象在内的全部性能统计指标。 - 该参数为text类型，区分大小写，仅可配置一个数据库。 - 该参数默认值为'kingbase'，如果不设置，则系统仍然使用默认的kingbase库来创建自动快照。
快照管理
查看快照列表
KingbaseES启动服务后，kwr collector 后台进程默认会每个小时采集一次负载信息，并保存到perf.kwr_snapshots中。
kingbase=# SELECT * FROM perf.kwr_snapshots;
snap_id | snap_time | sess_count | snap_version
---------+------------------------+------------+--------------
1 | 2025-01-06 18:20:54+08 | 0 | 1.8
2 | 2025-01-06 19:20:55+08 | 1 | 1.8
(2 行记录)
手动生成快照
kingbase=# SELECT * FROM perf.create_snapshot();
create_snapshot
-----------------
3
(1 行记录)
kingbase=#
删除快照
快照在超过sys_kwr.history_days指定的天数后，会自动删除，也可以手动删除。
#删除部分快照：
SELECT * FROM perf.drop_snapshots(start_id, end_id);
start_id：起始快照ID。
end_id：结束快照ID。
#删除全部快照：
SELECT * FROM perf.reset_snapshots();
生成kwr报告
#perf.kwr_report()生成报告并将报告内容自动保存到KingbaseES的data/sys_log目录下。
SELECT * FROM perf.kwr_report(start_id integer, end_id integer, format text = 'text', database text = NULL);
#perf.kwr_report_to_file()则生成报告并将内容保存指定的file_path路径下。
SELECT * FROM perf.kwr_report_to_file(start_id integer, end_id integer, format text, file_path text, database text = NULL);
函数的参数说明如下：
start_id：起始快照ID。
end_id：结束快照ID。
format：报告的格式，只支持'text'和'html'格式，建议使用'html'格式。
file_path：在服务器上保存报告文件的路径，必须有写文件的权限。
database：用于设置按数据库展示性能指标报告，仅KWR 1.8及以上版本支持。
- 如果不指定该参数，报告将展示全实例的性能指标。
- 如果指定了该参数，报告则展示指定数据库的性能指标。
- 如果指定的database数据库不存在，系统会给出错误提示。
- 示例1：生成text格式的kwr报告
SELECT * FROM perf.kwr_report(1,2);
命令执行结果如下：
kingbase=# SELECT * FROM perf.kwr_report(1,2);
kwr_report
-------------------------------------------------------------------------------------------------------------------------
实例信息: +
+
按库展示 启动时间 发行版本 KWR版本 编译版本 +
---------------------------------------------------------------------------------------------------------------------- +
- 2025-01-06 18:20:54 KingbaseES V009R001C002B0014 1.8 1100651784c +
+
系统信息: +
+
主机名 平台 处理器型号 处理器数 核心数 槽位 内存 +
---------------------------------------------------------------------------------------------------------------------- +
node1 CentOS Linux 7 ... 11th Gen Intel(R) Core(TM... 2 2 1 3771 MB +
+
快照信息: +
+
快照 ID 快照时间 会话数 +
---------------------------------------------------------------------------------------------------------------------- +
Begin Snap 1 2025-01-06 18:20:54 0 +
End Snap 2 2025-01-06 19:20:55 1 +
Elapsed 60.02 (mins) +
DB Time 0.15 (mins) +
+
====================================================================================================================== +
+
负载分析: +
+
统计项 总值 每秒 每事务 每执行 +
---------------------------------------------------------------------------------------------------------------------- +
DB Time(s) 8.74 0.00 0.00 0.13 +
DB CPU(s) 8.74 0.00 0.00 0.13 +
Foreground Wait Time(s) 0.00 0.00 0.00 +
WAL Size(MB) 0.00 0.00 0.00 +
Blocks Hit 1199 0.33 0.34 +
Blocks Read 8 0.00 0.00 +
Blocks Dirty 1 0.00 0.00 +
Blocks Write 323 0.09 0.09 +
Blocks Read Size(MB) 0.06 0.00 0.00 +
Blocks Write Size(MB) 2.52 0.00 0.00 +
Parse Calls 67 0.02 0.02 +
Plan Calls 62 0.02 0.02 +
Execute Calls 67 0.02 0.02 +
Tuples Return 628305 174.48 180.70 +
Tuples Fetch 17469 4.85 5.02 +
Tuples Insert 1360 0.38 0.39 +
Tuples Update 170 0.05 0.05 +
Tuples Delete 396 0.11 0.11 +
Commits 3477 0.97 1.00 +
Rollbacks 0 0.00 0.00 +
Transactions 3477 0.97 - +
Logon 0 0.00 0.00 +
Logoff 0 0.00 0.00 +
DeadLock 0 0.00 0.00 +
+
实例效率百分比（目标 100%）: +
+
效率 百分比 +
---------------------------------------------------------------------------------------------------------------------- +
Buffer Hit % 99.34 +
Parse Reused % 0.00 +
Plan Reused % 7.00 +
Buffer NoWait % 100.00 +
WAL Buffer NoWait % 100.00 +
LightLock Hit % 100.00 +
--More--
执行命令后，会在屏幕上显示text格式的kwr报告，同时在KingbaseES的data/sys_log目录下生成text格式的报告。
[kingbase@node1 sys_log]$ ll 总用量 264 -rw------- 1 kingbase kingbase 849 11月 23 00:10 kingbase-2024-11-23_000752.log -rw------- 1 kingbase kingbase 1559 11月 23 20:33 kingbase-2024-11-23_001220.log -rw------- 1 kingbase kingbase 194 11月 30 22:43 kingbase-2024-11-24_000000.log -rw------- 1 kingbase kingbase 459 11月 30 22:43 kingbase-2024-11-25_000000.log -rw------- 1 kingbase kingbase 4725 1月 6 17:45 kingbase-2024-12-01_104539.log -rw------- 1 kingbase kingbase 15940 1月 6 18:20 kingbase-2024-12-02_000000.log -rw------- 1 kingbase kingbase 188 1月 6 18:20 kingbase-2025-01-06_182053.log -rw------- 1 kingbase kingbase 109930 1月 6 21:38 kwr_1_2_20250106_213819.txt <------这个文件
- 示例2：生成html格式的kwr报告
SELECT * FROM perf.kwr_report(1,2,'html');
命令执行后，不会在屏幕上显示html格式的kwr报告，会在KingbaseES的data/sys_log目录下生成html格式的报告。
[kingbase@node1 sys_log]$ ll 总用量 492 [kingbase@node1 sys_log]$ ll 总用量 384 -rw------- 1 kingbase kingbase 849 11月 23 00:10 kingbase-2024-11-23_000752.log -rw------- 1 kingbase kingbase 1559 11月 23 20:33 kingbase-2024-11-23_001220.log -rw------- 1 kingbase kingbase 194 11月 30 22:43 kingbase-2024-11-24_000000.log -rw------- 1 kingbase kingbase 459 11月 30 22:43 kingbase-2024-11-25_000000.log -rw------- 1 kingbase kingbase 4725 1月 6 17:45 kingbase-2024-12-01_104539.log -rw------- 1 kingbase kingbase 15940 1月 6 18:20 kingbase-2024-12-02_000000.log -rw------- 1 kingbase kingbase 188 1月 6 18:20 kingbase-2025-01-06_182053.log -rw------- 1 kingbase kingbase 109930 1月 6 21:38 kwr_1_2_20250106_213819.txt -rw------- 1 kingbase kingbase 230706 1月 6 21:49 kwr_1_2_20250106_214919.html <------这个文件
查看html格式的kwr报告
关于kwr报告的解读请参考官网文档《KingbaseES数据库性能调优指南》。
ksh
KSH 以每秒采样的方式进行会话和数据收集，并将采集数据放入共享内存中，采集的数据主要包括：会话、应用、等待事件、命令类型、QueryId等。其主要使用场景是：当前或历史某个时点，发生了什么样的异常，系统在执行/运行什么任务。类似于oracle的ash。
KSH的参数配置
KSH 功能相关的参数在 kingbase.conf 中的推荐设置：
shared_preload_libraries = 'liboracle_parser, sys_stat_statements, sys_kwr'
track_activities = on # default = on
sys_stat_statements.max = 10000 # default = 5000
sys_stat_statements.track = 'top' # default = none
sys_kwr.collect_ksh = on # default = off
sys_kwr.ringbuf_size = 200000 # default = 100000
sys_kwr.history_days = 3 # default = 8
sys_kwr.language = 'chinese' # default = ‘chinese’
参数的说明如下：
track_activities：跟踪活动会话的等待事件、执行SQL、状态等, 默认为 on sys_stat_statements.max：设置sys_stat_statement跟踪的最大语句数，默认条目数为 5000 条 sys_stat_statements.track：跟踪统计SQL语句的访问，默认为 'none' sys_kwr.collect_ksh：启用或禁用 KSH 数据收集，默认为 off sys_kwr.ringbuf_size：设置ksh ringbuf大小，默认大小为 100000 条 sys_kwr.history_days：设置最大的 KSH 历史数据存储，默认为 8 天 sys_kwr.language：KSH 报告展示中文/英语信息，默认为中文（chinese 或 chn），可选为英文(english 或eng)
注意：采集报告需要在开启：track_activities，并至少设定 sys_kwr.collect_ksh = on 的情况下才可以查看。开启该参数会有一定的性能损耗。
修改上面几个参数后不需要重启数据库，reload即可生效。执行：
[kingbase@node1 data]$ sys_ctl reload 服务器进程发出信号
查看ksh数据
#保存于内存 Ringbuf 的数据可以通过视图 perf.session_history 查看：
SELECT * FROM perf.session_history;
#保存于数据库的历史数据可以通过视图 perf.ksh_history 查看：
SELECT * FROM perf.ksh_history;
生成ksh报告
SELECT * FROM perf.ksh_report({start_ts}, {duration}, {slot_width}, {datebase});
SELECT * FROM perf.ksh_report_to_file({start_ts}, {duration}, {slot_width}, {file_path}, {format}, {datebase});
SELECT * FROM perf.ksh_report_by_snapshots({start_snapid}, {end_snapid}, {slot_width}, {format}, {datebase});
SELECT * FROM perf.ksh_report_to_file_by_snapshots({start_snapid}, {end_snapid}, {file_path}, {format}, {slot_width}, {datebase});
参数说明：
start_ts: 报告开始时间，默认为 当前时间 - 15分钟。 duration: 报告时长，默认为 15 分钟，最大不超过 60 分钟。 slot_width: 报告最小区间，输入 0 时系统自动计算最优区间。 start_snapid: 起始快照号。 end_snapid: 结束快照号。 file_path: 报告生成地址，示例：'/home/username/ksh_report.html'。 format: 报告生成格式，可选择 'html'和'text'两种格式。 datebase：指定生成报告的数据库，示例：'kingbase'。如果不指定该参数，则生成全部数据库的报告。
插件 sys_kwr 卸载
DROP EXTENSION sys_kwr;
插件sys_kwr升级
通过 alter extension 来升级插件。
示例，由 1.7 升级到 1.8:
ALTER EXTENSION sys_kwr UPDATE TO '1.8';
注意：插件sys_kwr不支持跨版本升级，例如：无法从1.6直接升级至1.8版本。
总结
sys_kwr 插件可以自动采集性能数据，并提供详细的性能报告，是我们全面诊断分析数据库的性能情况的好帮手。
关于作者：
专注于Oracle、MySQL、PG、OpenGauss和国产数据库的研究，热爱生活，热衷于分享数据库技术。
微信公众号：飞天online
墨天轮：https://www.modb.pro/u/15197
如有任何疑问，欢迎大家留言，共同进步~~~
最后修改时间：2025-01-07 09:50:11
「喜欢这篇文章，您的关注和赞赏是给作者最好的鼓励」
关注作者
【版权声明】本文为墨天轮用户原创内容，转载时必须标注文章的来源（墨天轮），文章链接，文章作者等基本信息，否则作者和墨天轮有权追究责任。如果您发现墨天轮中有涉嫌抄袭或者侵权的内容，欢迎发送邮件至：contact@modb.pro进行举报，并提供相关证据，一经查实，墨天轮将立刻删除相关内容。
