Configure obdiag|V3.3.0|OceanBase Diagnostic Tool |docs|OceanBase Documentations

This topic describes the configuration files of OceanBase Diagnostic Tool (obdiag).

Note

We recommend that you use obd obdiag commands to quickly diagnose an OceanBase cluster deployed by using OceanBase Deployer (obd). In this case, no obdiag configuration file is required. For more information about the commands, see obdiag commands.

Prerequisites

You have installed obdiag. For more information, see Install obdiag.

Configuration methods

To configure obdiag, you can create a user-defined configuration file in a custom path, or use the system configuration file, which you do not need to modify in most cases. The following sections describe the two configuration files.

User-defined configuration file

You can create or edit a user-defined configuration file by running the obdiag config <option> command. By default, the configuration file is named config.yml and is stored in the ~/.obdiag directory. Template configuration files are stored in the ~/.obdiag/example directory.

obdiag config -h <db_host> -u <sys_user> [-p password] [-P port]

The following table describes the parameters.

Parameter	Required	Description
db_host	Yes	The IP address used to connect to the `sys` tenant of the OceanBase cluster.
sys_user	Yes	The username used to connect to the `sys` tenant of the OceanBase cluster. To avoid permission issues, we recommend that you use `root@sys`. If you connect to the cluster by using OceanBase Database Proxy (ODP), the value of this parameter must include the cluster name, such as `root@sys#obtest`.
-p password	No	The password used to connect to the `sys` tenant of the OceanBase cluster. This parameter is left empty by default.
-P port	No	The port used to connect to the `sys` tenant of the OceanBase cluster. Port `2881` is used by default.

Here are some examples:

# A password is specified.
obdiag config -hxx.xx.xx.xx -uroot@sys -p***** -P2881

# No password is specified.
obdiag config -hxx.xx.xx.xx -uroot@sys -P2881

# ODP is used for connection.
obdiag config -hxx.xx.xx.xx -uroot@sys#obtest  -p***** -P2883

After you run the obdiag config command, you need to enter related information as prompted.

#obdiag config -hxx.xx.xx.xx -uroot@sys -Pxxxx -p*****
2024-01-31 09:57:24,019 [INFO] Getting all the node information of the cluster, please wait a moment ...
Please enter the following configuration !!!
Enter your oceanbase host ssh username (default:''): test # The username for connecting to the host through SSH.
Enter your oceanbase host ssh password (default:''): ********* # The password for connecting to the host through SSH.
Enter your oceanbase host ssh_port (default:'22'): 22 # The SSH port number, which is 22 by default.
Enter your oceanbase install home_path (default:'/root/observer'): /home/admin/oceanbase # The installation path of OceanBase Database.
Enter your need config obproxy [y/N] (default:'N'): y # Specifies whether to use ODP for the diagnosed cluster.
Enter your obproxy server eg:'192.168.1.1;192.168.1.2;192.168.1.3' (default:''): xx.xx.xx.xx # The IP address of the ODP node.
Enter your obproxy host ssh username (default:''): test # The username for connecting to the ODP node through SSH.
Enter your obproxy host ssh password (default:''): ********* # The password for connecting to the ODP node through SSH.
Enter your obproxy host ssh port (default:'22'): 22  # The port number for connecting to the ODP node through SSH, which is 22 by default.
Enter your obproxy install home_path (default:'/root/obproxy'): /home/admin/obproxy # The installation path of ODP.
2024-01-31 09:59:23,109 [INFO] Node information has been rewritten to the configuration file /test/.obdiag/config.yml, and you can enjoy the journey !

Note

If you run the config command, you need to enter related information as prompted. Enter the values based on the actual situation.

After the execution is completed, the new configuration is generated in the config.yml configuration file, and the original configuration file, if it contains configuration information, is backed up to the ~/.obdiag directory as a backup_conf file.

The following sample code shows a complete configuration, which consists of three parts that can be configured as needed:

# Part 1: Parameters related to OceanBase Cloud Platform (OCP)
ocp:
  login:
    url: http://xx.xx.xx.xxx:xx
    user: ****
    password: ******
# Part 2: Parameters related to the OceanBase cluster
obcluster:
  ob_cluster_name: test # The cluster name.
  db_host: xx.xx.xx.1 # The IP address of the cluster.
  db_port: 2881 # The port number of the cluster, which is 2881 by default.
  tenant_sys: # The information of the sys tenant. To avoid permission issues, we recommend that you use root@sys.
    user: root@sys # By default, root@sys is used.
    password: ""
  servers:
    nodes:
      - ip: xx.xx.xx.1
      - ip: xx.xx.xx.2
      - ip: xx.xx.xx.3
    global:
      ssh_username: **** # The login information. We recommend that you use the same user information specified for the deployment of OceanBase Database.
      ssh_password: **** # If you do not use a password, set it to "".
      # ssh_port: 22 # The SSH port. By default, port 22 is used.
      # ssh_key_file: "" # The path of the SSH key. If you specify the ssh_password parameter, you do not need to specify this parameter.
      # ssh_type: remote # The deployment mode of OceanBase Database. Valid values: remote and docker. Default value: remote. Note that Kubernetes is not supported in docker mode.
      # container_name: xxx # The name of the OceanBase Database container. If you set the ssh_type parameter to docker, you must specify this parameter.
      
      # The installation directory of OceanBase Database. For example, if the path of the executable program of OceanBase Database is /root/observer/bin/observer,
      # you must set the home_path parameter to /root/observer.
      home_path: /root/observer   
      data_dir: /root/observer/store # The data disk path of OceanBase Database.
      redo_dir: /root/observer/store # The log disk path of OceanBase Database.
# Part 3: Parameters related to ODP
obproxy:
  obproxy_cluster_name: obproxy
  servers:
    nodes:
      - ip: xx.xx.xx.4
      - ip: xx.xx.xx.5
      - ip: xx.xx.xx.6
    global:
      ssh_username: **** # The login information. We recommend that you use the same user information specified for the deployment of ODP.
      ssh_password: **** # If you do not use a password, set it to "".
      # ssh_port: 22 # The SSH port. By default, port 22 is used.
      # ssh_key_file: "" # The path of the SSH key. If you specify the ssh_password parameter, you do not need to specify this parameter.
      # ssh_type: remote # The deployment mode of ODP. Valid values: remote and docker. Default value: remote. Note that Kubernetes is not supported in docker mode.
      # container_name: xxx # The name of the ODP container. If you set the ssh_type parameter to docker, you must specify this parameter.
      
      # The installation directory of ODP. For example, if the path of the executable program of ODP is /root/obproxy/bin/obproxy,
      # you must set the home_path parameter to /root/obproxy.
      home_path: /root/obproxy

Parameters of a specific node overrides those in the global section.

In the following sample configuration of an OceanBase cluster, parameters of each node are specified under the IP address of the node. If the same parameters are specified in the global section, parameters of each node take effect.

obcluster:
  ob_cluster_name: test
  db_host: xx.xx.xx.1
  db_port: 2881 # The port number of the cluster, which is 2881 by default.
  tenant_sys:
    user: root@sys # default root@sys
    password: ""
  servers:
    nodes:
      - ip: xx.xx.xx.1
        ssh_username: ****
        ssh_password: ****1
        home_path: /root/observer1
        data_dir: /root/observer/store1
        redo_dir: /root/observer/store1
      - ip: xx.xx.xx.2
        ssh_username: ****2
        ssh_password: ****2
        home_path: /root/observer2
        data_dir: /root/observer/store2
        redo_dir: /root/observer/store2
      - ip: xx.xx.xx.3
        ssh_username: ****3
        ssh_password: ****3
        home_path: /root/observer3
        data_dir: /root/observer/store3
        redo_dir: /root/observer/store3
    global:
      ssh_port: 22

Note

obdiag supports IPv6 addresses, such as ip: "xxxx:xxxx:xxx:xxxx:xxxx:xxxx:xxx:xxxx", since V3.2.0.
You can find more sample configuration files in the ~/.obdiag/example directory.
If your OceanBase cluster is deployed by using Docker, you can use the sample configuration file docker_ob_cluster.yml located in the ~/.obdiag/example directory.
If your OceanBase cluster is deployed in a Kubernetes environment by using ob-operator, you can use the sample configuration file operator.yml located in the ~/.obdiag/example directory.

`--config` option

obdiag V2.4.0 and later allow you to use the --config option to specify a user-defined configuration file. This way, you can use obdiag out of the box without a configuration file. This section describes how to use the --config option.

Note

You can specify multiple --config options in the format of --config key1=value1 --config key2=value2.
In the original config.yml configuration file stored in the ~/.obdiag directory, the [num] field appended to the obcluster.servers.nodes parameter indicates the information of a specific node, such as obcluster.servers.nodes[0].
In the original config.yml configuration file stored in the ~/.obdiag directory, the hierarchy is expressed by ..

Here are some sample configurations specified by --config options:

  --config ocp.login.url=http://xx.xx.xx.xxx:xx \
  --config ocp.login.user=**** \
  --config ocp.login.password=****** \
  --config obcluster.ob_cluster_name=test \
  --config obcluster.db_host=xx.xx.xx.1 \
  --config obcluster.db_port=2881 \
  --config obcluster.tenant_sys.user=root@sys \
  --config obcluster.tenant_sys.password="" \
  --config obcluster.servers.nodes[0].ip=xx.xx.xx.1 \
  --config obcluster.servers.nodes[1].ip=xx.xx.xx.2 \
  --config obcluster.servers.nodes[2].ip=xx.xx.xx.3 \
  --config obcluster.servers.global.ssh_username=**** \
  --config obcluster.servers.global.ssh_password=**** \
  --config obcluster.servers.global.ssh_port=22 \
  --config obcluster.servers.global.home_path=/root/observer \
  --config obcluster.servers.global.data_dir=/root/observer/store \
  --config obcluster.servers.global.redo_dir=/root/observer/store \
  --config obproxy.obproxy_cluster_name=obproxy \
  --config obproxy.servers.nodes[0].ip=xx.xx.xx.4 \
  --config obproxy.servers.nodes[1].ip=xx.xx.xx.5 \
  --config obproxy.servers.nodes[2].ip=xx.xx.xx.6 \
  --config obproxy.servers.global.ssh_username=**** \
  --config obproxy.servers.global.ssh_password=**** \
  --config obproxy.servers.global.ssh_port=22 \
  --config obproxy.servers.global.home_path=/root/obproxy

Here is an example of using an IPv6 address:

  --config obcluster.servers.nodes[0].ip="xxxx:xxxx:xxx:xxxx:xxxx:xxxx:xxx:xxxa"

You can simplify some parameter names in the preceding configurations. The following table describes the simplified parameter names supported by obdiag.

Simplified parameter name	Full parameter name
`db_host`	`obcluster.db_host`
`db_port`	`obcluster.db_port`
`tenant_sys.user`	`obcluster.tenant_sys.user`
`tenant_sys.password`	`obcluster.tenant_sys.password`
`ssh_username`	`obcluster.servers.global.ssh_username`
`ssh_password`	`obcluster.servers.global.ssh_password`
`ssh_port`	`obcluster.servers.global.ssh_port`
`home_path`	`obcluster.servers.global.home_path`
`obproxy_home_path`	`obproxy.servers.global.home_path`

System configuration file

The inner_config.yml configuration file is stored in the /usr/local/oceanbase-diagnostic-tool/conf directory.

obdiag:
  basic:
    config_path: ~/.obdiag/config.yml # The path of the user-defined configuration file.
    config_backup_dir: ~/.obdiag/backup_conf # The path where the backup of the original configuration file is stored when you run the obdiag config command.
    file_number_limit: 20 # The maximum number of files returned for a collection command on a single remote host.
    file_size_limit: 2G # The maximum size of a file returned for a collection command on a single remote host.
  logger:
    log_dir: ~/.obdiag/log # The path where the execution log file of obdiag is stored.
    log_filename: obdiag.log # The name of the execution log file of obdiag.
    file_handler_log_level: DEBUG # The lowest level of execution logs of obdiag to be recorded.
    log_level: INFO # The execution log level of obdiag.
    mode: obdiag
    stdout_handler_log_level: INFO # The lowest level of obdiag logs to be displayed.
check: # Parameters required for inspection. Usually, you do not need to modify parameters in this section.
  ignore_version: false # Specifies whether to ignore the version of OceanBase Database.
  report:
    report_path: "./check_report/" # The output path of the inspection report.
    export_type: table # The type of the inspection report.
  package_file: "~/.obdiag/check/observer_check_package.yaml" # The path of inspection package files.
  tasks_base_path: "~/.obdiag/check/tasks/" # The basic directory of inspection tasks.
gather:
  scenes_base_path: "~/.obdiag/gather/tasks" # The directory of gather tasks.
rca:
  result_path: "./rca/" # The storage path of root cause analysis results.

obdiag V2.4.0 and later allow you to use the --inner_config option to specify the system configuration file of obdiag. This section describes how to use the --inner_config option.

Note

You can specify multiple inner_config options in the format of --inner_config key1=value1 --inner_config key2=value2.
In the original inner_config.yml configuration file stored in the /usr/local/oceanbase-diagnostic-tool/conf directory, the hierarchy is expressed by ..

Here are some sample configurations specified by --inner_config options:

--inner_config obdiag.basic.file_number_limit=20
--inner_config obdiag.basic.file_size_limit=2G

Note

Prerequisites

Configuration methods

User-defined configuration file

Note

Note

--config option

Note

System configuration file

Note

`--config` option