MatrixGate 参数

本文档介绍了 MatrixGate 的详细参数信息。

1 配置文件参数

注意!
此部分的参数为 mxgate 启动前生成的配置文件中的参数。

参数名 默认值 描述
[database]类别
--db-database postgres MatrixGate 连接 YMatrix 数据库名
--db-master-host 本机主机名 MatrixGate 连接 YMatrix 主机名
--db-master-port 5432 MatrixGate 连接 YMatrix 主机端口号
--db-user 当前系统用户名 MatrixGate 连接 YMatrix 用户名
注意! 该用户必须具有创建外部表的权限,如果使用的是非超级权限用户,请使用如下命令增加权限:
alter user {username} CREATEEXTTABLE;
--db-password MatrixGate 连接 YMatrix 用户密码
--db-max-conn 10 MatrixGate 连接 YMatrix 最大连接数
[job]类别
--allow-dynamic false 当指定 --allow-dynamic=true 时,允许根据 POST 的数据内容(第一行),动态适配插入的目标表。此选项应仅用于 MatrixGate 启动时目标表名尚未确定的场景。如果固定插入某个已知的目标表,推荐用 --target 显式指定表名
--delimiter | 指定用于分隔文件每一行(行)中各列的字符
--error-handling accurate 遇到格式错误行的处理方式
'accurate':错误数据不入库并记录错误日志,该批次其他数据不受影响
'legacy':该批次整体失败
--exclude-columns 数据加载默认提供的列数量和列顺序需要与表定义一致,当数据加载仅提供部分列时,--exclude-columns 用于标记排除的列名,其他列仍需要保证顺序与表定义一致。 提示:如果已经开启 --use-auto-increment 跳过自增字段,则不需要在此列出这些自增字段。这个参数只需要标记出其他还需要排除的列名即可
--format text 指定源数据的数据格式 textcsvtext 速度最快,但不支持字符类型中出现换行。csv 格式适用性更广,对字符类型的列必须用双引号
--null-as 空字符串 指定表示空值的字符串。 默认值为无引号的空字符串。当数据表中的列约束为非空 NOT NULL,且数据内容上该列给出了空值,将会导致加载报错。提示:如需要使用 \N 为空值,需要对反斜杠进行转义,如:--null-as \N
--time-format unix-second 指定时间戳单位:unix-second \| unix-ms\|unix-nano \| raw。\n MatrixGate默认将每行数据的第一列当作时间戳的 Unix 表示,自动将其转化为数据库时间格式。如果时间戳不在第一列,或者用户已经自行转换为数据库格式,则应使用 raw,这样 MatrixGate 不会做时间类型转换
--upsert-key 进行 UPSERT 的键名,可以指定多个。
需要做 UPSERT 的表,必须建立 UNIQUE 约束,且参数中要指定所有约束键
--deduplicate-key 用法和 UPSERT 类似,区别是只更新空值,如果旧值非空,新值丢弃。
和 --upsert-key 参数互斥,只能选一种
--use-auto-increment true 当 target 表中含有自增字段时,是否在加载数据中跳过自增字段赋值而使用系统默认自增值
--target schemaName.tableName 指定目标的表名,schemaName 可以省略,默认为 public。允许指定多个目标表,使用方法是 "--target 表1 --target 表2 …"。当不提供此参数时,可以额外指定 --allow-dynamic 参数来允许动态适配表名
--dml-template 将 JSON 字段映射到元组列(Tuple Column)的映射模板的文件路径
[misc]类别
--log-archive-hours 72 日志目录下,超过一定时间未发生改变的 MatrixGate 日志文件,被自动压缩
--log-compress true 是否开启 log 自动压缩的全局开关
--log-dir /home/mxadmin/gpAdminLogs 日志目录
--log-max-archive-files 0 最多保留多少个压缩的 log 文件,超过这个数量,则最老的日志文件会被删除。0 为不删除
--log-remove-after-days 0 被压缩后的 log 文件,再经过多少天被自动删除。0 为不删除
--log-rotate-size-mb 100 当前 log 文件超过一定大小则自动切换到一个新文件,旧文件则立即压缩
-v / --verbose 打印详细的 verbose 日志
-V / --debug 打印详细的调试日志(包含 verbose 日志及 debug 日志)
--pprof-port 访问 Pprof 信息的端口,0 表示禁用
--no-cleanup 即使在正常退出时也保留临时模式
--grpc-port 访问 gRPC 信息的端口,0 表示禁用
[metrics]类别
--metrics-enable true 启用指标
--metrics-sample-interval 15(从 v5.3.2 调整为 15,之前为 3) 指标的采样间隔(秒)。将其设置为 >0 以启用指标收集(会降低性能)
[source]类别
--source http MatrixGate 数据来源,支持 http / stdin / kafka / transfer / grpc
[source]类别 [HTTP] 注意:此模式为配置文件中的默认数据源连接模式
--http-port 8086 MatrixGate 用户提交数据的 HTTP 接口
--max-body-bytes 4194304 每个 HTTP 包体大小上限
--max-concurrency 40000 HTTP 最大并发连接数
--request-timeout 0 请求超时时间,默认 0。当设置大于 0 的值,会在等待毫秒单位的设置时间后超时并返回 timeout(408)
--disable-keep-alive false MatrixGate 在每次 HTTP 请求后强制断开连接
--http-debug false 输出附加 HTTP 源的诊断信息
[source]类别 [Transfer] 注意:迁移模式非默认模式,如需使用此模式,请手动配置此部分参数
--src-host 源库 Master 的 IP 地址
--src-port 源库 Master 的端口号
--src-user 连接源库的用户名(建议使用 Superuser)
--src-password 连接密码
--src-schema 源表的模式名
--src-table 源表的表名
--src-sql 进行迁移数据过滤的 SQL
--compress 数据从源数据库 Segment 传输到本数据库的压缩方法:
空白字符串“”,代表不压缩,明文传输
gzip:使用 gzip 压缩,需要源数据库的 Segment 主机上必须安装有 gzip 这个 Linux 命令
lz4:使用 lz4 压缩,需要源数据库的 Segment 主机上必须安装有 lz4 这个 Linux 命令
推荐 lz4 > gzip > 不压缩
--port-base 9129 传输中会占用一个端口
--local-ip 必须用源库可以连接到本机的 IP 地址
[transform]类别
--transform plain 将写入的数据进行格式或类型转换。支持 plain / json / nil / tsbs / hanagdbc
[writer]类别
--interval 100 毫秒 MatrixGate 执行批量数据加载时间周期
--writer stream MatrixGate 通过 Writer 将数据写入到 YMatrix。支持 stream / nil

--stream-prepared
10 在一个任务(Job)中同时调用几个 slot 进程
--stream-host mdw YMatrix 中 Master 连接到 MatrixGate 的主机名。这是为了系统有多个网络接口
--use-gzip auto MatrixGate 向 Segment 发送数据时是否开启压缩,可配置参数为 auto/yes/no
auto 设置下优先选用 zstd 压缩算法;
设为 --use-gzip=yes 意味着使用 gzip 压缩算法
设为 --use-gzip=no,则会禁止压缩传输。此设置虽能节省少量 CPU 占用,但是会大大增加网络传输数据量,我们建议除非为单机部署的数据库,且 mxgate 和数据库全部在同一台主机上,否则慎用 no 设置,一律采用默认值 auto 即可
--max-seg-conn 128 外部表从 MatrixGate 拉取数据时启动的 Segment 数量,调大该参数会增加网络连接资源
--timing false 将该参数设置为 true 后,MatrixGate 在记录日志时会为每条 INSERT 增加耗时信息
--insert-timeout 600000 MatrixGate 执行 INSERT 语句超时时间。
设置大于 0 的值后会在等待毫秒单位配置时间后超时
-I / --instrumentation disable 打开 slot(s) 的检测,支持 disable / single / all 选项:
disable 表示禁用此功能;
single 表示只打开 slot[0] 的检测;
all 表示打开所有 slot 的检测

--bytes-limit
批量数据加载的的大小限制。在输入到 MatrixGate 的数据流不均匀的情况下,保障入库数据均匀。此功能默认不启用,若启用需要手动配置大小,取值范围为 0~INT_MAX

--auto-tune
false 将该参数设置为 true 后,MatrixGate 可以调整写入任务的 slot 数

--abort-by-pause-timeout
10000 在任务(Job)被执行暂停(Pause)命令后, 一旦达到该参数中所指定的超时时间,则自动放弃内存堆积的将要写入到数据库的数据。此参数取值范围为 0~INT_MAX;推荐取值 1000~10000,单位为毫秒(ms);如果设置为 0,则禁用此功能。建议配置此值明显低于 --request-timeout,以保证任务未处于暂停状态时,仍然使用 --request-timeout 为超时时间。一旦任务被暂停,mxgate 就会自动比对以上所述两个超时参数,并依照其中较低的值触发超时报错。该参数只有在 writer="stream" 时才可配置

2 命令行参数

注意!
此部分参数为 mxgate 启动后可在命令行中运行的参数。

参数名 子参数名 描述
run 在命令行运行 MatrixGate
start 启动 MatrixGate 后台进程
stop 终止 MatrixGate 后台进程
-f / --force 强制终止 MatrixGate 进程
--grpc-port 通过发送 gRPC 请求终止正在监听指定端口的 MatrixGate 进程
status 打印 MatrixGate 后台进程的状态
config 打印完整的配置文件
log 显示最新的 10 条日志
-n / --lines int 指定显示最新的多少条日志,不可以省略后跟 int 参数
version 显示版本
help 显示用法和参数列表
-C / --config 加载配置文件,目前支持作为 start / run 的子参数运行
-p / --pid MatrixGate 进程的 ID,目前支持作为 stop / log / watch / pause / resume 的子参数运行
--job 需要设置参数的任务(Job)。由于每个 Job 都存在于一个表中,因此实际应用中指定相应表名即可,目前支持作为 stop / log / watch / pause / resume 的子参数运行
set --stream-prepared-cli 设置写入任务(Job)中活跃写入 slot 的数量
࠾ --stream-prepared-cli 默认值为 10
࠾ 示例:mxgate set --stream-prepared-cli 3
--job-interval设置写入任务的 ETL(Extract-Transform-Load)工作时间(单位为毫秒,ms)
࠾ --job-interval 默认值为 100
࠾ 示例:mxgate set --job-interval 150
--high-water-mark设置目标任务的(写入负载)高水位阈值
࠾ --high-water-mark 默认值为 0
࠾ 示例:mxgate set --high-water-mark 20
--disable-high-water-mark设置是否禁用高水位阈值
࠾ --disable-high-water-mark 默认值为 false
࠾ 示例:mxgate set --disable-high-water-mark=true

--auto-tune
设置是否启用自动调节 slot 数的功能
࠾ 开启所有任务的此功能:mxgate set --auto-tune=true
࠾ 关闭所有任务的此功能:mxgate set --auto-tune=false
࠾ 开启指定任务的此功能:mxgate set --auto-tune=true --job public.t1
get --stream-prepared-get 获取写入任务(Job)中写入 slot 的数量
࠾ 示例:mxgate get --stream-prepared-get
--stream-status-get获取写入任务中写入 slot 的状态
࠾ 示例:mxgate get --stream-status-get
--job-interval-get获取写入任务的工作时间
࠾ 示例:mxgate get --job-interval-get
--job-list获取所有的写入任务信息
࠾ 示例:mxgate get --job-list
--job-state获取所有的写入任务状态
࠾ 示例:mxgate get --job-state
--current-config获取当前 MatrixGate 进程的配置
࠾ 示例:mxgate get --current-config
--kafka-topics获取所有的测试主题(Kafka Topic)
࠾ 示例:mxgate get --kafka-topics
--kafka-messages获取某一 Kafka Topic 的所有消息(Messages)
࠾ 示例:mxgate get --kafka-messages
--source-pressure获取目标任务对应的源端数据写入负载
࠾ 示例:mxgate get --source-pressure
--high-water-mark-get获取为目标任务设定的(写入负载)高水位阈值
࠾ 示例:mxgate get --high-water-mark-get

--auto-tune-status
获取写入任务自动调节 slot 数量的状态
࠾ 获取所有写入任务自动调节 slot 数量的状态:mxgate get --auto-tune-status
࠾ 获取指定任务自动调节 slot 数量的状态:mxgate get --auto-tune-status --job public.t1
pause -X / --disconnect 暂停 mxgate 时,是否断开 Segment 和 mxgate 之间的 slot(这会导致中断所有 Job 的所有 slot)
࠾ 示例:mxgate pause -X
-S / --sync 不特别运行此子参数的情况下,mxgate 将执行异步暂停;当显式配置此子参数,mxgate 将等待所有数据写入任务(Job)暂停完成再返回结果
࠾ 示例:mxgate pause -S
resume-R / --reload 恢复写入时,是否重新加载任务的元数据
࠾ 示例:mxgate resume -R
watch
-D / --daemon-addr MatrixGate 进程的 gRPC 服务地址(host:port)
-i / --info 持续打印 mxgate watch 展示出来的相关指标每一列的含义
࠾ 示例:mxgate watch --info
-T / --time 指定相关监视指标的持续时间(单位为秒,s)
࠾ 默认值为 -1,即不间断打印
࠾ 示例:mxgate watch --time 200
-H / --history 显示历史指标
࠾ 示例:mxgate watch --history
--watch-latency 持续打印 Latency 相关监控指标
࠾ 示例:mxgate watch --watch-latency
--watch-start 查看历史启动记录,默认当前时间前 24 小时内,如 2022-04-11 11:09:20
࠾ 示例:mxgate watch --watch-start
--watch-end 查看历史终止记录,默认当前时间,如 2022-04-11 11:09:20
࠾ 示例:mxgate watch --watch-end
--watch-duration 查看历史时长
࠾ 示例:mxgate watch --watch-duration

注意!
MatrixGate 主要功能介绍请见 MatrixGate 主要功能