[doc]Clog tool (#154)

* clog_tool doc

* clog format introduction

* fix comments and add about ob_admin

* fix tingshan comment

doc-cn/ob-admin/clog-format-introduction.md

+# clog 日志格式说明
+
+通常 clog 文件中包含多种类型的日志，其中 OB_LOG_SUBMIT 为主要的日志类型，表示对应的 clog 日志为其他模块（非 clog 模块）提交的日志，包含事务模块向 clog 提交的事务日志。本节介绍事务日志的打印格式。
+
+事务日志的打印格式主要包含三部分：摘要（abstract）、头部（header）和主体（content）。日志形式如下所示：
+
+```bash
+$$$abstract |header |||   |||content
+```
+
+## 摘要
+
+摘要描述了日志记录在日志文件中的相关信息，内容形式如下所示：
+
+```bash
+file_id:*** offset:*** len:***  OB_LOG_SUBMIT
+```
+
+下表列出了字段名的详细信息。
+
+| 字段名 | 说明 |
+| --- | --- |
+| file_id | clog 日志文件名 |
+| offset | 日志记录在日志文件中的偏移量 |
+| len | 日志记录的长度 |
+| OB_LOG_SUBMIT | clog 日志类型为 OB_LOG_SUBMIT |
+
+## 头部
+
+头部描述了日志记录自身的相关信息，内容形式如下所示：
+
+```bash
+ObLogEntryHeader:{magic:***, version:***, type:***, partition_key:***, log_id:***, data_len:***, generation_timestamp:***, epoch_id:***, proposal_id:***, submit_timestamp:***, is_batch_committed:***, is_trans_log:***, data_checksum:***, active_memstore_version:***, header_checksum:***}
+```
+
+下表列出了部分字段名的详细信息。
+
+| 字段名 | 说明 |
+| --- | --- |
+| partition_key | 日志记录对应的数据分区的分区标识符 |
+| log_id | 日志记录的标识符，可看作日志序列号 |
+| generation_timestamp_ | 日志记录产生的时间点（Unix 时间戳） |
+| epoch_id | 选举相关变量，选举周期标识符（Unix 时间戳） |
+| proposal_id | Paxos 协议相关变量 |
+| is_trans_log | 日志记录是否是事务记录 |
+
+## 主体
+
+主体描述了该日志记录包含的数据。如果该日志记录是事务日志记录，内容形式如下所示：
+
+```bash
+Trans: log_type:***, trans_inc:*** {[trans_log]}||| [mutator]
+```
+
+下表列出了部分字段名的详细信息。
+
+| 字段名 | 说明 |
+| --- | --- |
+| `log_type` | 事务日志的类型 |
+| `trans_id` | 事务日志对应的事务标识符 |
+| `[trans_log]` | 事务日志的相关信息 |
+| `[mutator]` | 如果事务日志类型为 redo，则该日志包含事务修改内容 |
+
+由于 OceanBase 数据库限制一条日志记录的大小，因此当一个事务的修改数据量较大时，可能产生多条 redo 类型的事务日志记录。

doc-cn/ob-admin/clog-tool.md

+# clog_tool
+
+OceanBase 数据库的 clog 日志类似于传统数据库的 Redo 日志。clog 日志负责在事务提交时持久化事务数据。事务数据是事务对数据库的修改记录。clog_tool 用于解析并打印 clog 文件。目前，clog_tool 集成在 ob_admin 工具中，您可以通过执行 `ob_admin` 命令调用 clog_tool。
+
+<!-- 为了保证高可用和一致性，OceanBase 数据库采用了 Paxos 协议对影响数据库状态的操作进行持久化。持久化产生的一致性日志文件即为 clog 日志。 -->
+
+## clog_tool 命令
+
+下表列出了 clog_tool 的常用命令。
+
+| 命令名 | 说明 |
+| --- | --- |
+| `dump_all` | 解析并打印指定的 clog 文件。 |
+| `dump_hex` | 解析并打印指定的 clog 文件，并将不可打印的字符转换为十六进制字符打印。 |
+| `dump_format` | 解析指定的 clog 文件，并将这个日志文件按照类 SQL 形式打印。 |
+| `dump_filter` | 解析指定的 clog 文件，并打印这个日志文件中满足过滤条件的记录。 |
+| `stat_clog` | 解析指定的 clog 文件，并打印这个日志文件的统计信息。|
+
+### `dump_all` 命令
+
+```bash
+ob_admin clog_tool dump_all <clog_file_name>
+```
+
+使用 `dump_all` 命令解析并打印指定的 clog 文件。解析多个文件时，文件名需要使用空格隔开。
+
+其中 `clog_file_name` 为指定 clog 文件名。`clog_file_name` 可以包含文件路径。例如：
+
+解析并打印单个 clog 文件。此处待解析的 clog 文件名为 `101`，且这个文件位于当前目录，则运行以下命令解析并打印该文件。
+
+```bash
+ob_admin clog_tool dump_all 101
+```
+
+解析并打印多个 clog 文件。此处待解析的 clog 文件名为 `101` 和 `103`，且这两个文件均位于当前目录，则运行以下命令解析并打印这两个文件。
+
+```bash
+ob_admin clog_tool dump_all 101 103
+```
+
+解析并打印多个文件名递增的 clog 文件。此处待解析的 clog 文件名为 `101`、`102`、`103` 和 `104`，且这些文件均位于当前目录，则运行以下命令解析并打印这些文件。
+
+```bash
+ob_admin clog_tool dump_all {101..104}
+```
+
+### `dump_hex` 命令
+
+```bash
+ob_admin clog_tool dump_hex <clog_file_name>
+```
+
+如果 clog 日志中包含不可打印的字符，那么 ob_admin 将无法通过 `dump_all` 命令打印这部分内容。使用 `dump_hex` 命令将不可打印的字符转为十六进制字符并打印。
+
+`<clog_file_name>` 详情，参考 `dump_all` 命令。
+
+### `dump_format` 命令
+
+```bash
+ob_admin clog_tool dump_format <clog_file_name>
+```
+
+通过 `dump_all` 命令打印的日志不便于阅读。为了增强可读性，使用 `dump_format` 命令解析指定的 clog 文件，并将这个日志文件按照类 SQL 形式打印。
+
+`<clog_file_name>` 详情，参考 `dump_all` 命令。
+
+### `dump_filter`
+
+```bash
+ob_admin clog_tool dump_filter '<filter_name>' <clog_file_name>
+```
+
+使用 `dump_filter` 命令过滤不需要的 clog 日志记录。
+
+`<clog_file_name>` 详情，参考 `dump_all` 命令。
+
+目前，`filter_name` 的取值如下：
+
+| 过滤条件名称 | 说明 |
+| --- | --- |
+| `table_id` | 数据表标识符 |
+| `partition_id` | 数据分区标识符 |
+
+`filter_name` 可以单独使用，也可以组合使用。过滤多个条件时，条件名称需要用英文分号（;）隔开。例如：
+
+`table_id` 为 123， clog 文件名为 `101` 且位于当前目录，则运行以下命令解析并打印该文件。
+
+```bash
+ob_admin clog_tool dump_filter 'table_id=123' 101
+```
+
+`table_id` 为 `123`，`partition_id` 为 `2`，需要解析的 clog 文件名为 `101` 且位于当前目录，则运行以下命令解析并打印该文件。
+
+```bash
+ob_admin clog_tool dump_filter 'table_id=123;partition_id=2' 101
+```
+
+### `stat_clog` 命令
+
+```bash
+ob_admin clog_tool stat_clog <clog_file_name>
+```
+
+使用 `stat_clog` 命令获取指定 clog 文件的统计信息，包括日志文件大小、日志记录个数、事务个数等信息。
+
+<!-- ## 事务的相关信息
+
+### 事务日志的类型
+
+根据事务日志产生的阶段，可以将事务日志分为事务执行时日志和事务提交时日志。
+
+#### 事务执行时日志
+
+在事务执行阶段，对事务的修改进行持久化时产生日志记录即为事务执行时日志。事务执行时日志记录的类型如下所示：
+
+| 日志类型 | 内部类型值 | 说明 |
+| --- | --- | --- |
+| OB_LOG_MUTATOR | 0x200 | 事务的 mutator 日志，包含事务的修改内容 |
+| OB_LOG_TRANS_STATE | 0x400 | 事务的状态日志 |
+| OB_LOG_MUTATOR_WITH_STATE | 0x600 | 事务的状态日志，携带 mutator 日志 |
+| OB_LOG_MUTATOR_ABORT | 0x800 | 事务的 abort 日志，用于标记该事务已回滚 |
+
+#### 事务提交时日志
+
+在事务提交阶段，对事务的修改进行持久化时产生的日志即为事务提交时日志。根据不同的事务类型，事务提交时日志可以分为分布式事务的提交时日志和本地单分区事务的提交时日志。
+
+分布式事务的提交时日志的类型如下所示：
+
+| 日志类型 | 内部类型值 | 说明 |
+| --- | --- | --- |
+| OB_LOG_TRANS_REDO | 0x1 | 分布式事务的 redo 日志，包含事务的修改内容（redo 日志） |
+| OB_LOG_TRANS_PREPARE | 0x2 | 分布式事务的 prepare 日志 |
+| OB_LOG_TRANS_REDO_WITH_PREPARE | 0x3 | 分布式事务的 prepare 日志，包含事务的修改内容（redo 日志） |
+| OB_LOG_TRANS_COMMIT | 0x4 | 分布式事务的 commit 日志，标记该事务已提交 |
+| OB_LOG_TRANS_ABORT | 0x8 | 分布式事务的 abort 日志，标记该事务已回滚 |
+| OB_LOG_TRANS_CLEAR | 0x10 | 分布式事务的 clear 日志，用于释放事务上下文信息 |
+
+本地单分区事务的提交时日志的类型如下所示：
+
+| 日志类型 | 内部类型值 | 说明 |
+| --- | --- | --- |
+| OB_LOG_SP_TRANS_REDO | 0x20 | 单分区事务的 redo 日志，包含事务的修改内容（redo 日志） |
+| OB_LOG_SP_TRANS_COMMIT | 0x40 | 单分区事务的 commit 日志，标记该事务已提交，包含事务的修改内容（redo 日志） |
+| OB_LOG_SP_TRANS_ABORT | 0x80 | 单分区事务的 abort 日志，标记该事务已回滚 |
+
+### 事务标识符（Transaction ID）
+
+事务标识符用于区分 OBServer 内部的不同事务。因此，事务标识符需要具有**唯一性**，即不同事务具有不同的事务标识符。
+
+为了实现事务标识符的唯一性，事务标识符的结构如下所示：
+
+```bash
+class ObTransID
+{
+  uint64_t hv_;
+  common::ObAddr server_;
+  int64_t inc_;
+  int64_t timestamp_;
+}
+```
+
+各字段说明如下所示：
+
+| 字段名 | 说明 |
+| --- | --- |
+| server_ | 维护该事务标识符的 OBServer 的物理地址（包括 IP 地址和端口号） |
+| inc_ | OBServer 维护的单调递增值，在 OBServer 重启后重新计数 |
+| timestamp_ | 创建该事务标志符时的本地物理时钟值（Unix 时间戳） |
+| hv_ | 根据以上三个字段计算得到的 Hash 值 |
+
+由于 OceanBase 数据库采用了 64 位 Hash 值，两个不同事务标识符的 Hash 值产生冲突的概率极低。因此，在大多数情况下，可以使用 Hash 值来区分不同事务。
+
+### 事务类型
+
+根据事务的操作类型以及访问数据的分布，可以将事务分为本地单分区事务与分布式事务。
+
+- 本地单分区事务：事务信息的维护与该事务的访问数据位于同一个节点，且该事务仅访问同一个数据分区内的数据。
+- 分布式事务：事务信息的维护与该事务的访问数据位于不同节点，或者事务访问多个数据分区。 -->