KWR插件介绍
SYS_KWR是KingbaseES自动负载信息库（Kingbase Auto Workload Repertories）的简称，它通过周期性自动记录性能统计相关的快照，分析出KingbaseES的操作系统运行环境、数据库时间组成、等待事件和TOP SQL等性能指标，为数据库性能调优提供指导。
KWR以插件的形式存在于KingbaseES产品中，目前最新版本是1.8。
KWR插件原理
KWR的基本原理：数据库实例运行过程中不断产生一些统计数据，比如对某个表的访问次数，数据页的内存命中次数，某个等待事件发生的次数和总时间，SQL语句的解析时间等，这些统计数据被一个叫做 KWR collector 的后台性能监控进程周期性地（默认每小时）自动采集，存储到KWR快照库里面，这些快照默认保存8天，到期后那些旧的快照被自动删除。
当出现性能问题的时候，可以通过指定时间段来查询相关快照列表，生成KWR报告，定位性能问题的根本原因。
其他性能组件比如 KDDM，基于 KWR 快照提供自动建议。
KWR相关进程
数据库服务启动后自动运行后台进程kwr collector，KWR collector 的后台性能监控进程周期性地（默认每小时）自动采集，存储到KWR快照库(select * from perf.kwr_snapshots)里面，这些快照默认保存8天，到期后那些旧的快照被自动删除。
KWR价值
KWR通过自动采集操作系统和数据库实例的性能数据，将其存储为KWR快照，并依此来生成KWR报告为DBA性能调优提供参考，其价值包括：
- 自动采集操作系统统计信息，不需要额外的性能监控工具。
- 感知数据库运行环境，排查数据库实例外部原因造成的性能问题。
- 通过统一的DB Time模型，度量数据库关键活动耗时。
- 通过query ID将SQL执行时间、等待时间和资源消耗关联起来，进行语句级分析。
- 从多个维度（时间、IO、内存、锁、实例、库对象等）分析数据库实例的性能问题。
- 自动生成快照，便于回溯之前发生的性能问题。
- 为KDDM等自动诊断和建议提供基础数据。
创建KWR插件
如果开启了KWR自动快照功能，会自动在kingbase库上创建该插件(默认配置文件中已加载该插件但是需要手动创建该插件)。可以通过SQL语句在目标库上创建：
test=# create extension sys_kwr;
CREATE EXTENSIONKWR依赖sys_stat_statements插件（1.11版本），该插件是内置插件，会在所有库上自动被创建(不用创建自己会创建)。
注意：KingbaseES由低版本升级至V009R001C002B0014后，需尽快将KWR插件升级至1.8版本，否则自动快照和手工快照功能将无法使用。
快速生成报告
确认KWR插件已创建
test=# \dx sys_kwr
List of installed extensions
Name | Version | Schema | Description
---------+---------+--------+--------------------------------------------------------
sys_kwr | 1.8 | public | KingbaseES auto workload repository and report builder
(1 row)如果未创建，执行以下步骤创建：
test=# create extension sys_kwr;
CREATE EXTENSION配置参数
配置文件 kingbase.conf，开启统计开关，其中 shared_preload_libraries 根据实际需要设置即可。
推荐参数如下：
vi /home/kingbase/KESV9/data/kingbase.conf
shared_preload_libraries = 'liboracle_parser, sys_kwr, sys_stat_statements'
track_sql = on
track_instance = on #KWR 1.3 新增参数
track_wait_timing = on
track_counts = on
track_io_timing = on
track_functions = 'all'
sys_stat_statements.track = 'top'
--重启数据库
sys_ctl restart -D /home/kingbase/KESV9/data/
--补充说明：
sys_kwr, sys_stat_statements默认就有说明：
shared_preload_libraries中sys_kwr, sys_stat_statements默认配置的有，liboracle_parser需要手动添加，因为KWR SQL里使用了字符串拼接语法，liboracle_parser起字符串拼接作用，若不添加会报以下错误：
创建快照 1
-- 创建快照 1
SELECT * FROM perf.create_snapshot(); 输出如下：
test=# select * from perf.create_snapshot();
create_snapshot
-----------------
1
(1 row)模拟业务操作
--执行一些SQL
SELECT count(*) FROM t1; 创建快照 2
---- 创建快照2
SELECT * FROM perf.create_snapshot(); 输出如下：
test=# SELECT * FROM perf.create_snapshot();
create_snapshot
-----------------
2
(1 row)生成全实例KWR报告
生成的KWR报告会自动保存到 DATA 目录下的 sys_log 子目录下，推荐使用HTML格式，因为它更便于阅读
KWR目前不能在Windows平台采集部分统计信息，报告中的内容会为空
场景1：TEXT版本格式
--生成全实例的TEXT版本报告
SELECT * FROM perf.kwr_report(1,2);
参数说明：
1：KWR快照起始编号
2：KWR快照结束编号
场景2：HTML版本格式
--生成全实例的HTML版报告
SELECT * FROM perf.kwr_report(1,2, 'html'); 
扩展：SQL 函数将生成的 html 文件保存到指定文件路径，生成全实例KWR报告
SELECT * FROM perf.kwr_report_to_file(1,2, 'html','/home/kingbase/kwr_kingbase_1_2.html');生成指定数据库的KWR报告
生成的KWR报告会自动保存到 DATA 目录下的 sys_log 子目录下，推荐使用HTML格式，因为它更便于阅读
场景1：TEXT版本格式
-- 生成指定数据库的TEXT版本报告，以kingbase为例
SELECT * FROM perf.kwr_report(1,2, 'text','kingbase');
参数说明：
1：KWR快照起始编号
2：KWR快照结束编号场景2：HTML版本格式
-- 生成指定数据库的HTML版报告，以kingbase为例
SELECT * FROM perf.kwr_report(1,2, 'html', 'kingbase'); 扩展：SQL 函数将生成的 html 文件保存到指定文件路径，生成指定数据库的KWR报告
test=# select * from perf.kwr_report_to_file(1, 2, 'html', '/home/kingbase/123.html', 'kingbase');
kwr_report_to_file
--------------------
t
(1 row)KWR的使用
配置GUC参数
内核统计模块相关的GUC参数
KWR依赖内核统计模块采集性能统计数据，建议开启以下GUC参数，否则KWR报告里会缺失部分内容：
track_sql = on
track_instance = on
track_wait_timing = on
track_counts = on
track_io_timing = on
track_functions = 'all'
sys_kwr.track_objects = off
sys_kwr.track_os = on -- KWR 1.4 新增参数
--参数说明：
track_sql：统计SQL时间、SQL等待事件、SQL IO，默认为off，建议开启。
track_instance：统计实例级IO、锁、关键活动，默认为off，建议开启。
track_wait_timing：统计累积式等待事件的时间，默认为on，建议开启。
track_counts：统计数据库活动，默认为on。
track_io_timing：统计IO耗时，默认为off，建议开启。
track_functions：统计用户自定义函数使用情况，默认为'none'，建议'all'。
sys_kwr.track_objects: 统计数据库对象使用情况，在sys_kwr1.7之前默认值为on，从sys_kwr1.7默认值更改为off，建议关闭。该参数需要手动添加。
sys_kwr.track_os: 统计系统数据，默认为on，建议开启。该参数需要手动添加。sys_stat_statements插件相关的GUC参数
KWR依赖sys_stat_statements插件采集TOP SQL统计数据，建议开启以下GUC参数，否则会提示警告，且部分报告（Top SQL）没有内容：
sys_stat_statements.track = 'top'
--参数说明：
sys_stat_statements.track: 设置 sys_stat_statements.track 控制哪个语句可以被该模块跟踪， 声明 'top' 来跟踪顶级（直接通过客户端发出）的语句，'all' 跟踪嵌套的语句，'none' 禁用语句状态收集。建议使用 'top'。能够跟踪客户端发出的SQL，包括JDBC访问数据库发出的语句KWR、KWR diff相关的GUC参数
sys_kwr.enable = on
sys_kwr.topn = 20
sys_kwr.history_days = 8
sys_kwr.interval = 60
sys_kwr.language = 'chinese' #KWR 1.3 新增参数
sys_kwr.database = 'kingbase' #KWR 1.8 新增参数
#sys_kwr.track_windows_os_info= on
--参数说明
sys_kwr.enable：开启kwr自动快照，默认为关。
sys_kwr.topn：显示kwr报告中排名前n条的信息，默认为20，最少为10，最多为100。
sys_kwr.history_days：快照保留日期，默认为8天，最少1天，最多1000天。
sys_kwr.interval：自动快照间隔，默认60分钟，最短10分钟，最长144000分钟（100天）。
sys_kwr.language：KWR报告、KWR diff报告使用语言，默认为中文（chinese 或 chn），可选为英文(english 或eng)。
sys_kwr.track_windows_os_info：Windows平台下是否跟踪操作系统统计信息，默认为on。开启该开关后，每次连接KWR插件所在数据库会消耗大约300毫秒来初始化Windows下的WMI库。
sys_kwr.database：KWR 1.8新增参数，用于指定自动快照的数据库。配置该参数后，自动快照进程会连接目标数据库，并周期性创建KWR快照，同时采集包括数据库对象在内的全部性能统计指标。
1：参数为text类型，区分大小写，仅可配置一个数据库。
2：参数默认值为'kingbase'，如果不设置，则系统仍然使用默认的kingbase库来创
建自动快照。注意事项
- 要打开自动快照功能，需要将sys_kwr.enable设置为on。
- 任何情况下都可以执行：SELECT * FROM perf.create_snapshot(); 来手工创建快照。
- 自动快照默认在kingbase库上创建 sys_kwr 插件，可以使用GUC参数
sys_kwr.database进行设置。 - shared_preload_libraries 里至少包含：sys_kwr, sys_stat_statements。
快照查询
test=# select * from perf.kwr_snapshots;
snap_id | snap_time | sess_count | snap_version
---------+------------------------+------------+--------------
1 | 2025-01-07 10:38:38+08 | 1 | 1.8
2 | 2025-01-07 11:45:07+08 | 1 | 1.8
(2 rows)自动快照功能
只需要将sys_kwr.enable设置为true（需要重启服务器），就开启了自动快照功能。
后台进程 kwr collector每分钟检查最后一次快照的时间，跟当前的时间间隔是否大于sys_kwr.interval。如果大于则立刻创建新的快照，并更新最后快照时间。
如果本次自动快照没有创建成功，则在下一个检查周期（一分钟后）继续尝试创建快照。
手动快照管理
配置好相关的GUC参数后，执行perf.create_snapshot() 创建手工快照，返回新的快照号，同时也在perf.kwr_snapshots里添加一条记录。
创建快照
--创建快照
SELECT * FROM perf.create_snapshot(); 删除部分快照
--查询快照
select * from perf.kwr_snapshots;
--删除部分快照
SELECT * FROM perf.drop_snapshots(1, 2);
--查询快照
select * from perf.kwr_snapshots;清理全部快照
--查询快照
select * from perf.kwr_snapshots;
--删除部分快照
SELECT * FROM perf.reset_snapshots();
--查询快照，全部快照被清理
select * from perf.kwr_snapshots;生成KWR报告
场景1：生成全实例KWR报告
生成的KWR报告会自动保存到 DATA 目录下的 sys_log 子目录下，推荐使用HTML格式，因为它更便于阅读
格式1：TEXT版本格式
--查询快照
select * from perf.kwr_snapshots;
--生成全实例的TEXT版本报告
SELECT * FROM perf.kwr_report(4,5);
参数说明：
4：KWR快照起始编号
5：KWR快照结束编号
--磁盘上KWR报告文件位置
[kingbase@localhost ~]$ cd /home/kingbase/KESV9/data/
[kingbase@localhost data]$ cd sys_log
[kingbase@localhost sys_log]$ ls -l
......
-rw-------. 1 kingbase kingbase 90350 Jan 10 16:03 kwr_4_5_20250110_160323.txt
......
格式2：HTML版本格式
--查询快照
select * from perf.kwr_snapshots;
--生成全实例的HTML版报告
SELECT * FROM perf.kwr_report(4,5, 'html');
--磁盘上KWR报告文件位置
[kingbase@localhost ~]$ cd /home/kingbase/KESV9/data/
[kingbase@localhost data]$ cd sys_log
[kingbase@localhost sys_log]$ ls -l
......
-rw-------. 1 kingbase kingbase 177722 Jan 10 16:05 kwr_4_5_20250110_160533.html
......
扩展：SQL 函数将生成的 html 文件保存到指定文件路径，生成全实例KWR报告
SELECT * FROM perf.kwr_report_to_file(4,5, 'html','/home/kingbase/kwr_kingbase_4_5.html');场景2：生成指定数据库的KWR报告
生成的KWR报告会自动保存到 DATA 目录下的 sys_log 子目录下，推荐使用HTML格式，因为它更便于阅读
格式1：TEXT版本格式
-- 生成指定数据库的TEXT版本报告，以kingbase为例
SELECT * FROM perf.kwr_report(4,5, 'text','kingbase');
参数说明：
4：KWR快照起始编号
5：KWR快照结束编号
格式2：HTML版本格式
-- 生成指定数据库的HTML版报告，以kingbase为例
SELECT * FROM perf.kwr_report(4,5, 'html', 'kingbase');
--生成KWR报告保存到指定的磁盘目录下，用kwr_report_to_file()函数，第4个参数指定文件全路径，以kingbase为例
select * from perf.kwr_report_to_file(4, 5, 'html', '/home/kingbase/123.html', 'kingbase');
作者：董小姐yyds
Oracle 11g OCM，KCP,PGCE，墨天轮技术专家，青学会成员
擅长主流Oracle、MySQL、PG安装部署、故障定位处理、性能优化，
金仓、达梦、openGauss系等各种商用和开源国产数据库
微信:margaretdy
公众号：董小姐yyds
视频号：DongxiaojieYYDS
墨天轮：https://www.modb.pro/u/3121
CSDN：https://blog.csdn.net/qq961573863?type=blog
知乎：https://www.zhihu.com/people/fuwaxiaohuan
