Skip to content

配置参数说明

zhangst edited this page Dec 13, 2022 · 35 revisions

本文主要介绍v2.4版本开始的配置项,v2.4以前的配置项大体相同,名字上有过一些调整。 在配置文件里面,有过对各个参数的注释,但可能有些不足的地方,本文主要作为补充。

0. 版本号

  • conf.version。当前配置文件的版本号,该参数将用于在不同版本之间进行兼容,比如2.6版本是否支持2.4的配置文件。请不要修改该值

1. 全局配置

1.1 进程相关配置

  • id。进程的id,将会用于存储pid信息,以防止同一个目录下有多个mongoshake同时启动。默认mongoshake。
  • master_quorum。是否启动主备模式。false表示只能启动1个mongoshake。配置true的话,用户可以启动2个mongoshake,拉取同一个源MongoDB,mongoshake将会自动选主,备在监测到主挂掉后,会接管过同步服务。注意,如果主是在全量同步阶段挂掉,那么备接管过服务是不会进行断点续传,而是会从头开始同步,而且如果配置项不当,可能还会有报错。主备模式主要用于在增量环节的HA容错切换。默认false

1.2 监控

  • full_sync.http_port。全量阶段对外提供restful接口,用户可以查看内部监控的情况。默认9101。
  • incr_sync.http_port。增量阶段对外提供restful接口,用户可以查看内部监控的情况。默认9100。
  • system_profile_port。golang pprof端口,可以用户查看内部运行堆栈信息。默认9200。

1.3 日志

  • log.level。日志的级别:debug, info, warning, error,对应日志里面的打印分别是[DEBG],[INFO],[WARN],[EROR]。另外还有[CRIT]表示是最严重的错误,必须运维处理的。默认info。
  • log.dir。log的输出路径,不配置将默认打到当前的logs目录。默认空。
  • log.file。log的文件名,随着log变大,将会自动按天进行切割。默认mongoshake.log。
  • log.flush。log是否及时缓存一部分再刷盘打印,默认为false以保证程序运行的性能,但可能程序中间崩溃退出,有部分log没有打印出来。true的话对于每条log都会进行刷盘,但是会降低部分性能。默认false。

1.4 连接相关配置(重要)

  • sync_mode。同步的模式,有3种模式:all表示全量+增量同步,全量同步完毕以后进入增量同步;full表示仅进行全量同步,全量同步后进程将会退出;incr表示仅进行增量同步(默认),从给定的checkpoint(见下述)开始拉取增量数据。默认incr。
  • mongo_urls。源MongoDB连接串的地址,其格式与mongo_shell使用的连接串格式保持一致。逗号分隔同一个副本集内的结点,分号分隔分片sharding实例,免密模式可以不写“username:password@”,注意,密码里面不能含有'@'符号。
    举例:
    副本集的连接串格式(A是主节点,B和C是2个从节点):mongodb://username1:password1@primaryA,secondaryB,secondaryC
    分片集的连接串格式(shard1的结点是A,B,C;shard2是X,Y,Z):mongodb://username1:password1@primaryA,secondaryB,secondaryC;mongodb://username2:password2@primaryX,secondaryY,secondaryZ
    注意:如果mongo_connect_mode不是为standalone的话,每个副本集(分片)都需要配置primary+secondary的连接串,不能只配置一个secondary节点,但可以只配置primary的。
  • mongo_cs_url。源MongoDB的config server的地址,如果源端是sharding,需要填写这个配置。默认空。
  • mongo_s_url。源MongoDB的mongos地址,如果源端是sharding,需要填写这个配置。默认空。
  • mongo_connect_mode。数据是从源MongoDB的哪个节点进行拉取的,primary表示从主节点拉取;secondaryPreferred(默认)表示优先从secondary拉取,没有的话将会从primary拉取;standalone表示从给定的单个节点拉取。需要注意的是,如果源端是sharding,且版本小于3.6,而且是全量同步(sync_mode=full),或者全量+增量同步(sync_mode=incr),建议这里配置primary以避免孤儿文档,参考MongoShake从mongos拉取仍旧存在duplicate key error默认secondaryPreferred。

1.5 通道参数

  • tunnel。通道类型,direct表示目的端对接的是MongoDB,rpc,file,kafka用于远程传输,mock仅用于调试。默认direct。
  • tunnel.address。通道地址,不同类型的通道需要配置不同的地址。
    对于direct,此处配置目的端MongoDB的地址。
    对于rpc,此处配置目的端receiver的rpc接收地址。
    对于tcp,此处配置目的端receiver的tcp接收地址。
    对于file,此处配置文件的路径,比如data。
    对于kafka,此处配置kafka的地址,例如topic@brokers1,brokers2,默认的topic是mongoshake,目前partition只用到0。
  • tunnel.message。发送到tunnel的数据的类型,通常情况,对于非kafka通道,用户不需要关注该参数。raw是默认的类型,json表示以json格式输出oplog,bson表示以bson格式输出oplog。详见:如何使用kafka-tcp-rpc-file等异步通道进行数据的发送和消费。关于oplog的格式详见:oplog各字段的解析
  • tunnel.kafka.partition_number。v2.4.21引入。控制写入的partition个数,具体oplog是写入到哪个partition是由incr_sync.shard_key参数决定,默认按照表进行hash,保证单个partition的有序。默认为1。 详见v2.4.21优化kafka写入性能和写入格式

1.6 过滤相关

  • filter.namespace.*。黑白名单过滤,有2个对应的参数:黑名单filter.namespace.black和白名单filter.namespace.white。目前不支持正则,白名单表示通过的namespace,黑名单表示过滤的namespace,不能同时指定。分号分割不同namespace,每个namespace可以是db,也可以是db.collection。例如,我想只通过db1,db2和db3中的collection1,那么配置filter.namespace.white=db1;db2;db3.collection1即可。默认空。
  • filter.pass.special.db。指定特殊的namespace通过,比如admin,system.views,mongoshake,config。正常情况下,这几个都会被过滤,但是有可能有比较特殊的情况,例如,由于历史原因,用户的数据写入到admin库了,现在希望对这部分数据也进行同步,那么就可以执行filter.pass.special.db=admin。默认空。
  • filter.ddl_enable。是否同步DDL。DML语句包括普通的insert,update,delete,DDL语句包括建/删索引,建/删库表,rename库表,事务等数据库结构的操作。false只同步DML,用户可以设置为true对DDL进行同步。默认false。

1.7 checkpoint相关(重要)

  checkpoint作为断点续传的位点信息,存储的是64位的混合逻辑时钟,对应MongoDB oplog的ts字段(32位时间戳+32位自增计数)。checkpoint将会不定期进行更新,所以一旦中间发生重启,将会从上次记录的checkpoint开始继续进行增量同步。如果sync_mode=oplog,第一次启动,由于没有checkpoint信息,将会从给定的checkpoint.start_position开始同步;对于sync_mode=document,将不会记录checkpoint信息,全量同步完毕直接退出;对于sync_mode=all的,全量同步完毕才会记录checkpoint。

  • checkpoint.storage.url。格式跟mongo_urls一致,标识checkpoint存储的位置,可以为第三方的MongoDB。如果不配置,对于副本集,默认写到源MongoDB;对于集群版,默认写到configure server(从2.4.6版本开始,集群版checkpoint地址改为默认写到源端mongos)。默认空。
  • checkpoint.storage.db。checkpoint存储的表名地址,默认mongoshake。也就是说,对于副本集来说,checkpoint存在源库的的mongoshake db里面;对于sharding,2.4.6开始默认写mongos。默认mongoshake。
  • checkpoint.storage.collection。checkpoint存储的表名地址,默认ckpt_default。也就是说,对于副本集来说,checkpoint存在mongoshake.ckpt_default里面,对于集群版,checkpoint存在于cs的admin.ckpt_default里(从2.4.6版本开始,集群版checkpoint地址改为默认写到源端mongos)。默认ckpt_default。
  • checkpoint.start_position。仅用于sync_mode是oplog的情况,第一次将会从这个指定的位点开始拉取。其格式是UTC的时间戳:2000-01-01T00:00:01Z。如果checkpoint在给定位置存在(参见checkpoint.storage.url和checkpoint.address),那么将会从checkpoint位置开始同步,忽略checkpoint.start_position参数;若checkpoint不存在,且该值为1970-01-01T00:00:01Z,则会拉取源端所有oplog;若checkpoint不存在,且该值不为1970-01-01T00:00:01Z,则会先检查源端oplog最老的时间是否大于给定的时间,如果是则会直接报错退出。所以,如果需要强制该位置开始拉取,在需要保证该位点有效的情况下,还需要删除原来的checkpoint。(用户可以通过rs.printReplicationInfo查看最老oplog的信息)默认1970-01-01T00:00:01Z。

1.8 其他

  • transform.namespace。是否开启命名空间转换,比如源库的a.b,转换到目的库变成c.d。默认不开启,开启将会消耗比较大的资源,从而导致同步速率的大幅度的降低。谨慎建议开启。默认空。

2. 全量同步相关配置

2.1 并发相关参数

  不同客户需要根据自己的实际情况选择不同的参数,例如用户shake所在的机器,或者源和目的的MongoDB性能比较低,那么可以适当调低下列参数以降低对MongoDB的影响;如果用户的机器和MongoDB性能较高,那么可以适当调大相应参数以增大同步效率。

  • full_sync.reader.collection_parallel。一次最大并发拉取的表的数目。默认6。
  • full_sync.reader.write_document_parallel。对一个表内部,启动多少个线程进行并发写入。默认8。
  • full_sync.reader.document_batch_size。1次写入将会聚合多少个文档。128表示shake一次写入将会聚合128个文档进行发送到目的MongoDB。默认128。
  • full_sync.reader.read_document_count。2.4.7版本开始启用,2.6.4版本废弃。表示1个table切分的块大小,比如该值为1000,那么假如table有5000个文档,那么会切分成5个块并发拉取。0表示不启用切分,建议该值不要设置过低导致并发度过高,会对shake本身机器负载以及目的端MongoDB造成压力,一个表并发在4-32为最佳值。默认0。
  • full_sync.reader.parallel_thread。2.6.4版本引入。单表并发拉取的线程个数,_默认为1_表示沿用单线程拉取。
  • full_sync.reader.parallel_index。2.6.4版本引入。单表切分成多个段所依赖的索引,对于副本集建议配置_id(默认);对于分片集群,建议配置shard key,不过目前只支持单个字段,不支持多个字段的联合索引。

2.2 结构化相关参数

  • full_sync.collection_exist_drop。同步前如果发现目的端已经存在同样的表,是否需要先删除再进行同步,false表示不删除直接同步,但可能会存在_id一样的文档从而报错(参考full_sync.executor.*相关参数),true表示在目的端先删除对应的表再进行同步。默认true。
  • full_sync.create_index。全量期间数据同步完毕后,是否需要创建前台索引,"foreground"表示前台创建索引,"none"表示不创建,2.4.1版本开始支持"background"后台创建索引。默认foreground

2.3 增量持久化参数

  • full_sync.reader.oplog_store_disk。2.4版本废弃。一旦启用,在全量同步期间,对源库的oplog进行拉取并本地磁盘持久化,避免增量同步所需的oplog被源库删除,造成增量同步失败。默认false。
  • full_sync.reader.oplog_store_disk_max_size。在全量同步期间,oplog本地持久化的容量上限,单位MB,若超过该值全量还没结束,则不再写入磁盘。默认256000。

2.3 写入端相关参数

  • full_sync.executor.insert_on_dup_update。如果_id存在在目的库,是否将insert语句修改为update语句。若用户本来目的端就已经有数据,建议开启。默认false。
  • full_sync.executor.filter.orphan_document。源端是sharding,是否需要过滤orphan文档。默认false。
  • full_sync.executor.majority_enable。全量阶段写入端是否启用majority write。默认false。

3. 增量同步相关配置

3.1 拉取相关参数

  • incr_sync.mongo_fetch_method。从源MongoDB拉取增量的方式,oplog(默认)表示以oplog进行拉取,change_stream表示以change stream进行对接拉取。oplog方式支持所有大于等于3.0的MongoDB版本,但对于sharding的同步,需要关掉balancer进行同步,否则会有时序不一致的问题。change_stream支持大于等于4.0的MongoDB版本,对于部分DDL的同步不支持,目前只支持库表的建/删,重命名,由于MongoDB本身的限制(不支持在ChangeStream输出这些命令),对于建/删索引,convertToCapped,applyOps等都不支持。默认oplog。
  • incr_sync.target_delay。控制延迟同步的时间,目的端可以落后于源端指定的秒数,详细请参考:v2.4.6版本增加延迟同步功能 默认0

3.2 双向同步

  • incr_sync.oplog.gids。仅用于阿里云云MongoDB,开源请忽略。云上版本请在控制台开启global id(目前还没开启),或咨询响应售后同学。默认空。

3.3 并发控制参数

  • incr_sync.shard_key。内部并发分发给worker线程的方式。id表示按主键_id进行哈希,collection表示按表哈希,auto表示自动识别,如果不存在索引那么会按照_id,存在则按照collection。如果修改为auto或者id,需要确认所有表都没有索引,并且后续也不会创建索引,按主键_id哈希的性能将会非常可观。默认collection。
  • incr_sync.shard_by_object_id_whitelist。按_id并发的白名单,具体请参考v2.4.12 增加incr_sync.shard_by_object_id_whitelist参数解决没有唯一索引情况下的单表倾斜问题
  • incr_sync.worker.worker线程的个数,默认为8,越大以为内部并发度将会越大。可以根据机器的负载情况适当调大/调小该参数。默认8。
  • incr_sync.worker.oplog_compressor。2.4.21废弃。仅用于非direct通道跨网络传输的情况,用户可以配置gzip, zlib或者deflate三种压缩方式,发送前数据将会进行压缩,以减少网络带宽的使用。默认none。
  • incr_sync.worker.batch_queue_size。调优参数,不建议修改,参考FAQ。默认64。
  • incr_sync.adaptive.batching_max_size。调优参数,不建议修改,参考FAQ。默认1024。
  • incr_sync.fetcher.buffer_capacity。调优参数,不建议修改,参考FAQ。默认256。
  • incr_sync.tunnel.write_thread。v2.4.21版本引入。控制序列化的线程个数,默认为1个tunnel(worker)对应1个。该参数必须为worker的倍数,比如worker默认是8,如果该参数为24,则每个worker对应3个解析线程。默认为空。 详见v2.4.21优化kafka写入性能和写入格式

3.4 direct通道写入端相关配置

  • incr_sync.executor.upsert。如果_id不存在在目的库,是否将update语句修改为insert语句。默认false。如果目的端是sharding,不能开启该参数。默认false。
  • incr_sync.executor.insert_on_dup_update。如果_id存在在目的库,是否将insert语句修改为update语句。默认false。
  • incr_sync.conflict_write_to。如果写入存在冲突,记录冲突的文档。db表示将冲突记录到checkpoint url对应的db里面。sdk表示写入sdk(开源没有用)。默认none。
  • incr_sync.executor.majority_enable。增量阶段写入端是否启用majority write。默认false。

3.5 其他

  • incr_sync.change_stream.watch_full_document。change stream专用参数。更新文档后,只需要更新的字段则设为false,需要全部文档内容则设为true。不设置在$set/$unset只会显示差异化的字段,而不会展示所有文档的字段。启用会导致性能有所下降。默认false。

4. 其他

  • special.source.db.flag。特殊形态支持,比如阿里云的serverless请选择aliyun_serverless默认为空。
Clone this wiki locally