MatrixBench 快速上手

本文档介绍了 MatrixBench 的基本使用方法，包含以下内容：

环境准备
快速上手
示例
使用相关 FAQ

注意！
目前 mxbench 已开源，欢迎你的审阅与贡献，请点击此处阅读 README。

1 环境准备

1.1 YMatrix 集群

需要一个正常运行的 YMatrix 集群。

1.2 环境变量

由于 MatrixBench 需要调用 createdb，gpconfig，gpstop，因此需要你提前配置好相关环境变量，使这些命令可以正确执行。

具体的，需要执行 source <YMatrix 安装目录>/greenplum_path.sh，并正确设置以下环境变量：

PGHOST
PGPORT
PGUSER
PGPASSWORD
PGDATABASE
MASTER_DATA_DIRECTORY

此外，用户还可以试执行 createdb mxbench, gpconfig -s log_rotation_size, gpstop -rai 等命令，确保可以正确运行。

1.3 MatrixGate

你需要通过 MatrixGate（简称 mxgate）写入数据。mxgate 是是一款高性能流式数据加载服务器，位于 YMatrix 安装目录下的 bin/mxgate。更多相关信息请见 mxgate。

2 快速上手

如果想在个人开发机上快速试用 MatrixBench，可以使用配置文件或者命令行的方式运行 MatrixBench。

注意!
mxbench 支持多数据类型与特征，及组合式查询语句的实现，以下示例不包含上述两个功能的相关用法，如需请见基本功能。

2.1. 配置文件运行

可以使用以下配置文件，命名为 mxbench.conf，并运行 mxbench --config mxbench.conf。

注意!
benchmark-parallel 参数设置需要适应机器性能，建议小于或等于 CPU 核数。

[database]
  db-database = "testdb1"
  db-master-port = 5432

[global]
  # 略过询问是否重设参数步骤。如果设置为 true，则认为你已设置好数据库参数，mxbench 不再进行处理
  skip-set-gucs = true

  table-name = "table1"

  # 生成的 DDL， 参数设置建议，查询语句（Query）等文件的存放目录
  workspace = "/tmp/mxbench"

  table-name = "table1"

[benchmark]
  benchmark = "telematics"

  [benchmark.telematics]
    # 数组，查询并发度
    benchmark-parallel = [8]
    # 提供的 3 个查询：单车最新值，10 车最新值，单车明细
    benchmark-run-query-names = ["SINGLE_TAG_DETAIL_QUERY" ]
    # 每轮每条 Query 的跑的次数或时间，让时间生效需要将次数设置为 0，如下：
    benchmark-run-times = 0
    benchmark-runtime-in-second = "30"

2.2 命令行运行

还可以使用命令行运行 MatrixBench。运行以下命令就等同于以上述配置文件运行 MatrixBench。

mxbench run \
  --db-database "testdb1" \
  --db-master-host "localhost" \
  --db-master-port 5432 \
  --db-user "mxadmin" \
  --skip-set-gucs \
  --table-name "table1" \
  --benchmark "telematics" \
  --benchmark-run-query-names "SINGLE_TAG_DETAIL_QUERY" \
  --benchmark-parallel 8 \
  --benchmark-run-times 0 \
  --benchmark-runtime-in-second 30

3 示例

此部分给出了配置文件及命令行运行的示例。

3.1 示例配置文件

此部分我们提供了以下两种典型场景的示例配置文件：

超宽稀疏表生成数据并运行混合负载
从外部路径读取 DDL 文件建表，读取 CSV 文件写入数据，不进行查询

3.1.1 超宽稀疏表生成数据并运行混合负载

超宽稀疏表指的是指标数量多（列多），但每一行的数据多为空值的表，常见于需要大量指标搭建不同数据分析模型的场景。混合负载即数据写入与查询同时进行，数据写入通过 mxgate 工具完成。

  # 示例文件 1
[Database]
  db-database = "testdb2"
  db-master-port = 5432

[Global]
  # 开启进度查看功能，默认即为 true
  watch = true

  # 生成的 DDL， 参数最佳实践建议， 查询语句等文件的存放目录
  workspace = "/home/mxadmin/mxbench/workspace"

  # 数据写入和查询是否同时进行
  simultaneous-loading-and-query = true

  table-name = "table2"

  # 设备数
  tag-num = 20000
  # 指标数据类型，支持 int4, int8, float4, float8 四种类型
  metrics-type = "float8"
  # 指标数目，如果指标数大于 998，就把前 997 个作为简单列，
  # 其他的作为 JSON 存放在名为 ext 的列中
  total-metrics-count = 5000

  # 生成数据的起始时间戳，ts-end 必须晚于 ts-start，否则报错
  ts-start = "2022-04-19 00:00:00"
  ts-end = "2022-04-19 00:01:00"

[Generator]
  generator = "telematics"

  [generator.telematics]
    # 每个设备每个时间点的指标，分几条数据上传，最终在数据库被 UPSERT 成 1 个 Tuple
    generator-batch-size = 1
    # 延迟上传的数据生成比例（1～100），时间戳往前推 1 小时
    generator-disorder-ratio = 0
    # 生成数据的空值率（1～100）
    generator-empty-value-ratio = 90
    # 生成数据的随机度， 有 OFF / S / M / L 几档，默认关闭 "OFF"
    generator-randomness = "OFF"

[Writer]
  writer = "stdin"

[Benchmark]
  benchmark = "telematics"

  [benchmark.telematics]
    # 数组，查询并发度
    benchmark-parallel = [64]
    # 提供的 3 个查询：单车最新值，10 车最新值，单车明细
    benchmark-run-query-names = [ "SINGLE_TAG_LATEST_QUERY", "MULTI_TAG_LATEST_QUERY", "SINGLE_TAG_DETAIL_QUERY" ]
    # 每轮每条查询语句的跑的次数或时间，让时间生效需要将次数设置为 0，如下：
    benchmark-run-times = 0
    benchmark-runtime-in-second = "60"

3.1.2 从外部路径读取 DDL 文件建表，读取 CSV 文件写入数据，不进行查询

即从用户路径读取 DDL 文件完成建表，随后读取 CSV 文件写入数据。此示例场景可增加 mxbench 测试的自主性，如果你已有确定的 DDL，并准备好了测试数据，请仿照此示例进行测试。
此示例不进行查询操作，因此不会出现混合负载情况。

  # 示例文件 2
[Database]
  db-database = "testdb3"
  db-master-port = 5432

[Generator]
  # 从 CSV 文件中读取数据
  generator = "file"

  [generator.file]
    generator-file-paths = ["/home/mxadmin/mxbench/data.csv"]


[Global]

  table-name = "table3"

  watch = true
  workspace = "/home/mxadmin/mxbench/workspace"
  ddl-file-path = "/home/mxadmin/mxbench/ddl.sql"

[Writer]
  writer = "stdin"

[Benchmark]
  benchmark = "nil"

3.2 示例命令行

此部分我们提供了以下两种典型场景的示例运行命令：

超宽稀疏表生成数据并运行混合负载
从外部路径读取 DDL 文件建表，读取 CSV 文件写入数据，不进行查询

3.2.1 超宽稀疏表生成数据并运行混合负载

使用示例配置文件 1 运行 MatrixBench 相当于使用以下命令行运行 MatrixBench：

$ mxbench run \
  --db-database "testdb2" \
  --db-master-port 5432 \
  --db-user "mxadmin" \
  --workspace "/home/mxadmin/mxbench/workspace" \
  --simultaneous-loading-and-query \
  --table-name "table2" \
  --tag-num 25000 \
  --metrics-type "float8" \
  --total-metrics-count 5000 \
  --ts-start "2022-04-19 00:00:00" \
  --ts-end "2022-04-19 00:01:00" \
  --generator "telematics" \
  --generator-batch-size 1 \
  --generator-disorder-ratio 0 \
  --generator-empty-value-ratio 90 \
  --generator-randomness "OFF" \
  --writer "stdin" \
  --benchmark "telematics" \
  --benchmark-run-query-names "SINGLE_TAG_LATEST_QUERY" \
  --benchmark-run-query-names "MULTI_TAG_LATEST_QUERY" \
  --benchmark-run-query-names "SINGLE_TAG_DETAIL_QUERY" \
  --benchmark-parallel 64 \
  --benchmark-run-times 0 \
  --benchmark-runtime-in-second 60

3.2.2 从外部路径读取 DDL 文件建表，读取 CSV 文件写入数据，不进行查询

使用示例配置文件 2 运行 MatrixBench 相当于使用以下命令行运行 MatrixBench：

$ mxbench run \
  --db-database "testdb3" \
  --db-master-port 5432 \
  --workspace "/home/mxadmin/mxbench/workspace" \
  --ddl-file-path "/home/mxadmin/mxbench/ddl.sql" \
  --table-name "table3" \
  --generator "file" \
  --generator-file-paths "/home/mxadmin/mxbench/data.csv" \
  --writer "stdin" \
  --benchmark "nil"

使用相关 FAQ

只写入，不查询
将 Benchmark 设为 nil;
只查询，不写入
将 Generator 设为 nil;
写入和查询同时进行
Global 设置中 simultaneous-loading-and-query 为 true。
想要生成并 dump 出 CSV 数据文件
Global 设置中 dump 为 true，生成的文件在 workspace 设置的目录下的 unix-timestamp 目录中。
想要查看生成的 DDL 和查询语句
workspace 设置的目录下的 unix-timestamp 目录中。
想要运行定制 DDL
在 Global 设置中的 ddl-file-path 中填写 DDL 文件的绝对路径。
想要运行定制查询语句
在 telematics Benchmark 的 benchmark-custom-queries 中填写定制查询语句，需用 "" 将内容囊括起来。不支持随机参数。
不想采用系统建议的参数，保留现有参数运行 MatrixBench:
MatrixBench 检测到现有系统和建议参数有不一致时，会在标准输出中做提示，并且询问是否需要重设参数并启动数据库。输入 "N"，保留原有参数。 MatrixBench 这时还会再次确认是否继续运行 MatrixBench。选择 "Y"，继续运行。
对参数合法性有什么要求？ Global 配置里:

ts-end 必须晚于 ts-start；
table-name、schema-name 不为空;
tag-num 必须大于 0;
ts-step-in-second 不为 0。

注意！
MatrixBench 完整的命令行参数信息请见 MatrixBench 命令行参数；主要功能介绍请见 MatrixBench 主要功能;MatrixBench 进度信息与统计报告详解请见 MatrixBench 理解进度信息与统计报告。