Debugging OceanBase Observer with VSCode and GDB: A Step‑by‑Step Guide

Introduction

There are three ways to debug the observer: logs, gdb, and VSCode (which essentially uses gdb or lldb). This guide focuses on using VSCode for debugging.

Debug version OB code baseline: open‑source community version 3.1.5 GitHub: https://github.com/oceanbase/oceanbase.git Commit ID: 99777b4bc94d2cfc6be8ae1dce624e46beefad08

The debugging method combines a local development tool (VSCode) with remote GDB on the Linux server where the observer runs.

Required Tools

Local: VSCode with extensions C/C++, CMake, CMake Tools, Remote‑SSH, Remote Development

Remote: gdb

Remote Environment

Build

Refer to the official build guide: https://github.com/oceanbase/oceanbase/wiki/Build-from-source-code

yum install -y git wget rpm* cpio make glibc-devel glibc-headers binutils m4
cd /opt && git clone https://github.com/oceanbase/oceanbase.git
cd oceanbase && git checkout 99777b4bc94d2cfc6be8ae1dce624e46beefad08
curl http://mirrors.aliyun.com/oceanbase/OceanBase.repo
## Modify build options
## Comment out set(DEBUG_PREFIX "-fdebug-prefix-map=${CMAKE_SOURCE_DIR}=.")
vi cmake/Env.cmake
# The build takes time; you can run the following steps first
bash build.sh debug --init --make
# After completion, a build_debug directory is created; the observer binary is located at build_debug/src/observer/observer

Install

Check Environment

Adjust the following system limits on the server (example configuration):

vi /etc/security/limits.conf
# Append
root soft nofile 655350
root hard nofile 655350
* soft nofile 655350
* hard nofile 655350
* soft stack 20480
* hard stack 20480
* soft nproc 655360
* hard nproc 655360
* soft core unlimited
* hard core unlimited
# Log out and log back in, then verify:
ulimit -a

Deploy

Refer to: https://github.com/oceanbase/oceanbase/wiki/how_to_deploy_binary

yum install -y yum-utils
yum-config-manager --add-repo https://mirrors.aliyun.com/oceanbase/OceanBase.repo
yum install -y libtool libaio obclient
/opt/oceanbase/deps/3rd && bash dep_create.sh all
cd /opt/oceanbase/tools/deploy
# This command copies the observer binary (build_debug or build_release) and other components to the current directory.
./obd.sh prepare -p /opt/oceanbase/build_debug/src/observer
./obd.sh deploy -c single.yaml

After source changes, you can redeploy quickly:

./obd.sh prepare -p /opt/oceanbase/build_debug/src/observer
./obd.sh deploy -c single.yaml

Test the connection (default MySQL port 10000, RPC port 10001):

[root@localhost deploy]# obclient -uroot -P10000 -h127.0.0.1
Welcome to the OceanBase.  Commands end with ; or \g.
Your OceanBase connection id is 3221487642
Server version: OceanBase 3.1.5 (r1-99777b4bc94d2cfc6be8ae1dce624e46beefad08) (Built Nov 22 2022 06:09:41)

Logs

Logs are located in the home_path directory defined in single.yaml . OceanBase generates observer.log, rootservice.log, election.log, and corresponding warning/error logs.

Install gdb

cd /opt && wget http://ftp.gnu.org/gnu/gdb/gdb-7.12.tar.gz
tar zxvf gdb-7.12.tar.gz && cd gdb-7.12
yum -y install gcc gcc-c++ texinfo
./configure
make && make install
gdb --version
gdbserver --version

Local Environment

Configure VSCode

Install extensions: C/C++, CMake, CMake Tools, Remote‑SSH, Remote Development

Open the Remote Explorer, SSH into the server where the observer runs (password authentication is acceptable).

Open the OceanBase source directory.

On the remote server, also install the C/C++ and CMake extensions.

Create launch.json in the .vscode folder (example below):

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(gdb) Attach",
            "type": "cppdbg",
            "request": "attach",
            "processId": "${command:pickProcess}",
            "program": "/opt/oceanbase/build_debug/src/observer/observer1/bin/observer",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "sourceFileMap": {
                "/AAA/": {
                    "editorPath": "/BBB/",
                    "useForBreakpoints": false
                }
            },
            "environment": [],
            "externalConsole": false,
            "MIMode": "gdb",
            "miDebuggerPath": "/usr/local/bin/gdb",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ]
        }
    ]
}

Start debugging via Run → Start Debugging , select the attach configuration, and choose the observer process.

After attaching, wait about half a minute for GDB to load the process.

When the debugger starts successfully, you will see the usual VSCode debugging UI.

Open ob_sql.cpp (Ctrl+P, type the filename) and set a breakpoint at line 1324.

Note: OceanBase runs many background tasks that periodically execute SQL, so breakpoints may be hit by background jobs, which can be inconvenient.

Proceed with debugging as needed.

References

OceanBase documentation: https://www.oceanbase.com/docs/community-observer-cn-10000000000449173

GitHub wiki: https://github.com/oceanbase/oceanbase/wiki