一. 设计目的

        当mods文件里的删除记录到达一定数量时，势必会降低查询等相关操作的执行效率，同时由于TsFile里存储着大量被用户删除的数据，在一定程度上也浪费了存储资源。因此，我们开发了TsFile整理工具帮助你对指定的TsFile文件进行整理和重写。

二. 工具介绍

  1. 整理工具可以帮助你整理已封口的tsFile文件和.mods文件，过滤掉删除的数据并生成新的tsFile。整理完后会将本地旧的.mods文件删除，若某tsFile里的数据被全部删除了，则会删除本地该tsFile文件和对应的.resource文件。

  2. 整理工具只能针对v0.12版本的IOTDB来使用，即只能针对版本为V3的tsFile进行整理，若低于此版本则必须先用在线升级工具将tsFile升级到V3版本。

  3. tsFile整理工具分为在线整理工具和离线整理工具，两者在整理的时候都会记录日志，供下次恢复之前整理失败的文件。离线整理工具在执行整理的时候会先去检测日志里是否存在失败的文件，有的话则优先整理它们；而在线整理工具是在IoTDB Server每次启动时检查日志里是否存在需要恢复整理的文件，有的话则进行整理。

三. 离线整理工具

        该工具的启动脚本settle.bat和settle.sh在编译了server后会生成至server\target\iotdb-server-{version}\tools\tsFileToolSet目录中。运行脚本时要给定至少一个参数，该参数可以是一个目录路径或者是一个具体的tsFile文件路径，不同参数间用空格分割。若参数是目录，则离线整理工具会递归寻找该目录下所有已封口的tsFile进行整理。若有多个参数，离线整理工具则会寻找指定参数下的所有tsFile文件，对他们依次进行整理。

        在使用离线整理工具的时候，必须保证IOTDB server停止运行，否则会出错。

3.1 用户使用

3.1.1 运行方法

#Windows
.\settle.bat <目录路径/tsFile路径> <目录路径/tsFile路径> ...

#MacOs or Linux
./settle.sh <目录路径/tsFile路径> <目录路径/tsFile路径> ...

3.1.2 运行示例

>.\settle.bat C:\IOTDB\sourceCode\choubenson\iotdb\data\data\sequence\root.ln\0\0

````````````````````````
Starting Settling the tsFile
````````````````````````
Totally find 3 tsFiles to be settled, including 0 tsFiles to be recovered.
Start settling for tsFile : C:\IOTDB\sourceCode\choubenson\iotdb\data\data\sequence\root.ln\0\0\1631261328514-1-0-2.tsFile
Finish settling successfully for tsFile : C:\IOTDB\sourceCode\choubenson\iotdb\data\data\sequence\root.ln\0\0\1631261328514-1-0-2.tsFile
Start settling for tsFile : C:\IOTDB\sourceCode\choubenson\iotdb\data\data\sequence\root.ln\0\0\1631274465662-3-0-1.tsFile
Finish settling successfully for tsFile : C:\IOTDB\sourceCode\choubenson\iotdb\data\data\sequence\root.ln\0\0\1631274465662-3-0-1.tsFile
Start settling for tsFile : C:\IOTDB\sourceCode\choubenson\iotdb\data\data\sequence\root.ln\0\0\1631433121335-5-0-0.tsFile
Finish settling successfully for tsFile : C:\IOTDB\sourceCode\choubenson\iotdb\data\data\sequence\root.ln\0\0\1631433121335-5-0-0.tsFile
Finish settling all tsFiles successfully!

3.2 相关类

         整理工具类：org.apache.iotdb.db.tools.settle.tsFileAndModSettleTool

3.3 注意事项

        离线整理工具在每次执行settle时，会先去读取日志判断是否存在整理待恢复的文件，有的话则优先整理它们，读取完后会删除该日志。

四. 在线整理工具

        当用户在IoTDB客户端输入了settle命令后，在线整理工具会在客户端所在主线程启动整理服务Settle Service，该服务会去寻找指定存储组下的所有tsFile文件，依次对每个TsFile进行整理。在线整理工具在整理过程中不允许用户对该虚拟存储组下的数据有任何的删除操作，直到整理完毕。

        此模块预留了整理线程的接口供后续为每个TsFile提供一个整理线程在后台执行整理操作，但目前只允许整理线程的串行执行，避免了线程的不安全。

4.1 用户使用

4.1.1 运行方法

IoTDB> Settle <存储组>

或者

IoTDB> Settle <"TsFile的绝对路径">

注意：单个TsFile的绝对路径必须用双引号或单引号括起来。

4.1.2 运行示例

IoTDB> Settle root.ln;
Msg: The statement is executed successfully.

或者

IoTDB> Settle "C:\IOTDB\sourceCode\choubenson\iotdb\data\data\sequence\root.ln\0\0\1631261328514-1-0-2.tsfile"

Msg: The statement is executed successfully.

4.2 单个TsFile的整理

4.2.1 工作流程

  1. 首先对该旧tsFile文件加读锁，避免在重写的过程中该tsFile被删除，而在删除该tsFile的本地mods文件前允许用户对该tsFile进行查询操作。

  2. 往整理日志记录标记该文件的状态为1。

  3. 对旧tsFile和其mods文件进行整理并重写到新tsFile文件（此时新tsFile和对应的新.resource文件已经生成并存放在临时目录下，位置为：“旧tsFile所在目录\新tsFile时间分区目录\”）。若该旧tsFile数据都已被删除了，则将其TsFileResource标记为已删除。

  4. 往整理日志记录标记该文件的状态为2。

  5. 对旧tsFile文件释放读锁后再加写锁，阻塞用户的查询等操作。

  6. 删除旧mods文件，然后将新tsFile和对应的新.resource文件移动到正确的目录下（即旧tsFile所在目录），此过程是先删除旧对应旧文件，再把新的移动过去。

  7. 清空内存中与该tsFile的相关缓存数据，即该被重写的tsFile在内存中涉及到的相关数据都应该被及时更新：

    (1) 需要clear cache (包括chunk cache和timeseriesmetadata cache)，防止因为Mods被删除而读出该tsFile已被删除的数据（脏数据）。

    (2) 若整理后，此tsFile被删除，则要从StorageGroupProcessor的tsFileManagement里挪去该oldtsFileResource. 

    (3) 从FileReaderManager中移除旧TsFile的sequenceReader。

  8. 对该tsFile释放写锁，允许用户对该文件进行查询操作，允许该文件被删除。

  9. 往整理日志标记该文件的状态为3，settle结束！

4.2.2 注意事项

        （1）在线整理工具在整理过程中阻塞了用户对该虚拟存储组下的数据有任何的删除操作，直到整理完毕。

        （2）目前整理操作是在客户端所在的主线程里运行的，即用户在输入settle命令后必须同步等待settle操作直到完毕。项目里预留了接口供后续在后台另开一个整理线程执行整理操作。

        （3）若用户输入命令“settle root.sg”时，系统正在整理该存储组，则会提示用户当前sg正在被settling，不会重复settle此sg。

        （4）IoTDB Server在启动时会去判断settle.log日志里是否存在先前整理失败的文件，有的话则进行恢复整理。系统在恢复整理文件尚未完毕前会阻止用户输入settle命令。

4.2.3 补充说明

  1. OldtsFileResource对应的本地tsFile文件不存在的情况

    (1) 上一次settle重写的过程中，旧tsFile因数据都被删掉了而相关文件被删掉，还没完成settle过程就出现异常导致整理线程中断。于是下次启动后发现settle.txt日志里的该tsFile整理记录对应的本地文件不存在。

    (2) 上一次settle重写过程中，重写完后在移动的过程中，旧tsFile被删除而新tsFile还未移动前该线程就意外中断了。

  2. Settle重写NewtsFileResource的返回情况（即tsFileAndModSettleTool类的settleOnetsFileAndMod()方法的返回情况）

    (1) 若旧tsFile没有封口，则不进行重写，返回null。

    (2) 若旧tsFile没有mods文件，即没有删除记录，则不进行重写，返回null。

    (3) 进行了重写后，旧tsFile的所有数据都被删除了，就会删除本地该tsFile文件和.resource文件，并且不会生成新的tsFile，则返回null。

4.3 相关类

  1. 整理服务类：org.apache.iotdb.db.service.SettleService

  2. 整理线程类：org.apache.iotdb.db.engine.settle.SettleTask

  3. 整理日志类：org.apache.iotdb.db.engine.settle.SettleLog

  4. 整理工具类：org.apache.iotdb.db.tools.settle.tsFileAndModSettleTool

4.4 整理日志

  1. 整理日志文件的路径在"data\system\settle\settle.txt"，它有一条条记录项，存放了某个tsFile的整理状态，每条记录项的格式为：<tsFile文件路径>,<整理状态>。

  2. 整理共有三个状态，每个状态代表的含义如下：

    (1) 状态1：代表该tsFile在整理中，还未生成新的tsFile

    (2) 状态2：代表该tsFile的新tsFile已经生成，即整理线程已经把数据整理到新tsFile里了，还未移动到正确的目录下。

    (3) 状态3：代表该tsFile已经整理完毕且整理成功，旧tsFile对应的.mods文件已被删除，新的tsFile和对应的.resource文件已经移动到正确的目录下。

  3. 无论是在线工具还是离线工具，它们在读取了settle.log日志后都会删除该日志，只不过在线工具是在server启动的时候读取日志进行恢复，而离线工具是在每次用户使用该工具执行settle时优先读取日志进行恢复。

  4. 整理日志可用于在下次server重启时恢复上次整理失败的那些tsFile文件，具体的步骤为：

    1) 整理服务SettleService启动时，会先去查找settle.txt文件是否存在，若存在则读取日志中记录的那些整理失败的tsFile，把他们加入整理列表里。

    2) 开始整理：

    (1) 对于状态是1的文件，则会删除上次整理失败而残留的新tsFile文件，并进行重写整理写入到新tsFile，然后删除对应的旧mods文件，并把新的tsFile和.resource文件移动到正确的目录下。

    (2) 对于状态是2的文件，说明其新tsFile和对应的.resource文件已经生成，则只要把它们移动到正确的目录下即可。

  • No labels