一、概述
二、使用准备
三、使用示例
四、获取帮助
五、命令参考
六、常见问题处理
增量物化视图可以对物化视图增量刷新,需要用户手动执行语句完成对物化视图在一段时间内的增量数据刷新。与全量创建物化视图的不同在于目前增量物化视图所支持场景较小。目前物化视图创建语句仅支持基表扫描语句或者UNION ALL语句。
调优程序是一个独立于数据库内核之外的工具,需要提供数据库及其所在实例的用户名和登录密码信息,以便控制数据库执行benchmark进行性能测试;在启动调优程序前,要求用户测试环境交互正常,能够正常跑通benchmark测试脚本、能够正常连接数据库。
说明: 如果需要调优的参数中,包含重启数据库后才能使修改生效的参数,那么在调优过程中数据库将会重启多次。如果用户的数据库正在执行作业,请慎用train与tune模式。
调优程序X-Tuner包含三种运行模式,分别是:
须知: 如果在tune模式下,使用深度强化学习算法,要求必须有一个训练好的模型,且要求训练该模型时的参数与进行调优时的参数列表(包括max与min)必须一致。
图 1 X-Tuner结构图
X-Tuner的整体架构如图1 X-Tuner 结构图所示,系统可以分为:
说明: 应确保benchmark脚本跑分结果越大表示性能越好。例如TPC-H这种衡量SQL语句整体执行时长的benchmark,可以通过取总体执行时间的相反数作为benchmark的输出分数。
可以通过两种方式运行X-Tuner,一种是直接通过源码运行,另一种则是通过Python的setuptools将X-Tuner安装到系统上,而后直接通过gs_xtuner命令调用。下面分别介绍两种运行X-Tuner的方法。
方法一:直接通过源代码运行
在当前目录下可以看到 requirements.txt 等文件,通过pip包管理工具根据该 requirements.txt 文件安装依赖:
pip install -r requirements.txt
安装成功后需要添加环境变量PYTHONPATH,然后可执行main.py。以获取帮助信息为例,则可以执行:
cd tuner # 切换到 main.py 入口文件所在的目录
export PYTHONPATH='..' # 将上一级目录添加到寻找包的路径中
python main.py --help # 可以直接通过该命令执行获取帮助的动作,其他功能使用方法类似
方法二:将X-Tuner安装到系统中
执行下述命令,Python会通过自身的setuptools将本工具安装到Python环境中:
python setup.py install
如果Python的bin目录被添加到PATH环境变量中,则gs_xtuner命令也可以在任何地方被直接调用。
仍然以获取帮助信息为例,执行下述命令:
gs_xtuner --help
X-Tuner在运行前需要加载配置文件,该配置文件默认路径是 $INSTALL_DIR/tuner/xtuner.conf ,可以通过 gs_xtuner –help 命令查看默认加载的配置文件绝对路径:
...
-x TUNER_CONFIG_FILE, --tuner-config-file TUNER_CONFIG_FILE
This is the path of the core configuration file of the
X-Tuner. You can specify the path of the new
configuration file. The default path is /path/to/xtuner/xtuner.conf.
You can modify the configuration file to control the
tuning process.
...
修改配置文件的配置项可以指引X-Tuner执行不同的动作,用户可以根据自己的不同需求来修改配置文件的内容,配置文件的配置项说明详见表2。如果需要修改配置文件的加载路径,则可以通过选项 -x 命令行选项来指定。
Benchmark的驱动脚本存放路径为X-Tuner的benchmark子目录。X-Tuner自带常用的benchmark驱动脚本,例如基于时间周期的探测脚本(默认)、TPC-C、TPC-H等。X-Tuner通过调用benchmark/__init__.py文件中 get_benchmark_instance() 命令来加载不同的benchmark驱动脚本,获取benchmark驱动实例。其中,benchmark驱动脚本的格式说明如下:
下面分别介绍驱动脚本的内容三要素:
cmd变量:表示执行benchmark脚本需要运行的命令,可以直接在驱动脚本中修改,也可以通过配置文件的benchmark_cmd配置项来指定。cmd中的文本允许使用占位符,用于获取某些运行cmd命令时的必要信息,使用示例参见TPC-H驱动脚本示例。这些占位符包括:
run函数:该函数的函数签名为:
def run(remote_server, local_host) -> float:
其中,返回数据类型为float,表示benchmark执行后的评估分数值,要求该值越大表示性能越好,例如使用TPC-C跑分结果tpmC即可作为返回值,TPC-H的全部SQL语句执行总时间的相反数(取相反数后可保证返回值越大则性能越好)也可作为返回值。
remote_server 变量是X-Tuner 程序传递给脚本使用的远端主机(数据库宿主机)的shell命令接口,local_host 变量是X-Tuner 程序传递给脚本使用的本地主机(运行X-Tuner脚本的主机)的shell命令接口。上述shell命令接口提供的方法包括:
exec_command_sync(command, timeout)
功能:该方法用于在主机上执行shell命令。
参数列表:
command 必选,数据类型可以是str, 以及元素为str类型的list或tuple;
timeout 可选,表示命令执行的超时时长,单位是秒。
返回值:
返回二元组 (stdout, stderr),stdout表示标准输出流结果,stderr表示标准错误流结果,数据类型均为str.
exit_status
功能:该属性表示最近一条shell命令执行后的退出状态码(exit status code)。
说明:一般情况,退出状态码为0表示执行正常,非0表示存在错误。
Benchmark驱动脚本示例说明
TPC-C 驱动脚本
from tuner.exceptions import ExecutionError
# WARN: You need to download the benchmark-sql test tool to the system,
# replace the PostgreSQL JDBC driver with the openGauss driver,
# and configure the benchmark-sql configuration file.
# The program starts the test by running the following command:
path = '/path/to/benchmarksql/run' # TPC-C测试脚本benchmark-sql 的存放路径
cmd = "./runBenchmark.sh props.gs" # 自定义一个名为 props.gs 的benchmark-sql测试配置文件
def run(remote_server, local_host):
# 切换到 TPC-C 脚本目录下,清除历史错误日志,然后运行测试命令。
# 此处最好等待几秒钟,因为benchmark-sql 测试脚本生成最终测试报告是通过一个shell脚本实现的,整个过程会有延迟,
# 为了保证能够获取到最终的tpmC数值报告,我们这里选择等待3秒钟。
stdout, stderr = remote_server.exec_command_sync(['cd %s' % path, 'rm -rf benchmarksql-error.log', cmd, 'sleep 3'])
# 如果标准错误流中有数据,则报异常退出。
if len(stderr) > 0:
raise ExecutionError(stderr)
# 寻找最终tpmC结果
tpmC = None
split_string = stdout.split() # 对标准输出流结果进行分词。
for i, st in enumerate(split_string):
# 在5.0版本的benchmark-sql中,tpmC最终测试结果数值在 ‘(NewOrders)’关键字的后两位,正常情况下,找到该字段后直接返回即可。
if "(NewOrders)" in st:
tpmC = split_string[i + 2]
break
stdout, stderr = remote_server.exec_command_sync(
"cat %s/benchmarksql-error.log" % path)
nb_err = stdout.count("ERROR:") # 判断整个benchmark运行过程中,是否有报错,记录报错的错误数
return float(tpmC) - 10 * nb_err # 这里将报错的错误数作为一个惩罚项,惩罚系数为10,越高的惩罚系数表示越看中报错的数量.
TPC-H驱动脚本
import time
from tuner.exceptions import ExecutionError
# WARN: You need to import data into the database and SQL statements in the following path will be executed.
# The program automatically collects the total execution duration of these SQL statements.
path = '/path/to/tpch/queries' # 存放TPC-H测试用的SQL脚本目录
cmd = "gsql -U {user} -W {password} -d {db} -p {port} -f {file}" # 需要运行TPC-H测试脚本的命令,一般使用'gsql -f 脚本文件' 来运行
def run(remote_server, local_host):
# 遍历当前目录下所有的测试用例文件名
find_file_cmd = "find . -type f -name '*.sql'"
stdout, stderr = remote_server.exec_command_sync(['cd %s' % path, find_file_cmd])
if len(stderr) > 0:
raise ExecutionError(stderr)
files = stdout.strip().split('\n')
time_start = time.time()
for file in files:
# 使用 file 变量替换 {file},然后执行该命令行。
perform_cmd = cmd.format(file=file)
stdout, stderr = remote_server.exec_command_sync(['cd %s' % path, perform_cmd])
if len(stderr) > 0:
print(stderr)
# 代价为全部测试用例的执行总时长
cost = time.time() - time_start
# 取相反数,适配run 函数的定义:返回结果越大表示性能越好。
return - cost
X-Tuner支持三种模式,分别是获取参数诊断报告的recommend模式、训练强化学习模型的train模式以及使用算法进行调优的tune模式。上述三种模式可以通过命令行参数来区别,通过配置文件来指定具体的细节。
三种模式连接数据库的配置项是相同的,有两种方式:一种是直接通过命令行输入详细的连接信息,另一种是通过JSON格式的配置文件输入,下面分别对两种指定数据库连接信息的方法进行说明。
通过命令行指定:
分别传递 –db-name –db-user –port –host –host-user 参数,可选 –host-ssh-port 参数,例如:
gs_xtuner recommend --db-name postgres --db-user omm --port 5678 --host 192.168.1.100 --host-user omm
通过JSON格式的连接信息配置文件指定:
JSON配置文件的示例如下,并假设文件名为 connection.json:
{
"db_name": "postgres", # 数据库名
"db_user": "dba", # 登录到数据库上的用户名
"host": "127.0.0.1", # 数据库宿主机的IP地址
"host_user": "dba", # 登录到数据库宿主机的用户名
"port": 5432, # 数据库的侦听端口号
"ssh_port": 22 # 数据库宿主机的SSH侦听端口号
}
则可通过 -f connection.json 传递。
说明:
为了防止密码泄露,配置文件和命令行参数中默认都不包含密码信息,用户在输入上述连接信息后,程序会采用交互式的方式要求用户输数据库密码以及操作系统登录用户的密码。
对recommend 模式生效的配置项为 scenario,若为auto,则自动检测workload类型。
执行下述命令,获取诊断结果:
gs_xtuner recommend -f connection.json
则可以生成诊断报告如下:
图 1 recommend 模式生成的报告示意图
在上述报告中,推荐了该环境上的数据库参数配置,并进行了风险提示。报告同时生成了当前workload的特征信息,其中有几个特征是比较有参考意义的:
说明: recommend 模式会读取数据库中的pg_stat_database以及 pg_stat_bgwriter等系统表中的信息,需要登录到数据库上的用户具有足够的权限(建议为管理员权限,可通过alter user username sysadmin;授予username相应的权限)。 由于某些系统表会一直记录统计信息,这可能会对负载特征识别造成干扰,因此建议最好先清空某些系统表的统计信息,运行一段时间的workload后再使用recommend模式进行诊断,以便获得更准确的结果。使用如下命令清除统计信息:
select pg_stat_reset_shared('bgwriter');
select pg_stat_reset();
该模式是用来训练深度强化学习模型的,与该模式有关的配置项为:
tuning_list: 用户指定需要调哪些参数,如果不指定,则根据workload类型自动推荐应该调的参数列表。如需指定,则tuning_list 表示调优列表文件的路径。一个调优列表配置文件的文件内容示例如下:
{
"work_mem": {
"default": 65536,
"min": 65536,
"max": 655360,
"type": "int",
"restart": false
},
"shared_buffers": {
"default": 32000,
"min": 16000,
"max": 64000,
"type": "int",
"restart": true
},
"random_page_cost": {
"default": 4.0,
"min": 1.0,
"max": 4.0,
"type": "float",
"restart": false
},
"enable_nestloop": {
"default": true,
"type": "bool",
"restart": false
}
}
待上述配置项配置完成后,可以通过下述命令启动训练:
gs_xtuner train -f connection.json
训练完成后,会在配置项rl_model_path指定的目录中生成模型文件。
tune模式支持多种算法,包括基于强化学习(Reinforcement Learning, RL)的DDPG算法、基于全局搜索算法(Global OPtimization algorithm, GOP)算法的贝叶斯优化算法(Bayesian Optimization)以及粒子群算法(Particle Swarm Optimization, PSO)。
与tune模式相关的配置项为:
待上述配置项配置完成后,可以通过下述命令启动调优:
gs_xtuner tune -f connection.json
![]()
注意: 在使用tune和train 模式前,用户需要先导入benchmark所需数据并检查benchmark能否正常跑通。调优过程结束后,调优程序会自动恢复调优前的数据库参数配置。
启动调优程序之前,可以通过如下命令获取帮助信息:
gs_dbmind component xtuner --help
输出帮助信息结果如下:
usage: [-h] [--db-name DB_NAME] [--db-user DB_USER] [--port PORT]
[--host HOST] [--host-user HOST_USER]
[--host-ssh-port HOST_SSH_PORT] [-f DB_CONFIG_FILE]
[-x TUNER_CONFIG_FILE] [-v]
{train,tune,recommend}
X-Tuner: a self-tuning tool integrated by openGauss.
positional arguments:
{train,tune,recommend}
Train a reinforcement learning model or tune database
by model. And also can recommend best_knobs according
to your workload.
optional arguments:
-h, --help show this help message and exit
-f DB_CONFIG_FILE, --db-config-file DB_CONFIG_FILE
You can pass a path of configuration file otherwise
you should enter database information by command
arguments manually. Please see the template file
share/server.json.template.
-x TUNER_CONFIG_FILE, --tuner-config-file TUNER_CONFIG_FILE
This is the path of the core configuration file of the
X-Tuner. You can specify the path of the new
configuration file. The default path is xtuner.conf.
You can modify the configuration file to control the
tuning process.
-v, --version show program's version number and exit
Database Connection Information:
--db-name DB_NAME The name of database where your workload running on.
--db-user DB_USER Use this user to login your database. Note that the
user must have sufficient permissions.
--port PORT Use this port to connect with the database.
--host HOST The IP address of your database installation host.
--host-user HOST_USER
The login user of your database installation host.
--host-ssh-port HOST_SSH_PORT
The SSH port of your database installation host.
表 1 命令行参数
参数 |
参数说明 |
取值范围 |
---|---|---|
mode |
指定调优程序运行的模式 |
train,tune,recommend |
–tuner-config-file, -x |
X-Tuner的核心参数配置文件路径,默认路径为安装目录下的xtuner.conf |
- |
–db-config-file, -f |
调优程序的用于登录到数据库宿主机上的连接信息配置文件路径,若通过该文件配置数据库连接信息,则下述数据库连接信息可省略 |
- |
–db-name |
指定需要调优的数据库名 |
- |
–db-user |
指定以何用户身份登陆到调优的数据库上 |
- |
–port |
数据库的侦听端口 |
- |
–host |
数据库实例的宿主机IP |
- |
–host-user |
指定以何用户身份登陆到数据库实例的宿主机上,要求改用户名的环境变量中可以找到gsql、gs_ctl等数据库运维工具。 |
- |
–host-ssh-port |
数据库实例所在宿主机的SSH端口号,可选,默认为22 |
- |
–help, -h |
返回帮助信息 |
- |
–version, -v |
返回当前工具版本号 |
- |
表 2 配置文件中的参数详解
参数名 |
参数说明 |
取值范围 |
---|---|---|
logfile |
生成的日志存放路径 |
- |
output_tuning_result |
可选,调优结果的保存路径 |
- |
verbose |
是否打印详情 |
on, off |
recorder_file |
调优中间信息的记录日志存放路径 |
- |
tune_strategy |
调优模式下采取哪种策略 |
rl, gop, auto |
drop_cache |
是否在每一个迭代轮次中进行drop cache,drop cache可以使benchmark跑分结果更加稳定。若启动该参数,则需要将登录的系统用户加入到 /etc/sudoers 列表中,同时为其增加 NOPASSWD 权限(由于该权限可能过高,建议临时启用该权限,调优结束后关闭)。 |
on, off |
used_mem_penalty_term |
数据库使用总内存的惩罚系数,用于防止通过无限量占用内存而换取的性能表现。该数值越大,惩罚力度越大。 |
建议0 ~ 1 |
rl_algorithm |
选择何种RL算法 |
ddpg |
rl_model_path |
RL模型保存或读取路径,包括保存目录名与文件名前缀。在train 模式下该路径用于保存模型,在tune模式下则用于读取模型文件 |
- |
rl_steps |
深度强化学习算法迭代的步数 |
- |
max_episode_steps |
每个回合的最大迭代步数 |
- |
test_episode |
使用RL算法进行调优模式的回合数 |
- |
gop_algorithm |
采取何种全局搜索算法 |
bayes, pso |
max_iterations |
全局搜索算法的最大迭代轮次(并非确定数值,可能会根据实际情况多跑若干轮) |
- |
particle_nums |
PSO算法下的粒子数量 |
- |
benchmark_script |
使用何种benchmark驱动脚本,该选项指定加载benchmark路径下同名文件,默认支持TPC-C、TPC-H等典型benchmark |
tpcc, tpch, tpcds, sysbench … |
benchmark_path |
benchmark 脚本的存储路径,若没有配置该选项,则使用benchmark驱动脚本中的配置 |
- |
benchmark_cmd |
启动benchmark 脚本的命令,若没有配置该选项,则使用benchmark驱动脚本中的配置 |
- |
benchmark_period |
仅对 period benchmark有效,表明整个benchmark的测试周期是多少,单位是秒 |
- |
scenario |
用户指定的当前workload所属的类型 |
tp, ap, htap |
tuning_list |
准备调优的参数列表文件,可参考 share/knobs.json.template 文件 |
- |
— END —