国产化替代
文档
博客
新闻
关于我们
下载

YMatrix 文档

版本发布历史
系统需求

关于 YMatrix

快速上手

标准集群部署

数据建模

连接到数据库

数据写入

数据迁移

数据查询

运维监控

性能调优

故障诊断

参考指南

SQL 参考

常见问题（FAQ）

场景应用

MatrixGate 主要功能

本文档介绍了 MatrixGate 的主要功能。

注意！
编程语言接入 MatrixGate 请见数据写入 - 编程语言接入 MatrixGate。


1 MatrixGate 加载特殊类型

1.1 MatrixGate 加载 CSV 文件示例

  • 在 demo 数据库中创建表 csvtable。
demo=# CREATE TABLE csvtable (
       time TIMESTAMP WITH TIME ZONE,
       tagid INT,
       c1 INT,
       c2 INT,
       c3 INT
       )
       USING MARS3
       DISTRIBUTED BY (tagid)
       ORDER BY (time,tagid);

  • 编辑数据加载文件 data.csv，内容如下：

    1603777821|1|101|201|301
1603777822|2|102|202|302
1603777823|3|103|203|303

  • 启动 mxgate，指定 --source 参数为 stdin，目标表为已经存在的 csvtable，加载并行度为 2。示例中主机为 mdw。

    [mxadmin@mdw ~]$ mxgate \
--source stdin \
--db-database demo \
--db-master-host 127.0.0.1 \
--db-master-port 5432 \
--db-user mxadmin \
--time-format unix-second \
--delimiter "|" \
--target csvtable \
--parallel 2 < data.csv

  • 连接数据库查询数据是否加载成功。

demo=# SELECT * FROM csvtable ;
          time          | tagid | c1  | c2  | c3
------------------------+-------+-----+-----+-----
 2020-10-27 05:50:23+08 |     3 | 103 | 203 | 303
 2020-10-27 05:50:22+08 |     2 | 102 | 202 | 302
 2020-10-27 05:50:21+08 |     1 | 101 | 201 | 301

(3 rows)

1.2 MatrixGate 加载 JSON 字段示例

1.2.1 JSON

  • 创建表。

    demo=# CREATE TABLE json_test(
     id int,
     j json
     )
     USING MARS3
     ORDER BY (id);

  • 创建数据文件。 ~/json.csv

    1|"{""a"":10, ""b"":""xyz""}"

  • 加载 这里使用 stdin 模式为例，其他模式都一样。 关键在 --format csv。

    [mxadmin@mdw ~]$ mxgate \
--source stdin \
--db-database postgres \
--db-master-host 127.0.0.1 \
--db-master-port 7000 \
--db-user mxadmin \
--time-format raw \
--format csv \
--delimiter "|" \
--target json_test < ~/json.csv

  • 查看加载数据。

    demo=# SELECT * FROM json_test;
id |           j
----+-----------------------
1 | {"a":10, "b":"xyz"}
(1 row)

1.2.2 JSON 数组

  • 创建表。

    demo=# CREATE TABLE json_array_test(
     id int,
     j json
     )
     USING MARS3
     ORDER BY (id);

  • 创建数据文件 ~/json_array.csv。

    1|"{""{\""a\"":10, \""b\"":\""xyz\""}"",""{\""c\"": 10}""}"

  • 加载 mxgate。

    [mxadmin@mdw ~]$ mxgate \
--source stdin \
--db-database postgres \
--db-master-host 127.0.0.1 \
--db-master-port 7000 \
--db-user mxadmin \
--time-format raw \
--format csv \
--delimiter "|" \
--target json_array_test < ~/json_array.csv

  • 验证。

    demo=# SELECT * FROM json_array_test ;
id |                      j
----+---------------------------------------------
1 | {"{\"a\":10, \"b\":\"xyz\"}","{\"c\": 10}"}
(1 row)

注意！
因为 JSON 列包含引号等特殊字符，所以 mxgate 的 --format 参数必须为 CSV。


2 观测 mxgate 运行指标

watch 是 mxgate 的一个子命令，用一系列指标描述 mxgate daemon 运行情况。 watch 有两种模式：

  • 实时观测模式， 用类似 sar 的格式每隔 3 秒将 gate 的各项指标打印在控制台。
  • 历史观测模式，可以指定任意时间段，任意时间周期（例如昨天的每个小时，上个月的每一天，去年的每一个月）统计导入速度。

2.1 实时观测

[mxadmin@mdw ~]$ mxgate watch

会每三秒收集 mxgate 的运行指标，输出结果如下

                 Time          WCount          ICount        WSpeed/s        ISpeed/s  WBandWidth MB/S     BlocakItems
  2022-04-28 15:20:58        14478858        14527011         2598081         2627887            2395               0
  2022-04-28 15:21:01        22231035        22633254         2584059         2702081            2222               0
  2022-04-28 15:21:04        30494310        30500874         2754425         2622540            3551               0
  2022-04-28 15:21:07        38004210        38032956         2503300         2510694            2862               0
  2022-04-28 15:21:10        46188696        46298223         2728162         2755089            2227               0
  ...

可通过 --info 参数来获取上述各个指标的说明

[mxadmin@mdw ~]$ mxgate watch --info

默认情况下只会输出速度指标，可通过 --watch-latency 参数来观测时间指标用于分析问题

[mxadmin@mdw ~]$ mxgate watch --watch-latency

2.2 历史数据观测

[mxadmin@mdw ~]$ mxgate watch --history

会计算截至当前时间为止，24小时内的每小时的平均速度，输出结果如下

                TIME RANGE                | SPEED/S  | BANDWIDTH MB/S  | BLOCK ITEMS
  2022-04-28 16:00:00-2022-04-28 17:00:00 |  2208010 |         1254.48 |           0
  2022-04-28 17:00:00-2022-04-28 18:00:00 |  1157920 |         1327.00 |           0
  2022-04-28 18:00:00-2022-04-28 19:00:00 |  2228666 |         2162.32 |           0
  2022-04-28 19:00:00-2022-04-28 20:00:00 |  1371092 |         2881.30 |           0
  2022-04-28 20:00:00-2022-04-28 21:00:00 |  1575320 |         2608.20 |           0

其中 SPEED/S,BANDWIDTH MB/S 代表导入的条目速度与导入带宽（MB/s 为单位）, BLOCK ITEMS 代表阻塞在 mxgate 的数据量，当数据库消费速度跟不上数据源（http，kafka 等）生产速度时，这个值会上升

可以添加 --watch-start，--watch-end，--watch-duration 参数来控制观测历史数据的时间区间与周期 例如

[mxadmin@mdw ~]$ mxgate watch --history --watch-start '2022-03-27 00:00:00' --watch-end '2022-04-27 00:00:00' --watch-duration '168h'

可以获得从 3 月 27 日到 4 月 27 日每周(每 168h)平均导入速度 其中 --watch-duration 支持 h m s 三种单位


3 不停机更新并行写入

mxgate 支持在不停止运行的情况下，修改并行加载参数 --stream-prepared、--interval：

  • --stream-prepared 代表的是 mxgate 向 YMatrix 每张表写入数据时活跃 slot 的数量，默认所有表的 slot 数量相同，可手动针对单个任务（Job）调节（每张表只能有一个任务）。
    • 增加 --stream-prepared 值，往往意味着提高数据写入的并发度，进而提升性能，同时也会占用更多的内存资源。
    • 减少 --stream-prepared 值，则可以减少数据节点（Segment）内存资源的占用，但性能也会随之降低。
  • --interval 代表的是每个活跃 slot 的工作间隔时间，即每个 slot 等待 --interval（以毫秒为单位，ms）的时间后，将该时间段内 mxgate 接收到的数据发送到 YMatrix。
    • 增加 --interval 的值，意味着每个 slot 每次写入数据的延迟会增加，每次写入的数据量会加大（前提是有数据源源不断地流入 mxgate）。
    • 减少 --interval 的值，则延迟减少，数据量也降低。

综上，在生产实践中，上述两个参数需要配合不同的存储引擎和用户对数据写入实时性的要求进行合理的调整。

具体用法示例如下：

  • 设置每个表的 slot 数量为 3
    $ mxgate set --stream-prepared-cli 3
  • 获取每个表活跃 slot 数量
    $ mxgate get --stream-prepared-get
  • 设置所有表 slot 的时间间隔为 200ms
    $ mxgate set --job-interval 200
  • 获取所有表的 slot 当前的时间间隔
    $ mxgate get --job-interval-get

注意！
对于以上参数，如果你想设置或获取某个特定表的 slot 数量或工作时间，那么在上述命令后加 --job <名称> 即可。每个任务对应一张数据库表，job 参数结构由模式名与表名组成，意思就是如果你的特定表叫做 test_table，模式名为 public，那么完成指定就需要在已有命令后加上 --job public.test_table 就是对的。


4 不停机更新表结构

在数据加载中，由于时序数据源越来越丰富，之前设定的表结构对于现在场景可能不再适用，因而就有了修改表结构的需求。此节将会说明，mxgate 如何在不停机的情况下，暂停数据写入、重载表元信息以及恢复数据写入。具体步骤如下：

  • 首先，使用命令 mxgate pause -X 中断所有表的 slot，为修改数据库表结构作准备。其中 -X 参数是必要的，它会帮助中断 mxgate 和数据库之间的 slot。如果不中断 slot，是无法对数据库表进行修改的。除了 -X 之外，运用 -S 参数可以令 pause 命会同步等待所有 slot 中断完成再返回。
$ mxgate pause -X
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
begin to pause all jobs，please wait...
  • 其次，中断对应表的所有 slot 之后，即可以对数据库对应的数据库表执行修改结构的操作，如增加若干列，删除若干列，删除已有表，重新创建“同名”的新表。

注意！ 重建的表结构可以不同，但“表名”必须保持一致。

  • 最后，使用命令 mxgate resume -R 恢复所有表的 slot，重载数据表的元信息。其中 -R 参数是必需的，resume 与 -R 将组合完成重载操作。

    $ mxgate resume -R
******************************************************
__  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
Version: v5.2.0
Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
begin to reload all jobs，please wait...

  • 特别地，多个 mxgate 进程同时运行的情况，需要 -p 参数表示对应 mxgate 进程的进程号，上述所有命令都是同理，例如：

    $ mxgate get --job-interval-get -p 70199 --job

注意！
执行重载命令的前提是 mxgate 的对应的表的所有 slot 必须先被暂停，否则会出现如下报错：jobs are not paused，please pause them first

注意！
pause 动作如果超时（50 秒），则取消对应 Slot 的插入操作，以确保 pause 操作可以正常完成。


5 UPSERT 功能支持

YMatrix 从 v4.2.0 实现了 MatrixGate 的 UPSERT 功能。详见 数据分批合并场景（UPSERT）。


6 单表迁移

YMatrix 从 v4.3.0 实现了 MatrixGate 的单表迁移功能。详见 单表迁移。

注意！
YMatrix 不仅支持单表迁移，也支持全库迁移（v4.7.0 及以上）。详见 全库迁移。


7 不停机更新日志级别

我们有时需要打开 mxgate 的 debug 日志来观测一些关键信息，但是打开或者关闭 debug 日志都需要重启 mxgate，并不利于定位问题。因此， YMatrix 提供了动态变更 mxgate 日志级别的功能:

  • 在 gate 运行的时候，使用命令 mxgate set --log-level VERBOSE 开启信息比较完整的 VERBOSE 级别的日志或者 mxgate set --log-level DEBUG 开启信息最完整的 DEBUG 级别的日志，等不需要在观察 debug 日志的时候，可以通过 mxgate set --log-level INFO,恢复日志级别为 INFO。


8 mxgate 事件触发

有时我们需要在 mxgate 对某表执行插入操作的过程中，对此表进行一些 DDL 的修改，此功能可以使 mxgate 在收到 DDL 修改指令后对正在发生的插入操作进行“退避”，从而使得 DDL 语句在第一时间可以得到执行。

支持的 DDL 操作如下：

  1. 清空一个表或者一组表
    =# TRUNCATE TABLE <tablename>;
  2. 为某个表增加列、删除列、修改列类型
    =# ALTER TABLE <tablename> ADD COLUMN <columnname> <columndatatype>;
=# ALTER TABLE <tablename> DROP COLUMN <columnname>;
=# ALTER TABLE <tablename> ALTER COLUMN <columnname> TYPE <columndatatype>;
  3. 为某个表更改表名
    =# ALTER TABLE <tablename> RENAME TO <new tablename>;
  4. 先删除表再重新创建它
    =# DROP TABLE <tablename>;
=# CREATE TABLE <tablename(column datatype)>;
  5. 针对分区表的以上四种 DDL 操作


9 mxgate 自动调节 slot 数

通常，我们可以通过手动调节 stream-prepared 参数 （并行执行的 slot 会话数量）来适配不同写入任务的负载（即将写入的数据量）。但在某些业务场景中，写入任务的负载存在持续的动态变化，这种变化无法通过人工的方式来调整。

因此，MatrixGate 设计了一种自动机制：通过开启 --auto-tune 参数来完成对写入负载的自动适配。

此参数可通过以下几种方式启用：

注意！
开启此功能可以实时保证最高效的写入性能，但是对于会话 slot 资源的利用，不一定为最优。

注意！
如果你设置了开启自动调整 slot 数，同时设置了高水位阈值，那么只有在写入负载超过阈值的情况下自动调整 slot 数功能才会生效。


10 mxgate 百分比量化写入负载

mxgate 支持对源端数据的写入负载进行量化（百分比 0 ～ 100%），在 mxgate 执行数据写入的过程中，通过如下命令即可获取到对应任务（Job）的写入负载：

$ mxgate get --source-pressure
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 source-pressure = 27.26%

如果有多个 Job，则可以通过 Job 的名称来获取对应的写入负载，或者一次性获取多个 Job 的写入负载：

$ mxgate get --source-pressure --job public.t2
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 source-pressure = 15.73%
$ mxgate get --source-pressure
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 source-pressure = 35.84%
public.t1 source-pressure = 0%

完成百分比负载量化后，你可以使用此指标设置一个相应的高水位阈值。如果源端数据写入负载超过了设定的阈值，则对应的数字会展示为红色。此时可以手动调整 slot 数以降低写入压力，当然也可以使用 mxgate 自动调节 slot 数功能。

阈值需通过以下命令设置：

$ mxgate set --high-water-mark <highwatermark> --job <jobname>

例如：

$ mxgate set --high-water-mark 20 --job public.t2
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 high-water-mark = 20.00%

通过如下命令获取对应 Job 的高水位阈值：

$ mxgate get --high-water-mark-get --job public.t2
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 high-water-mark = 20.00%
$ mxgate get --high-water-mark-get
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t1 high-water-mark = 0.00%
public.t2 high-water-mark = 20.00%

注意！
如果超过了设定的阈值，压力值会变红。

如果你开启了 mxgate 的自动调整 slot 数功能，并且设置了对应的高水位阈值，那么在该 Job 的载入压力值没有超过设定的高水位阈值之前，slot 数是不会自动增加的，即使 mxgate 尝试通过自动调整功能增加也无济于事。

例如：我们设定了高水位阈值为 75%。在载入压力 为 35% 的时候，虽然 mxgate 经过判断认为应该增加 slot 数，但是因为没有达到高水位阈值设置的 75%，此时 slot 数并不会增加，而是会显示如下报错：

[WARN]:-[SlotsLauncher] Sources pressure = 35.21 of job(public.t2) is lower than the high water mark(75), the slot increase is not allowed

注意！
示例值仅为参考，请根据实际业务需求和当前数据写入速度来设置相应高水位阈值。

如果想解除高水位阈值的限制，则可以使用如下命令：

$ mxgate set --disable-high-water-mark=true --job public.t2
******************************************************
 __  __       _        _       ____       _
|  \/  | __ _| |_ _ __(_)_  __/ ___| __ _| |_ ___
| |\/| |/ _` | __| '__| \ \/ / |  _ / _` | __/ _ \
| |  | | (_| | |_| |  | |>  <| |_| | (_| | ||  __/
|_|  |_|\__,_|\__|_|  |_/_/\_\\____|\__,_|\__\___|
  Version: v5.2.0
  Your Copy is Licensed to: yMatrix.cn; 2023-10-26; any
******************************************************
public.t2 high-water-mark = 0.00%

11 mxgate 数据写入进程信息、插入系统表和错误日志表

你可以通过查询 matrixmgr 数据库中的 matrixgate_internal.mxgate_process_view 视图来查看所有连接到 YMatrix 数据库的正在进行数据写入，或者已进行数据写入完毕的 mxgate 进程信息。

matrixmgr=# SELECT * from matrixgate_internal.mxgate_process_view;
 id |  pid   | host | port | source |    database     |      external_table_schema       | has_metrics |          created_at           |           exited_at           | exited | schema_cleaned |      mxgate_config       | updated_at
----+--------+------+------+--------+-----------------+----------------------------------+-------------+-------------------------------+-------------------------------+--------+----------------+--------------------------+------------
 13 |  63431 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_63431_sdw2_b7b30959  | t           | 2024-04-03 16:45:27.789389+08 | 2024-04-03 16:45:27.981513+08 | t      | f              | {"metrics_interval": 10} |
 14 |  66038 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_66038_sdw2_e810e04d  | t           | 2024-04-03 16:45:54.381101+08 | 2024-04-03 16:45:54.571016+08 | t      | f              | {"metrics_interval": 15} |
 15 |  98535 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_98535_sdw2_b5032eff  | f           | 2024-04-03 16:49:50.540095+08 | 2024-04-03 16:49:50.753405+08 | t      | f              | {"metrics_interval": 15} |
 16 | 102059 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_102059_sdw2_c0f9dbc4 | f           | 2024-04-03 16:50:30.544932+08 | 2024-04-03 16:50:30.749403+08 | t      | f              | {"metrics_interval": 15} |
 17 | 104761 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_104761_sdw2_f284b2f2 | t           | 2024-04-03 16:50:40.909025+08 | 2024-04-03 16:50:41.10522+08  | t      | f              | {"metrics_interval": 10} |
 18 | 105109 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_105109_sdw2_9ffa1360 | f           | 2024-04-03 16:50:42.324334+08 | 2024-04-03 16:50:42.501187+08 | t      | f              | {"metrics_interval": 15} |
 19 | 110590 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_110590_sdw2_527394f9 | f           | 2024-04-03 16:51:28.265894+08 | 2024-04-03 16:51:28.468763+08 | t      | f              | {"metrics_interval": 0}  |
 20 | 110760 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_110760_sdw2_c7d787a3 | t           | 2024-04-03 16:51:29.730855+08 | 2024-04-03 16:51:29.957642+08 | t      | f              | {"metrics_interval": 10} |
 21 | 110882 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_110882_sdw2_6bdbd471 | f           | 2024-04-03 16:51:31.189347+08 | 2024-04-03 16:51:31.383211+08 | t      | f              | {"metrics_interval": 15} |
 22 | 112484 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_112484_sdw2_83dc4c87 | f           | 2024-04-03 16:51:47.735186+08 | 2024-04-03 16:51:47.943989+08 | t      | f              | {"metrics_interval": 0}  |
 23 | 112608 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_112608_sdw2_ebd6fcb1 | t           | 2024-04-03 16:51:49.202759+08 | 2024-04-03 16:51:49.413013+08 | t      | f              | {"metrics_interval": 10} |
 24 | 112746 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_112746_sdw2_804d4e9c | f           | 2024-04-03 16:51:50.651448+08 | 2024-04-03 16:51:50.82829+08  | t      | f              | {"metrics_interval": 15} |
 25 | 114206 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_114206_sdw2_1376e4f0 | f           | 2024-04-03 16:52:05.954983+08 | 2024-04-03 16:52:06.150763+08 | t      | f              | {"metrics_interval": 0}  |
 26 | 114323 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_114323_sdw2_31f5fe71 | t           | 2024-04-03 16:52:07.392493+08 | 2024-04-03 16:52:07.606231+08 | t      | f              | {"metrics_interval": 10} |
 27 | 114454 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_114454_sdw2_84a2439d | f           | 2024-04-03 16:52:08.849134+08 | 2024-04-03 16:52:09.044388+08 | t      | f              | {"metrics_interval": 15} |
 28 | 118611 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_118611_sdw2_11aa241a | f           | 2024-04-03 16:54:08.596567+08 | 2024-04-03 16:54:08.806036+08 | t      | f              | {"metrics_interval": 0}  |
 29 | 118754 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_118754_sdw2_9c835dfc | t           | 2024-04-03 16:54:10.04123+08  | 2024-04-03 16:54:10.28288+08  | t      | f              | {"metrics_interval": 10} |
 30 | 118879 | sdw2 | 8891 | http   | kafka_gate_json | _matrixgate_118879_sdw2_d58b7ed2 | f           | 2024-04-03 16:54:11.521661+08 | 2024-04-03 16:54:11.72412+08  | t      | f              | {"metrics_interval": 15} |
(18 rows)

或通过以下命令查看。

$ mxgate get mxgate-process-info

参数说明：

参数 描述
id 自增 ID
pid mxgate 进程 PID
host mxgate 所在服务器主机名
port mxgate 对外暴露的 gRPC 服务的端口号
created_at mxgate 进程创建的时间。进程启动后，该时间不会再更新
exited mxgate 进程是否是退出状态。正常情况下，mxgate 进程运行中，该参数值为 false；mxgate 进程正常退出，如执行了 Control + C 或 mxgate stop 命令，则该参数值为 true；如果 mxgate 进程非正常退出（如被手动杀掉或服务器离线），则可能出现 mxgate 来不及在退出的时候修改此值的情况，最终仍保持为 false 状态
cleaned mxgate 进程使用的外部表模式是否已被删除。如果 mxgate 进程在运行中，则该参数为 false；如果 mxgate 进程正常退出，那么几秒后该参数就会变为 true；如果是非正常退出，则可能出现 mxgate 来不及在退出的时候修改此值的情况，因而无法将相关模式即时删除，最终仍保持为 false 状态。为了应对这种情况，YMatrix 内部会维护 mxgate 心跳（Heartbeat）时间，超过 2h 未更新心跳，则认为 mxgate 进程已退出，相关外部表模式会被删除，该参数会变为 true
database mxgate 连接的数据库
source mxgate 的数据源类型（HTTP / Stdin / Kafka / Transfer）
updated_at mxgate 进程每隔 3 秒对该时间进行更新。该时间是 YMatrix Master 上的 mxgate 进程的更新时间，如果 mxgate 进程正常退出，那么从 matrixgate_internal.mxgate_process_view 视图中查询到的对应 id 的 updated_at 参数会变为 NULL
has_metrics mxgate 内部收集各种数据统计及性能指标的模块是否启动。该字段为 false 时，mxgate get mxgate-process-info 命令的返回结果为空
external_table_schema 记录 mxgate 创建的外部表的模式。用于在 mxgate 非正常退出后，对残余的模式进行清除
mxgate_config 用于保存 mxgate config 文件中关键字段，便于在 mxgate 进程退出后，仍然可以查阅对应的配置信息（v5.3.2 开始支持）

目前，mxgate 所有类型的数据源（Stdin，HTTP，gRPC，Transfer）都支持了数据插入系统表和错误日志的信息统计。其中：

  • 插入系统表（Insert catalog）：此表中的每一行表示 mxgate 每个 slot 一次 INSERT 操作（成功 / 部分成功 / 失败）的记录；
  • 错误日志表（Error log）：记录了所有插入失败的元组（Tuple）。

通过以下命令查看插入系统表：

=# SELECT * FROM matrixgate_internal.insert_catalog;
 id | mxgate_id | insert_sequence | slot_id | session_id |       created_at       | status  | source | flows_cnt | total_lines | bytes_length |                          target_table                           |        message        | job_id
----+-----------+-----------------+---------+------------+------------------------+---------+--------+-----------+-------------+--------------+-----------------------------------------------------------------+-----------------------+--------
  3 |        39 |               1 |      10 |     152832 | 2024-03-15 13:17:32+08 | partial | http   |        10 |         100 |          600 | "public"."concurrent_insert_error_log_varification_http_source" | 20 malformed messages |      1
(1 row)

参数说明：

参数 描述
id 自增 ID
mxgate_id mxgate 进程 ID。对应 mxgate_process_view 视图中的 id 字段
insert_sequence 本次 insert 操作的序列号，slot 每 insert 一次，该值会加 1
slot_id 本次 insert 对应的 slot 的 ID 号
session_id 本次 insert，mxgate 作为客户端和数据库建立连接的会话 ID
created_at 本条 insert 记录的创建时间
status 本条 insert 的状态，包括：success / partial / fail(成功/部分成功/失败)
source mxgate 数据源类型
flows_cnt 本次 insert 包含多少个批
total_lines 本次 insert 总共多少行
bytes_length 本次 insert 总共含多少字节的数据
target_table 数据写入的目标表
message 如果写入出错，则表示错误原因
job_id Job 的 ID，形式为："schema"."table"

通过以下命令查看错误日志表：

=# SELECT * FROM matrixgate_internal.insert_error_log;
 catalog_id |       created_at       |      received_at       | line_number |                          errmsg                           | rawdata
------------+------------------------+------------------------+-------------+-----------------------------------------------------------+----------
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           6 | invalid input syntax for type integer: "error", column id | error|c5
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           9 | invalid input syntax for type integer: "error", column id | error|c8
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           6 | invalid input syntax for type integer: "error", column id | error|c5
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           9 | invalid input syntax for type integer: "error", column id | error|c8
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           6 | invalid input syntax for type integer: "error", column id | error|c5
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           9 | invalid input syntax for type integer: "error", column id | error|c8
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           6 | invalid input syntax for type integer: "error", column id | error|c5
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           9 | invalid input syntax for type integer: "error", column id | error|c8
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           6 | invalid input syntax for type integer: "error", column id | error|c5
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           9 | invalid input syntax for type integer: "error", column id | error|c8
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           6 | invalid input syntax for type integer: "error", column id | error|c5
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           9 | invalid input syntax for type integer: "error", column id | error|c8
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           6 | invalid input syntax for type integer: "error", column id | error|c5
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           9 | invalid input syntax for type integer: "error", column id | error|c8
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           6 | invalid input syntax for type integer: "error", column id | error|c5
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           9 | invalid input syntax for type integer: "error", column id | error|c8
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           6 | invalid input syntax for type integer: "error", column id | error|c5
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           9 | invalid input syntax for type integer: "error", column id | error|c8
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           6 | invalid input syntax for type integer: "error", column id | error|c5
          3 | 2024-03-15 13:17:32+08 | 2024-03-15 13:17:31+08 |           9 | invalid input syntax for type integer: "error", column id | error|c8
(20 rows)

参数说明：

参数 描述
catalog_id 自增 ID。对应插入系统表的 id 字段
created_at 本条记录创建的时间
received_at 本条数据被 mxgate 接收到的时间
line_number 本条数据的行号
errmsg 错误原因
rawdata 原始数据

注意!
mxgate 如果遇到一次写入操作中的整批数据全部失败的情况，则只会在 matrixgate_internal.insert_catalog 表中记录一条 status = fail 的信息，而不会在 matrixgate_internal.insert_error_log 表里记录再记录每一行错误的元组。