[Feature] Provide a parameter to assign the size of clog disk #990 - document

[Vendredimatin]

1 概要

1.1 需求背景

本项目的任务提出者，用户及实现该软件的部门

当前，OceanBase 数据库的日志回收策略中对用户可见的配置项有 2 个（见文档https://open.oceanbase.com/docs/observer-cn/V3.1.4/10000000000449455）：

• clog_disk_usage_limit_percentage
• clog_disk_utilization_threshold

其中clog_disk_utilization_threshold配置项用于控制clog的复用下限，在系统工作正常时，Clog 会在此水位开始复用最老的日志文件，默认值是 Clog 独立磁盘空间的 80%，不可修改。因此，正常运行的情况下，clog 或 ilog 磁盘空间占用不会超过 80%，超过则会报 "clog disk is almost full" 的错误，提醒 DBA 处理。

正常情况下，一个observer会单独跑在一块磁盘上，对该配置项不会产生任何影响；但是，仍然存在多个observer跑在一块磁盘上的可能性。例如，observer A（40%）和observer B（40%）的clog加起来已经占了磁盘的80%的空间了，observer A和observer B都抛出了"clog disk is almost full"的错误，但是observer A的用户A根据此错误来查看observer A的clog磁盘占用空间，发现才占用了40%而已，此时用户A会因为文档的描述和报错不一致而产生困惑。因此本需求需要对此进行调整。

1.3 目标

解决多observer运行在同一块磁盘时，"clog disk is almost full" 报错与单observer实际占用情况不符的问题。

2 方案实现设计

2.1 方案概述

为了实现上述目标，需要明确observer可使用的clog磁盘大小，有以下两个方案：
方案一：增加一个配置项，指定observer的clog最多占用一块磁盘的百分之几。
方案二：增加一个配置项，直接配置observer的clog磁盘大小。
首先方案一的配置项非常容易与1.1节中提到的两个配置项混淆，可能给用户使用造成不便；另外两个方案的修改量大概相等（方案一可能相对少），都需要增加一个配置项，所有使用到clog磁盘空间大小的代码都需要经过改动。
综上，考虑选择方案二。

2.2 配置项信息

增加一个启动配置项(log_disk_size)，明确指明observer的clog磁盘大小

属性	描述
参数类型	容量单位
默认值	0GB
取值范围	[0, )
是否重启OBServer起效	否

当log_disk_size配置项值为0时，表示取块磁盘大小。
计算时，使用log_disk_size作为计算clog占用空间百分比的total_space.
因此，需要修改以下两部分：

• 所有计算disk_total_space的地方
• 修改update_free_quota的计算方式

2.3 现状

• 当前磁盘空间计算方式
  • 通过statfs系统调用来获取目前使用的磁盘的总空间。
• 当前free_quota计算方式
  • 通过statfs系统调用获取磁盘的总空间total_space、并计算已使用的空间used_space
  • total_space乘上规定的磁盘上限权重后，再减去used_space即是free_quota

2.4 改造点

2.4.1 observer配置项改动

涉及修改文件：ob_parameter_seed.ipp

DEF_CAP_WITH_CHECKER(log_disk_size, OB_CLUSTER_PARAMETER, "0G", common::ObConfigClogDiskLimitSizeChecker,"[0G,)",
    "maximum of clog disk size before reuse clog files, should be less than log_disk_size."
    "Range: [0G, +∞)",
    ObParameterAttr(Section::TRANS, Source::DEFAULT, EditLevel::DYNAMIC_EFFECTIVE));

2.4.2 observer启动配置项检查

当log_disk_size配置为负或者大于磁盘总空间时，observer应该init失败

2.4.3 磁盘总占用空间计算方式

涉及修改文件ob_log_disk_manager.cpp

当log_disk_size为默认值0时，仍然保留以下计算方式；当log_disk_size被指定时，直接将log_disk_size赋值给total_space_
注释内代码为修改的地方

int ObLogDiskManager::get_total_disk_space_(int64_t& total_space) const
{
  int ret = OB_EAGAIN;
  /*
  const int64_t log_disk_size = ObServerConfig::get_instance().log_disk_size;

  if (log_disk_size != 0){
      total_space = log_disk_size;
  }else{
      const int64_t clog_disk_limit_percent = 30;
      struct statfs fsst;
      ret = OB_EAGAIN;
      // try every disk until succeed
      for (int32_t i = 0; OB_FAIL(ret) && i < MAX_DISK_COUNT; i++) {
          if (OB_LDS_GOOD == disk_slots_[i].get_state()) {
              if (0 != ::statfs(disk_slots_[i].get_disk_path(), &fsst)) {
                  ret = OB_IO_ERROR;
                  COMMON_LOG(WARN, "statfs error", K(ret), K(errno), KERRMSG);
              } else {
                  ret = OB_SUCCESS;
                  total_space = ((int64_t)fsst.f_bsize * (int64_t)fsst.f_blocks) * clog_disk_limit_percent / 100LL;
              }
          }
        }
  */
     if (OB_FAIL(ret)) {
      ret = OB_IO_ERROR;
      COMMON_LOG(ERROR, "all disks fail", K(ret));
      }
  }
  return ret;
}

2.4.2 free_quota的计算方式

涉及修改文件ob_log_file_pool.cpp

当log_disk_size为默认值0时，仍然遵循以下逻辑；当log_disk_size不为0时，以log_disk_size作为total_space，使用lstat系统调用获取path目录下已占用空间，再通过二者之差获取free_quota.
修改地方见下伪代码，注释内为修改的地方

int ObLogWriteFilePool::update_free_quota(const char* path, const int64_t percent, const int64_t limit_percent)
{
  int ret = OB_SUCCESS;
  // const int64_t log_disk_size = ObServerConfig::get_instance().log_disk_size;
  // int64_t used_size = 0;
  struct statfs fsst;
  if (NULL == path || 0 > percent || 100 < percent || 0 > limit_percent || 100 < limit_percent) {
    ret = OB_INVALID_ARGUMENT;
  } else if (OB_UNLIKELY(0 != statfs(path, &fsst))) {
    ret = OB_IO_ERROR;
    CLOG_LOG(ERROR, "statfs error", K(ret), K(path), K(errno), KERRMSG);
  } /*else if (OB_FAIL(get_total_used_size(&used_size))) {
    ret = OB_IO_ERROR;
    COMMON_LOG(ERROR, "get_total_used_size fail", K(ret));
  } */else {
    /*
    int64_t total_size = 0;
    if (log_disk_size == 0){
      const int64_t clog_disk_limit_percent = 30;
      total_size = (int64_t)fsst.f_bsize * (int64_t)fsst.f_blocks * clog_disk_limit_percent / 100LL;
    }else{
       total_size = log_disk_size * 1024 * 1024;
    }
    
    const int64_t free_quota = total_size * percent / 100LL - used_size;
    int64_t limit_quota = total_size * limit_percent / 100LL - used_size;
    */
    if (100 == limit_percent) {
      limit_quota = limit_quota - RESERVED_QUOTA_2;
    }
    ATOMIC_STORE(&free_quota_, free_quota);
    ATOMIC_STORE(&limit_free_quota_, limit_quota);
    EVENT_SET(CLOG_DISK_FREE_SIZE, free_quota);
    EVENT_SET(CLOG_DISK_FREE_RATIO, (int)((double)free_quota / (double)total_size * 100));
    if (REACH_TIME_INTERVAL(10 * 1000 * 1000)) {
      CLOG_LOG(INFO,
          "update free quota",
          K(type_),
          K(total_size),
          K(used_size),
          K(free_quota),
          K(limit_quota),
          "warn_percent(%)",
          percent,
          K(limit_percent),
          "used_percent(%)",
          used_size * 100 / (total_size + 1));
    }
    if (free_quota + 1024 * 1024 * 1024 < 0) {
      if (REACH_TIME_INTERVAL(10 * 1000 * 1000)) {
        CLOG_LOG(ERROR,
            "clog disk is almost full",
            K(type_),
            K(total_size),
            K(free_quota),
            "warn_percent(%)",
            percent,
            K(limit_percent),
            "used_percent(%)",
            used_size * 100 / (total_size + 1));
      }
    }
  }
  return ret;
}

3. 测试

3.1 测试用例

1. 测试log_disk_size能够成功地配置进ob中
   1. 
2. 测试ob_log_disk_manager.cpp中磁盘大小的获取是否符合预期
   1. 当未设置时，应该获取磁盘大小的30%
      1. 测试结果如下：observer所在磁盘空间为1.8T，当没有指定log_disk_size时，observer的大小为1.8T的30%(约528G)
      2. 
3. 测试更新free_quota_时，能否根据log_disk_size来计算free_quota_
   1. 测试结果如下：设置log_disk_size 为20G， 已用空间约16G，free_quota剩余4G
   2. 
4. 测试更新free_quota时，能够根据free_quota来成功回收clog文件
   1. 测试结果如下：设置log_disk_size 为40G， 已用空间81%，超过了80%的约束，observer进行回收，unlink clog，将已用空间降到79%
   2. 
   3. 

3.2 observer 单元测试

已通过observer单元测试

[Vendredimatin]

update：

1. 当用户不指定clog_disk_limit_size时，取整块磁盘大小。