# Understanding the R-Nacos Loadtest Workspace Member for Performance Testing

> Discover the R-Nacos loadtest workspace member, a Rust sub-project for performance testing RNacos. Simulate thousands of concurrent users with the Goose framework against configuration and naming APIs.

- Repository: [Nacos Group/r-nacos](https://github.com/nacos-group/r-nacos)
- Tags: performance
- Published: 2026-03-07

---

**The loadtest workspace member is a dedicated Rust sub-project that provides a standalone performance-testing suite for the RNacos server, utilizing the Goose load-testing framework to simulate thousands of concurrent virtual users against configuration and naming service APIs.**

The `nacos-group/r-nacos` repository includes a specialized `loadtest` workspace member designed to isolate performance-testing code from the main server crate. This workspace member enables developers to benchmark the Rust-based RNacos implementation under realistic traffic patterns using configurable load scenarios that exercise the configuration center and naming center APIs.

## What Is the Loadtest Workspace Member?

The `loadtest` workspace member is declared in the root [[`Cargo.toml`](https://github.com/nacos-group/r-nacos/blob/main/Cargo.toml)](https://github.com/nacos-group/r-nacos/blob/master/Cargo.toml#L30-L36) as a first-class Cargo package within the `members` array. This architectural decision isolates performance-testing dependencies—such as the Goose load-testing library and `ratelimiter_rs`—from the main server binary, ensuring the production crate remains lightweight.

By organizing the performance suite as a dedicated workspace member, the project provides a **reproducible, configurable harness** for benchmarking RNacos under realistic traffic patterns. The member contains multiple binary targets located in `loadtest/src/bin/`, each implementing a specific load scenario against the RNacos HTTP and gRPC APIs.

## How the Loadtest Suite Implements Performance Testing

The loadtest workspace member implements load generation through a combination of the Goose framework, targeted API scenarios, and per-user rate limiting to prevent client-side bottlenecks.

### Goose Load-Testing Framework

The suite uses the **Goose** library—a Rust equivalent of Python's Locust—to drive thousands of virtual users. Each user executes a series of *scenarios* that map directly to RNacos public APIs. According to the source code in [[`http_config_set.rs`](https://github.com/nacos-group/r-nacos/blob/main/http_config_set.rs)](https://github.com/nacos-group/r-nacos/blob/master/loadtest/src/bin/http_config_set.rs#L3-L4), the framework initializes a `GooseAttack` that registers multiple scenarios with assigned weights, allowing proportional distribution of traffic across different API endpoints.

### Core Performance Scenarios

The loadtest workspace member exercises four core RNacos usage patterns, each implemented as a separate binary target:

1. **Configuration Center – Set**: POST requests to `/nacos/v1/cs/configs` implemented in [`http_config_set.rs`](https://github.com/nacos-group/r-nacos/blob/main/http_config_set.rs)
2. **Configuration Center – Query**: GET requests to `/nacos/v1/cs/configs` implemented in [`http_config_query.rs`](https://github.com/nacos-group/r-nacos/blob/main/http_config_query.rs)
3. **Naming Center – Beat/Register**: HTTP heartbeat registration and gRPC registration implemented in [`http_naming_beat.rs`](https://github.com/nacos-group/r-nacos/blob/main/http_naming_beat.rs) and [`grpc_naming_register.rs`](https://github.com/nacos-group/r-nacos/blob/main/grpc_naming_register.rs)
4. **Naming Center – Query**: GET requests to `/nacos/v1/ns/instance/list` implemented in [`http_naming_query.rs`](https://github.com/nacos-group/r-nacos/blob/main/http_naming_query.rs)

### Per-Virtual-User Rate Limiting

To avoid overwhelming the client machine while still achieving high aggregate QPS, each virtual user carries a `QpsLimiter` from the `ratelimiter_rs` crate. As implemented in [[`http_config_set.rs`](https://github.com/nacos-group/r-nacos/blob/main/http_config_set.rs)](https://github.com/nacos-group/r-nacos/blob/master/loadtest/src/bin/http_config_set.rs#L13-L18), the limiter caps the per-user request rate. When the limiter denies a request, the user session pauses for a microsecond to yield control to other tasks:

```rust
if let Some(user_session) = user.get_session_data_mut::<UserSession>() {
    if !user_session.limiter.acquire() {
        tokio::time::sleep(Duration::from_micros(1)).await;
        return Ok(());
    }
    // Request construction and transmission logic follows
}

```

## Running Performance Tests with the Loadtest Binaries

The loadtest workspace member exposes several binary targets that accept standard Goose command-line flags. You can launch a performance test using `cargo run` with the `--bin` flag specifying the scenario.

### Benchmarking the Configuration Set API

To execute a 60-second benchmark against the HTTP Config Set endpoint, increasing by 10 users per second up to 100 concurrent users:

```bash
cargo run --bin http_config_set --release -- \
    --host http://127.0.0.1:8848 \
    -r 10 -u 100 -t 60 \
    --report-file report_config_set.html

```

This command invokes the `http_config_set` binary, which registers a Goose scenario that repeatedly POSTs configuration data to `/nacos/v1/cs/configs`.

### Scenario Registration Structure

Each binary initializes a `GooseAttack` and registers scenarios with transactions. The following excerpt from [[`http_config_set.rs`](https://github.com/nacos-group/r-nacos/blob/main/http_config_set.rs)](https://github.com/nacos-group/r-nacos/blob/master/loadtest/src/bin/http_config_set.rs#L22-L28) demonstrates the registration pattern:

```rust
GooseAttack::initialize()?
    .register_scenario(
        scenario!("ConfigSet")
            .set_weight(1).unwrap()
            .register_transaction(
                transaction!(set_config)
                    .set_name("/nacos/v1/cs/configs")
            ),
    )
    .execute()
    .await?;

```

## Extending the Loadtest Suite

Adding new performance tests requires creating a new source file under `loadtest/src/bin/` following the established pattern. The workspace layout automatically detects new binaries as separate executables.

To add a custom scenario, create [`loadtest/src/bin/http_custom.rs`](https://github.com/nacos-group/r-nacos/blob/main/loadtest/src/bin/http_custom.rs) with this skeleton:

```rust
#[tokio::main]
async fn main() -> Result<(), GooseError> {
    GooseAttack::initialize()?
        .register_scenario(
            scenario!("MyCustom")
                .set_weight(1).unwrap()
                .register_transaction(transaction!(my_tx).set_name("/my/api")),
        )
        .execute()
        .await?;
    Ok(())
}

```

Run the new test using:

```bash
cargo run --bin http_custom --release -- \
    --host http://127.0.0.1:8848 -r 5 -u 50 -t 30 \
    --report-file my_custom_report.html

```

## Summary

- The **loadtest workspace member** is a standalone Cargo package declared in the root [`Cargo.toml`](https://github.com/nacos-group/r-nacos/blob/main/Cargo.toml) that isolates performance-testing code from the main RNacos server.
- It utilizes the **Goose** load-testing framework to drive thousands of virtual users against HTTP and gRPC endpoints.
- Four core scenarios cover configuration set/query and naming beat/query operations, each implemented as a separate binary in `loadtest/src/bin/`.
- **Per-user rate limiting** via `QpsLimiter` prevents client-side bottlenecks during high-throughput tests.
- The suite supports standard Goose CLI flags (`--host`, `-u`, `-r`, `-t`, `--report-file`) for configurable test execution and HTML reporting.

## Frequently Asked Questions

### What testing framework does the loadtest workspace member use?

The loadtest workspace member uses **Goose**, a Rust load-testing framework inspired by Python's Locust. Goose enables the definition of scalable scenarios where thousands of virtual users execute transactions against RNacos APIs, as seen in the scenario registrations within [`loadtest/src/bin/http_config_set.rs`](https://github.com/nacos-group/r-nacos/blob/main/loadtest/src/bin/http_config_set.rs).

### How do I run a specific load test scenario?

Execute `cargo run --bin <scenario_name> --release --` followed by Goose flags. For example, `cargo run --bin http_config_set --release -- --host http://127.0.0.1:8848 -u 100 -t 60` runs the configuration set test with 100 users for 60 seconds. Available binaries include `http_config_set`, `http_config_query`, `http_naming_beat`, and `http_naming_query`.

### Can I test the original Java Nacos server with this tool?

Yes. Because RNacos maintains API compatibility with the original Java Nacos server, the loadtest workspace member can target either implementation. Simply adjust the `--host` flag to point to a Java Nacos instance endpoint; the HTTP request patterns remain identical.

### How does the suite prevent overwhelming the client during high-load tests?

Each virtual user maintains a `QpsLimiter` instance from the `ratelimiter_rs` crate that controls the per-user request rate. When the limiter blocks a request, the user yields execution for a microsecond, preventing CPU saturation on the load generator while allowing aggregate traffic to reach the target QPS.