This topic describes how to use YCSB to perform a performance test on OBKV-HBase. YCSB-OBKV is a performance testing tool for OBKV based on the Yahoo! Cloud Serving Benchmark (YCSB) framework. It is used to benchmark the read and write performance of the OBKV interface.
Tool overview
- GitHub repository: oceanbase/YCSB (obkv branch)
- Supported test models: OBKV-HBase and OBKV-Table. This topic describes only the test method for OBKV-HBase.
- Usage (choose one):
- Web UI (graphical user interface): Suitable for beginners. It provides a visual web interface and supports relatively fixed test methods.
- Command line (CLI): Suitable for scenarios where the test machine has a different network environment from the outside world. It supports more customized test behaviors.
- Supported operation types:
- load (data loading)
- put (writing)
- read (reading)
- scan (scanning)
- batch_put (batch writing)
- batch_read (batch reading)
Prerequisites
Environment preparation
- Java 8 or later
- Maven 3.x
- A deployed OBKV-HBase cluster (an ODP address or a direct connection config URL is required)
Obtain the project
There are two ways to obtain the project. Choose either one:
Clone the repository
# Clone the repository and switch to the obkv branch. git clone -b obkv https://github.com/oceanbase/YCSB.git cd YCSBThe project directory structure is as follows:
YCSB/ ├── obkv-hbase/ # OBKV-HBase test module ├── obkv-table/ # OBKV-Table test module ├── webui/ # Web UI module ├── core/ # YCSB core framework ├── deploy.sh # One-click deployment script (compilation/start/stop/restart) └── docs/ # Detailed documentationDownload the compressed package
Click the obkv branch link to download the compressed package from GitHub.
Use the Web UI
Start the service
# Initial startup (automatically compiles all modules and starts the web service).
./deploy.sh start --rebuild
# Subsequent startup (the JAR files already exist, so start directly).
./deploy.sh start
# Service management commands
./deploy.sh status # View the running status.
./deploy.sh logs --follow # View logs in real time.
./deploy.sh stop # Stop the service.
./deploy.sh restart # Restart the service.
After the service is started, access http://localhost:8080 in your browser.
Procedure
Create a table: Select the module (OBKV-HBase) at the top, open the Table Creation Wizard tab, enter the partition parameters, generate SQL, enter the database connection information, and execute the table creation.
Run a test: Open the Performance Test tab, enter the connection information in Step 1, select a test mode in Step 2, select the test type and parameters in Step 3, and initiate the test.
Note the following:
- Step 1: Two connection methods are supported: direct connection mode and ODP mode. For the differences between the two methods, see OBKV connection modes.
- Step 2: Two test modes are supported: default mode and prefix mode.
- Step 3: Enter the YCSB test parameters, such as the number of stress test threads, operations, operation type ratio, number of fields, and field size.
- Step 4: Configure client-related settings, such as the timeout period and the number of connections.
View results: View the output on the Real-time Logs tab. After the test is complete, view the throughput and latency on the Result View tab (see the figure above).
Notice
You must first execute
loadto write data, and then executeread/scan/batch_readto perform the test.History: View historical test records, including test results and test configurations, and reuse test configurations for retesting.
Use the command line
The command-line test procedure is as follows:
# Step 1: Compile the project.
cd obkv-hbase && ./build.sh
# Step 2: Generate the table creation SQL.
# Range partitioning:
./create_table.sh --max_key 1000 --partition_count 4
# Primary key partitioning:
./create_table.sh --mode hbase --type first_part --partition_type key --partition_count 4
# Subpartitioning (range + key):
./create_table.sh --mode hbase --type sec_part \
--range_partition_count 30 \
--range_start_timestamp 1704067200000 \
--range_partition_duration_ms 2592000000 \
--key_subpartition_count 40
# Step 3: Execute the generated SQL file in OceanBase AI Database.
# Step 4: Edit workloads/workload_load and specify at least the following connection parameters:
# hbase.oceanbase.odpMode=true
# hbase.oceanbase.odpAddr=<ODP address>
# hbase.oceanbase.odpPort=<ODP port>
# hbase.oceanbase.fullUserName=<user@tenant#cluster>
# hbase.oceanbase.password=<password>
# hbase.oceanbase.database=<database name>
# hbase.oceanbase.table=ycsb_test
# hbase.oceanbase.columnFamily=cf
# Step 5: Run the test (use the same commands as those for OBKV-Table).
./run_fast_test.sh load
./run_fast_test.sh read
Quick reference for core parameters
This section describes the general YCSB parameters and the OBKV-HBase-specific parameters.
General YCSB parameters
Parameter |
Description |
Type |
Default value |
|---|---|---|---|
| recordcount | Total number of records in the dataset | Int | — |
| operationcount | Total number of operations in the running phase | Int | — |
| threadcount | Number of concurrent threads | Int | 1 |
| fieldcount | Number of fields per record | Int | 10 |
| fieldlength | Byte length of each field | Int | 100 |
| requestdistribution | Request distribution (uniform/zipfian/hotspot/latest) | String | uniform |
| insertorder | Key generation order (hashed/ordered) | String | hashed |
OBKV-HBase connection parameters
Parameter |
Description |
ODP mode |
Direct connection mode |
|---|---|---|---|
| hbase.oceanbase.odpMode | Connection mode | true | false |
| hbase.oceanbase.odpAddr | ODP address | Required | — |
| hbase.oceanbase.odpPort | ODP port | Required | — |
| hbase.oceanbase.paramURL | Direct connection URL | — | Required |
| hbase.oceanbase.sysUserName | System username | — | Required |
| hbase.oceanbase.sysPassword | System password | — | Required |
| hbase.oceanbase.fullUserName | Username (user@tenant#cluster) | Required | Required |
| hbase.oceanbase.password | Password | Required | Required |
| hbase.oceanbase.database | Database name | Required | Required |
| hbase.oceanbase.table | Table name | Required | Required |
| hbase.oceanbase.columnFamily | Column family name | Required | Required |
OBKV-HBase test parameters
Mode |
obkv.testMode value |
Applicable partition type |
Additional requirement |
|---|---|---|---|
| Default mode | default | Primary key/range-partitioned table | None |
| Prefix query mode | prefix | Partitioned or subpartitioned tables | insertorder=ordered |
Result interpretation
After the test is complete, analyze the following key metrics to determine whether the test results meet expectations:
Metric |
Description |
Optimization direction |
|---|---|---|
| Throughput(ops/sec) | Operations per second | The higher, the better. |
| AverageLatency(us) | Average latency (μs) | The lower, the better. |
| 95thPercentileLatency(us) | P95 latency | The lower, the better. |
| 99thPercentileLatency(us) | P99 latency | The lower, the better. |
| Return=OK / Return=ERROR | Number of successful and failed operations | ERROR should be 0. |
FAQ
- Errors in read/scan/batch_read: You must first execute
loadto load data. - Prefix mode failure: Check whether insertorder is set to ordered.
- Debugging issues: Set
obkv.debug=trueto enable debug logs. - Uneven data distribution in a key_range table: Check whether the partitioning parameters are consistent with those used when the table was created.
Documentation index
The following documents in the docs/ directory of the project repository provide detailed guidelines for using performance testing:
Document |
Description |
Link |
|---|---|---|
| Quick start | Complete your first test in 5 minutes | getting-started.md |
| Web UI user guide | Complete GUI operation instructions | guide-webui.md |
| Command-line usage guide | Full instructions for the command-line method | guide-cli.md |
| Complete parameter list | Meanings, types, and default values of all parameters | params-reference.md |
| Workload reference | Workload file templates and examples | workload-reference.md |
| OBKV-HBase module reference | Table model, test modes, and partitioning strategy | module-obkv-hbase.md |
| Web UI architecture design | Architecture, SSE, and resource isolation | webui-architecture.md |
| Web UI API reference | REST API documentation | webui-api-reference.md |
| FAQ | Frequently asked questions | faq.md |