Understanding the R-Nacos Loadtest Workspace Member for Performance Testing

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/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/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
2. Configuration Center – Query: GET requests to /nacos/v1/cs/configs implemented in http_config_query.rs
3. Naming Center – Beat/Register: HTTP heartbeat registration and gRPC registration implemented in http_naming_beat.rs and grpc_naming_register.rs
4. Naming Center – Query: GET requests to /nacos/v1/ns/instance/list implemented in 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/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:

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:

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/master/loadtest/src/bin/http_config_set.rs#L22-L28) demonstrates the registration pattern:

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 with this skeleton:

#[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:

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 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}