### Quick Start: Combined Publish and Subscribe

Source: https://github.com/emqx/emqttb/blob/master/README.adoc

Combines publishing and subscribing scenarios in a single command to run concurrently.

```bash
emqttb -L 30s  @pub -t 't/%n' -I 10ms -i 10ms -N 100 -s 1kb \
               @sub -t 't/#' -I 10ms -N 10 @g -h 127.0.0.1
```

--------------------------------

### Quick Start: Publish Traffic

Source: https://github.com/emqx/emqttb/blob/master/README.adoc

Starts 100 clients publishing messages to localhost with specified intervals and message size. Run steady traffic for 30s and then exit.

```bash
emqttb --loiter 30s \
       @pub --topic 't/%n' --conninterval 10ms --pubinterval 10ms --num-clients 100 --size 1kb \
       @g --host 127.0.0.1
```

```bash
emqttb -L 30s @pub -t 't/%n' -I 10ms -i 10ms -N 100 -s 1kb @g -h 127.0.0.1
```

--------------------------------

### Quick Start: Subscribe Traffic

Source: https://github.com/emqx/emqttb/blob/master/README.adoc

Starts 10 clients subscribing to a wildcard topic and running steady traffic for 30s.

```bash
emqttb --loiter 30s \
       @sub --topic 't/#' --conninterval 10ms --num-clients 10 \
       @g --host 127.0.0.1
```

```bash
emqttb -L 30s @sub -t 't/#' -I 10ms -N 10 @g -h 127.0.0.1
```

--------------------------------

### Get Help for EMQTTB CLI Commands

Source: https://github.com/emqx/emqttb/blob/master/README.adoc

Display the manual page for a specific EMQTTB CLI command, such as 'pub'.

```bash
emqttb --help pub
```

--------------------------------

### Build EMQTT Bench Release Tarball

Source: https://context7.com/emqx/emqttb/llms.txt

Instructions for cloning the repository and building the release tarball using Erlang/OTP 24+ and rebar3. Includes macOS specific setup.

```bash
git clone git@github.com:emqx/emqttb.git
cd emqttb
make release
# Binary is symlinked at ./emqttb
```

```bash
# macOS (Homebrew)
brew install erlang rebar3 cmake texi2html texinfo
export MANPAGE_STYLESHEET=$(brew --prefix docbook-xsl)/docbook-xsl/manpages/docbook.xsl
make release
```

```bash
# Skip building docs
export CAN_BUILD_DOCS=false
make release
```

```bash
# Run in-place
./_build/default/bin/emqttb --help
```

--------------------------------

### Start emqttb with REST API Enabled

Source: https://context7.com/emqx/emqttb/llms.txt

Start emqttb with the `--restapi` flag to expose a REST API on port 8017 for health checks and scenario polling.

```bash
# Start with REST API enabled
emqttb --restapi @pub -t 't/%n' -N 100 -L 60s @g -h 127.0.0.1 &
```

--------------------------------

### Build EMQTTB on macOS with Homebrew

Source: https://github.com/emqx/emqttb/blob/master/README.adoc

Build EMQTTB on macOS using Homebrew to install dependencies. Ensure Erlang/OTP 24+, rebar3, cmake, texi2html, and texinfo are installed.

```bash
brew install erlang rebar3 cmake texi2html texinfo
git clone git@github.com:emqx/emqttb.git
cd emqttb
export MANPAGE_STYLESHEET=$(brew --prefix docbook-xsl)/docbook-xsl/manpages/docbook.xsl
make release
```

--------------------------------

### Full Cluster Benchmark with Grafana Integration

Source: https://context7.com/emqx/emqttb/llms.txt

This example demonstrates a mixed pub/sub benchmark on a 3-node cluster, configured with autorate control, metrics pushed to Prometheus, and annotations sent to Grafana. Environment variables for Grafana API key and URL must be set.

```bash
export EMQTTB_METRICS__GRAFANA__API_KEY="Bearer <your-key>"
export EMQTTB_METRICS__GRAFANA__URL="http://grafana.internal:3000"

emqttb \
  --loiter 5min \
  --restapi \
  --grafana \
  --pushgw --pushgw-url http://prometheus-gw.internal:9091 \
  @pubsub_fwd \
    --num-clients 1000 \
    --full-forwarding \
    --pub-qos 1 --sub-qos 1 \
    --size 256 \
    --pubinterval 1ms \
    --conninterval 5ms \
  @a -a pubsub_fwd/pubinterval \
     --pvar '[scenarios,pubsub_fwd,{},pub,metrics,pub_latency,pending]' \
     --setpoint 0 --speed 10000 \
  @a -a pubsub_fwd/conninterval \
     --pvar '[scenarios,pubsub_fwd,{},pub,metrics,conn_latency,pending]' \
     --olp --olp-threshold 500 \
  @g -h broker1.internal,broker2.internal,broker3.internal
```

```bash
# Poll scenario stage from a CI pipeline
while true; do
  stage=$(curl -s http://localhost:8017/scenario/pubsub_fwd/stage)
  echo "Stage: $stage"
  [ "$stage" = "complete" ] && break
  sleep 5
done
```

--------------------------------

### EMQTT Bench @sub Scenario - Subscribe Load

Source: https://context7.com/emqx/emqttb/llms.txt

Examples of using the @sub scenario to generate MQTT subscribe load. Demonstrates wildcard subscriptions, QoS, end-to-end latency measurement, persistent sessions, and message sequence verification.

```bash
# 10 subscribers on wildcard topic, 30s
emqttb --loiter 30s \
       @sub --topic 't/#' \
            --conninterval 10ms \
            --num-clients 10 \
       @g --host 127.0.0.1
```

```bash
# QoS 1 subscription with end-to-end latency measurement (publisher must use --metadata)
emqttb -L 60s @sub -t 'bench/#' -N 100 -q 1 --parse-metadata @g -h 127.0.0.1
```

```bash
# Persistent session: disable clean start, set session expiry
emqttb -L 60s @sub -t 'pers/#' -N 50 +c --expiry 86400 -q 2 @g -h broker.example.com
```

```bash
# Verify message sequence integrity (gaps and repeats detection)
emqttb -L 30s @sub -t 'seq/#' -N 20 --verify-sequence @g -h broker.example.com
```

```bash
# Combined pub+sub in one command (100 publishers + 10 subscribers)
emqttb -L 30s \
       @pub -t 't/%n' -I 10ms -i 10ms -N 100 -s 1kb \
       @sub -t 't/#'  -I 10ms -N 10 \
       @g -h 127.0.0.1
```

--------------------------------

### EMQTT Bench @pub Scenario - Publish Load

Source: https://context7.com/emqx/emqttb/llms.txt

Examples of using the @pub scenario to generate MQTT publish load. Covers various configurations like message size, interval, QoS, retained messages, persistent sessions, and random payloads.

```bash
# 100 publishers to localhost, 1 KB messages, every 10ms, for 30s
emqttb --loiter 30s \
       @pub --topic 't/%n' \
            --conninterval 10ms \
            --pubinterval 10ms \
            --num-clients 100 \
            --size 1kb \
            --qos 1 \
       @g --host 127.0.0.1
```

```bash
# Retained messages with metadata (enables latency tracking on subscriber side)
emqttb -L 60s @pub -t 'bench/%n' -i 100ms -N 200 -s 512 --retain --metadata @g -h broker.host
```

```bash
# QoS 2 with persistent session (no clean start) and session expiry
emqttb -L 30s @pub -t 'pers/%n' -N 10 --qos 2 +c --expiry 3600 @g -h 127.0.0.1
```

```bash
# Multi-loadgen alignment: start numbering clients from 1000
emqttb -L 30s @pub -t 'bench/%n' -N 100 --start-n 1000 @g -h broker.example.com
```

```bash
# Random message payload content
emqttb -L 30s @pub -t 'load/%n' -N 50 -s 256 --random @g -h broker.example.com
```

--------------------------------

### Benchmark MQTT Connection Handshake with @conn

Source: https://context7.com/emqx/emqttb/llms.txt

Use the @conn scenario to measure connection throughput and session setup performance. It ramps up idle connections over time. Persistent sessions can be configured with the --expiry option.

```bash
emqttb -L 60s @conn --num-clients 1000 --conninterval 5ms @g -h 127.0.0.1
```

```bash
emqttb -L 30s @conn -N 500 -I 10ms +C --expiry 3600 @g -h broker.example.com
```

```bash
emqttb -L 30s @conn -N 200 -I 5ms @g -h 127.0.0.1
```

--------------------------------

### Get Scenario Stage via REST API

Source: https://context7.com/emqx/emqttb/llms.txt

Poll the current stage of a running scenario (e.g., `ramp_up`, `run_traffic`, `complete`) using the `/scenario/<name>/stage` endpoint.

```bash
# Get current stage of a running scenario
curl -s http://localhost:8017/scenario/pub/stage
# Response: "ramp_up" | "run_traffic" | "complete"

curl -s http://localhost:8017/scenario/sub/stage
# Response: "ramp_up" | "run_traffic" | "complete"
```

--------------------------------

### REST API Endpoints

Source: https://context7.com/emqx/emqttb/llms.txt

When started with `--restapi`, emqttb exposes a REST API on port 8017 (default). This enables health-checking and scenario-stage polling from external test orchestrators.

```APIDOC
## REST API Endpoints

When started with `--restapi`, emqttb exposes a REST API on port 8017 (default). This enables health-checking and scenario-stage polling from external test orchestrators.

```bash
# Start with REST API enabled
emqttb --restapi @pub -t 't/%n' -N 100 -L 60s @g -h 127.0.0.1 &

# Health check — always returns HTTP 200 with empty body
curl -s http://localhost:8017/healthcheck
# Response: HTTP 200

# Get current stage of a running scenario
curl -s http://localhost:8017/scenario/pub/stage
# Response: "ramp_up" | "run_traffic" | "complete"

curl -s http://localhost:8017/scenario/sub/stage
# Response: "ramp_up" | "run_traffic" | "complete"

# Prometheus metrics scrape endpoint
curl -s http://localhost:8017/metrics

# Reload configuration (equivalent to SIGHUP)
curl -s -X POST http://localhost:8017/conf/reload

# Browse HTML documentation
curl -s http://localhost:8017/doc/index.html
```
```

--------------------------------

### Benchmark Forwarded Pub/Sub Across Nodes with @pubsub_fwd

Source: https://context7.com/emqx/emqttb/llms.txt

Use @pubsub_fwd to test cross-node message forwarding in a multi-host broker setup. Full forwarding ensures messages traverse the cluster. Disable full forwarding for same-node pub/sub tests. Multi-loadgen alignment is supported with --start-n.

```bash
emqttb -L 60s \
       @pubsub_fwd --num-clients 100 \
                   --full-forwarding \
                   --pub-qos 1 --sub-qos 1 \
                   --size 256 -i 10ms -I 5ms \
       @g -h broker1.host,broker2.host,broker3.host
```

```bash
emqttb -L 30s @pubsub_fwd -n 100 --no-full-forwarding -i 10ms @g -h 127.0.0.1
```

```bash
emqttb -L 60s @pubsub_fwd -n 200 --start-n 1000 -i 5ms @g -h broker1.host,broker2.host
```

--------------------------------

### Custom Client Group Configurations for Scenarios

Source: https://github.com/emqx/emqttb/blob/master/README.adoc

Shows how to use different client group configurations for different scenarios, such as using WebSocket for publishers and MQTT for subscribers.

```bash
emqttb @pub -t 'foo/%n' -g wss \
       @sub -t 'foo/#' -g mqtt \
       @g -g wss -h localhost --transport ws --ssl \
       @g -g mqtt -h localhost --transport sock
```

--------------------------------

### EMQTT Bench CLI Structure and Scoped Actions

Source: https://context7.com/emqx/emqttb/llms.txt

Demonstrates the command-line interface structure of emqttb, including global flags and action scopes prefixed with '@'. Shows how to use short forms and disable boolean flags.

```bash
# Anatomy: global args, then action scopes
emqttb --loiter 30s \
       @pub --topic 't/%n' --conninterval 10ms --pubinterval 10ms --num-clients 100 --size 1kb \
       @g --host 127.0.0.1
```

```bash
# Short form (equivalent)
emqttb -L 30s @pub -t 't/%n' -I 10ms -i 10ms -N 100 -s 1kb @g -h 127.0.0.1
```

```bash
# Disable a boolean flag with no- prefix
emqttb --no-pushgw @pub -t 'test/%n' @g -h broker.example.com
```

```bash
# Disable a short boolean flag using + sigil
emqttb @sub +c -t 'test/#' -N 50 @g -h broker.example.com
```

```bash
# Get per-action help
emqttb --help pub
emqttb --help sub
emqttb --help conn
```

```bash
# Logs go to /tmp/emqttb.log — stdout stays clean
```

--------------------------------

### Understanding EMQTTB CLI Structure

Source: https://github.com/emqx/emqttb/blob/master/README.adoc

Illustrates the structure of EMQTTB CLI arguments, including global arguments, actions, and positional arguments within action scopes.

```bash
emqttb --foo --bar 1 positional1 positional2 @action1 --foo 1 positional1 @action2 ...
       |___________| |_____________________|          |_________________|
       |regular args    positional args    |
       |___________________________________|
                 global scope
```

--------------------------------

### Dump and Replay Configuration with EMQTT Bench

Source: https://context7.com/emqx/emqttb/llms.txt

Use `emqttb --conf-dump` to save the current benchmark configuration to a file. Replay this configuration using the `--again` flag.

```bash
emqttb --conf-dump /tmp/last-run.conf @pub -t 't/%n' -N 100 @g -h 127.0.0.1
emqttb --conf-dump /tmp/last-run.conf --again
```

--------------------------------

### Default Client Group Configuration

Source: https://github.com/emqx/emqttb/blob/master/README.adoc

Demonstrates using the default client group configuration for the @pub scenario.

```bash
emqttb @pub -t foo @g -h localhost
```

```bash
emqttb @pub -t foo --group default @g --group default -h localhost
```

--------------------------------

### Use Configuration File with emqttb

Source: https://context7.com/emqx/emqttb/llms.txt

Specify a configuration file using the `--conf-file` option when running emqttb.

```bash
# Use a configuration file
emqttb --conf-file /etc/emqttb/my-bench.conf @pub -t 't/%n' @g -h broker.host
```

--------------------------------

### List Available Resources with EMQTT Bench

Source: https://context7.com/emqx/emqttb/llms.txt

The `@ls` action lists available autorate IDs and metric keys. Use `emqttb @ls autorate` to list autorate IDs and `emqttb @ls metric` to list metric IDs.

```bash
# List all autorate IDs available in the model
emqttb @ls autorate
# Output includes: pub/conninterval, pub/pubinterval, sub/conninterval,
#   pubsub_fwd/conninterval, pubsub_fwd/pubinterval,
#   persistent_session/conninterval, persistent_session/pubinterval, etc.

# List all metric IDs (use with --pvar in @a)
emqttb @ls metric
```

--------------------------------

### Enable Grafana Annotations

Source: https://context7.com/emqx/emqttb/llms.txt

Integrate with Grafana by setting `EMQTTB_METRICS__GRAFANA__API_KEY` and `EMQTTB_METRICS__GRAFANA__URL` environment variables, then enable annotations with the `--grafana` flag.

```bash
# Set Grafana API key and URL via environment variables, then enable annotations
export EMQTTB_METRICS__GRAFANA__API_KEY="Bearer eyJrIjoiNmhSdTFnWGJlaE9tZXQ2YXI4WlEyUGNSMXFMb1oyUXkiLCJuIjoiZW1xdHRiIiwiaWQiOjF9"
export EMQTTB_METRICS__GRAFANA__URL="http://localhost:3000"
emqttb --grafana @pub -t 't/%n' -N 100 @g -h 127.0.0.1
```

--------------------------------

### Set Default Number of Clients via Environment Variable

Source: https://context7.com/emqx/emqttb/llms.txt

Set the default number of clients for benchmarks using the `EMQTTB_N_CLIENTS` environment variable.

```bash
# Set default number of clients
export EMQTTB_N_CLIENTS=500
```

--------------------------------

### Clone EMQTTB Repository and Build Release

Source: https://github.com/emqx/emqttb/blob/master/README.adoc

Clone the EMQTTB repository and build the release version. Requires Erlang/OTP 24+, rebar3, make, and cmake.

```bash
git clone git@github.com:emqx/emqttb.git
cd emqttb
make release
```

--------------------------------

### Set Default Broker Host via Environment Variable

Source: https://context7.com/emqx/emqttb/llms.txt

Configure the default broker host using the `EMQTTB_GROUPS__DEFAULT__HOST` environment variable.

```bash
# Set default broker host
export EMQTTB_GROUPS__DEFAULT__HOST="broker.example.com"
```

--------------------------------

### Enabling Prometheus Pushgateway

Source: https://github.com/emqx/emqttb/blob/master/README.adoc

Enables EMQTTB to export metrics to a Prometheus Pushgateway.

```bash
emqttb --pushgw --pushgw-url http://localhost:9091
```

--------------------------------

### Environment Variable Configuration

Source: https://context7.com/emqx/emqttb/llms.txt

All configuration keys can be set via environment variables using the `EMQTTB_` prefix and `__` as the path separator. Environment variables have lower priority than CLI arguments.

```APIDOC
## Environment Variable Configuration

All configuration keys can be set via environment variables using the `EMQTTB_` prefix and `__` as the path separator. Environment variables have lower priority than CLI arguments.

```bash
# Set default broker host
export EMQTTB_GROUPS__DEFAULT__HOST="broker.example.com"

# Set Grafana integration
export EMQTTB_METRICS__GRAFANA__API_KEY="Bearer <token>"
export EMQTTB_METRICS__GRAFANA__URL="http://grafana.host:3000"

# Set default number of clients
export EMQTTB_N_CLIENTS=500

# Set default publish/connect interval
export EMQTTB_INTERVAL=10ms

# Use a configuration file
emqttb --conf-file /etc/emqttb/my-bench.conf @pub -t 't/%n' @g -h broker.host
```
```

--------------------------------

### Set Default Interval via Environment Variable

Source: https://context7.com/emqx/emqttb/llms.txt

Set the default publish or connect interval using the `EMQTTB_INTERVAL` environment variable.

```bash
# Set default publish/connect interval
export EMQTTB_INTERVAL=10ms
```

--------------------------------

### Set Grafana Integration via Environment Variables

Source: https://context7.com/emqx/emqttb/llms.txt

Configure Grafana integration by setting the `EMQTTB_METRICS__GRAFANA__API_KEY` and `EMQTTB_METRICS__GRAFANA__URL` environment variables.

```bash
# Set Grafana integration
export EMQTTB_METRICS__GRAFANA__API_KEY="Bearer <token>"
export EMQTTB_METRICS__GRAFANA__URL="http://grafana.host:3000"
```

--------------------------------

### Import Bundled Grafana Dashboard

Source: https://context7.com/emqx/emqttb/llms.txt

Import the bundled `emqttb-dashboard.json` file into Grafana to visualize key metrics.

```bash
# Import the bundled Grafana dashboard JSON:
# emqttb-dashboard.json tracks: workers, spawn rate, messages/s, latency,
# autorate, pending ops, persistent session throughput, gap/repeat counts
```

--------------------------------

### Configure Grafana API Key and URL

Source: https://github.com/emqx/emqttb/blob/master/README.adoc

Set environment variables for Grafana API key and URL to enable EMQTTB to add annotations to Grafana dashboards. Requires a Grafana API key with 'Editor' role.

```bash
export EMQTTB_METRICS__GRAFANA__API_KEY="Bearer eyJrIjoiNmhSdTFnWGJlaE9tZXQ2YXI4WlEyUGNSMXFMb1oyUXkiLCJuIjoiZW1xdHRiIiwiaWQiOjF9"
export EMQTTB_METRICS__GRAFANA__URL="http://localhost:3000"
emqttb --grafana ...
```

--------------------------------

### Autorate Action for Dynamic Rate Control

Source: https://context7.com/emqx/emqttb/llms.txt

Use the `@a` action to create an autorate instance for dynamic rate control. This PI controller adjusts variables like publish interval based on process variables. The `--olp` flag enables SCRAM for emergency rate override during broker overload.

```bash
# Auto-adjust pub interval to keep pending pub operations near 0
emqttb @pub -t 't/%n' -N 100 \
       @a --autorate pub/pubinterval \
          --pvar '[scenarios,pub,{},metrics,pub_latency,pending]' \
          --setpoint 0 \
          --speed 10000 \
          --Kp 0.05 \
       @g -h 127.0.0.1
```

```bash
# Auto-adjust connection interval with SCRAM overload protection
emqttb @pub -t 't/%n' -N 500 \
       @a -a pub/conninterval \
          --pvar '[scenarios,pub,{},metrics,conn_latency,pending]' \
          --olp \
          --olp-threshold 500 \
          --olp-override 10s \
          --olp-hysteresis 50 \
       @g -h broker.example.com
```

```bash
# Manually set autorate speed and min/max bounds
emqttb @pub -t 'bench/%n' -N 200 \
       @a -a pub/pubinterval --speed 5000 --min 1000 --max 60000000 \
       @g -h 127.0.0.1
```

--------------------------------

### List Available Autorate IDs

Source: https://context7.com/emqx/emqttb/llms.txt

Use `emqttb @ls autorate` to list all available autorate identifiers.

```bash
emqttb @ls autorate
```

--------------------------------

### Browse HTML Documentation via REST API

Source: https://context7.com/emqx/emqttb/llms.txt

Browse the HTML documentation by accessing the `/doc/index.html` endpoint of the REST API.

```bash
# Browse HTML documentation
curl -s http://localhost:8017/doc/index.html
```

--------------------------------

### Configure Client Group with @g Action

Source: https://context7.com/emqx/emqttb/llms.txt

The @g action configures MQTT connection parameters like host, transport, TLS, and credentials for client groups. Multiple @g blocks can define different transport requirements. This includes specifying ports, WebSocket transport with SSL, multiple broker hosts for round-robin, and username/password authentication.

```bash
emqttb @pub -t 'test/%n' -N 100 @g --host 127.0.0.1
```

```bash
emqttb @pub -t 'test/%n' -N 100 @g --group default --host broker.example.com --port 1883
```

```bash
emqttb @pub -t 'ws/%n' -g wss -N 50 @g -g wss -h broker.example.com --transport ws --ssl
```

```bash
emqttb @pub -t 'foo/%n' -g wss @sub -t 'foo/#' -g mqtt \
       @g -g wss  -h localhost --transport ws --ssl \
       @g -g mqtt -h localhost --transport sock
```

```bash
emqttb @pub -t 't/%n' -N 300 @g -h broker1.host,broker2.host,broker3.host
```

```bash
emqttb @pub -t 'secure/%n' -N 100 @g -h broker.example.com --username testuser --password secret
```

```bash
emqttb @pub -t 'v5/%n' -N 50 @g -h 127.0.0.1 --mqtt-version v5
```

--------------------------------

### List Available Metric IDs for --pvar

Source: https://context7.com/emqx/emqttb/llms.txt

Use `emqttb @ls metric` to list all available metric identifiers that can be used with the `--pvar` option.

```bash
emqttb @ls metric
```

--------------------------------

### Reload Configuration via REST API

Source: https://context7.com/emqx/emqttb/llms.txt

Reload the emqttb configuration, equivalent to sending a SIGHUP signal, by sending a POST request to the `/conf/reload` endpoint.

```bash
# Reload configuration (equivalent to SIGHUP)
curl -s -X POST http://localhost:8017/conf/reload
```

--------------------------------

### Test Broker Stability with @sub_flapping

Source: https://context7.com/emqx/emqttb/llms.txt

The @sub_flapping scenario tests broker stability under connect/disconnect churn by repeatedly cycling subscriber groups. Configure the topic, number of clients, connection interval, and number of cycles. Persistent sessions and QoS levels can also be specified.

```bash
emqttb @sub_flapping --topic 'flap/#' \
                     --num-clients 50 \
                     --conninterval 5ms \
                     --cycles 10 \
       @g -h 127.0.0.1
```

```bash
emqttb @sub_flapping -t 'flap/#' -N 100 -I 5ms -C 5 -q 1 +c --expiry 60 @g -h 127.0.0.1
```

--------------------------------

### Test Collocated Pub/Sub with @pubsub Scenario

Source: https://context7.com/emqx/emqttb/llms.txt

The @pubsub scenario is suitable for testing fan-out patterns on a single broker node. Each client publishes and subscribes independently. Metadata can be parsed for latency tracking, and QoS levels can be specified.

```bash
emqttb -L 30s \
       @pubsub --num-clients 100 \
               --pub-topic 'pubsub/pub/%n' \
               --sub-topic 'pubsub/sub/%n' \
               --pubinterval 50ms \
               --size 256 \
               --conninterval 10ms \
       @g -h 127.0.0.1
```

```bash
emqttb -L 60s \
       @pubsub -N 50 --pub-qos 1 --sub-qos 1 --parse-metadata \
               --pub-topic 'load/pub/%n' --sub-topic 'load/sub/%n' \
               -i 100ms -I 10ms -s 512 \
       @g -h 127.0.0.1
```

--------------------------------

### Grafana Integration

Source: https://context7.com/emqx/emqttb/llms.txt

emqttb integrates with Grafana to use the bundled dashboard (`emqttb-dashboard.json`) and to annotate dashboards when scenario stages start/advance/finish.

```APIDOC
## Grafana Integration — Dashboard and Annotations

emqttb integrates with Grafana to use the bundled dashboard (`emqttb-dashboard.json`) and to annotate dashboards when scenario stages start/advance/finish.

```bash
# Set Grafana API key and URL via environment variables, then enable annotations
export EMQTTB_METRICS__GRAFANA__API_KEY="Bearer eyJrIjoiNmhSdTFnWGJlaE9tZXQ2YXI4WlEyUGNSMXFMb1oyUXkiLCJuIjoiZW1xdHRiIiwiaWQiOjF9"
export EMQTTB_METRICS__GRAFANA__URL="http://localhost:3000"
emqttb --grafana @pub -t 't/%n' -N 100 @g -h 127.0.0.1

# Import the bundled Grafana dashboard JSON:
# emqttb-dashboard.json tracks: workers, spawn rate, messages/s, latency,
# autorate, pending ops, persistent session throughput, gap/repeat counts
```
```

--------------------------------

### Autorate Action

Source: https://context7.com/emqx/emqttb/llms.txt

The `@a` action creates an autorate instance, a velocity-form PI controller that adjusts a control variable to minimize error against a setpoint. The `--olp` flag enables SCRAM for emergency rate override when the broker is overloaded.

```APIDOC
## `@a` Autorate Action — Dynamic Rate Control (PI Controller)

The `@a` action creates an autorate instance: a velocity-form PI controller that adjusts a control variable (e.g., publish interval) to minimize error against a setpoint derived from a process variable (e.g., pending operations count). The `--olp` flag enables SCRAM (emergency rate override when the broker is overloaded).

```bash
# Auto-adjust pub interval to keep pending pub operations near 0
emqttb @pub -t 't/%n' -N 100 \
       @a --autorate pub/pubinterval \
          --pvar '[scenarios,pub,{},metrics,pub_latency,pending]' \
          --setpoint 0 \
          --speed 10000 \
          --Kp 0.05 \
       @g -h 127.0.0.1

# Auto-adjust connection interval with SCRAM overload protection
emqttb @pub -t 't/%n' -N 500 \
       @a -a pub/conninterval \
          --pvar '[scenarios,pub,{},metrics,conn_latency,pending]' \
          --olp \
          --olp-threshold 500 \
          --olp-override 10s \
          --olp-hysteresis 50 \
       @g -h broker.example.com

# Manually set autorate speed and min/max bounds
emqttb @pub -t 'bench/%n' -N 200 \
       @a -a pub/pubinterval --speed 5000 --min 1000 --max 60000000 \
       @g -h 127.0.0.1

# List available autorate IDs
emqttb @ls autorate

# List available metric IDs (for --pvar)
emqttb @ls metric
```
```

--------------------------------

### Benchmark Offline Message Delivery with @persistent_session

Source: https://context7.com/emqx/emqttb/llms.txt

The @persistent_session scenario measures broker persistent session throughput by alternating between publishing messages to offline topics and having subscribers reconnect to drain them. Configure the number of publishers/subscribers, publish time, cycles, QoS, and message size. Sequence verification and max stuck time can also be set.

```bash
emqttb @persistent_session \
       --num-publishers 10 \
       --num-subscribers 10 \
       --pubtime 1s \
       --cycles 10 \
       --pub-qos 2 --sub-qos 2 \
       --conninterval 5ms \
       --size 256 \
       @g -h 127.0.0.1
```

```bash
emqttb @persistent_session \
       -P 20 -S 20 -T 5s -C 5 \
       --verify-sequence \
       --max-stuck-time 30s \
       @g -h 127.0.0.1
```

--------------------------------

### Push Metrics to Prometheus Push-Gateway

Source: https://context7.com/emqx/emqttb/llms.txt

Push metrics to a Prometheus push-gateway by specifying the `--pushgw` and `--pushgw-url` flags.

```bash
# Push to Prometheus push-gateway
emqttb --pushgw --pushgw-url http://localhost:9091 @pub -t 't/%n' -N 100 @g -h 127.0.0.1
```

--------------------------------

### Prometheus Metrics Export

Source: https://context7.com/emqx/emqttb/llms.txt

emqttb exports metrics to Prometheus either via a push-gateway or a scrape endpoint. The scrape endpoint is enabled with `--restapi`; push-gateway requires explicit flags.

```APIDOC
## Prometheus Metrics Export

emqttb exports metrics to Prometheus either via a push-gateway or a scrape endpoint. The scrape endpoint is enabled with `--restapi`; push-gateway requires explicit flags.

```bash
# Enable Prometheus scrape endpoint (default: http://localhost:8017/metrics)
emqttb --restapi @pub -t 't/%n' -N 100 @g -h 127.0.0.1

# Scrape metrics
curl http://localhost:8017/metrics

# Push to Prometheus push-gateway
emqttb --pushgw --pushgw-url http://localhost:9091 @pub -t 't/%n' -N 100 @g -h 127.0.0.1

# Key Prometheus metrics exposed:
# emqttb_group_n_workers{group}         - number of active workers per group
# emqttb_published_messages{group}      - total published messages counter
# emqttb_received_messages{group}       - total received messages counter
# emqttb_e2e_latency{group}             - end-to-end latency (µs) rolling average
# emqttb_group_op_time{group,operation} - average operation latency (µs)
# emqttb_group_n_pending{group,operation} - pending operations counter
# emqttb_autorate_rate{id}              - current autorate controlled value
# emqttb_gaps_number{group}             - message sequence gap count
# emqttb_repeats_number{group}          - message sequence repeat count
```
```

--------------------------------

### Enable Prometheus Scrape Endpoint

Source: https://context7.com/emqx/emqttb/llms.txt

Enable the Prometheus scrape endpoint by using the `--restapi` flag. The default endpoint is `http://localhost:8017/metrics`.

```bash
# Enable Prometheus scrape endpoint (default: http://localhost:8017/metrics)
emqttb --restapi @pub -t 't/%n' -N 100 @g -h 127.0.0.1
```

--------------------------------

### Scrape Prometheus Metrics

Source: https://context7.com/emqx/emqttb/llms.txt

Scrape metrics from the enabled Prometheus endpoint using `curl`.

```bash
# Scrape metrics
curl http://localhost:8017/metrics
```

--------------------------------

### Prometheus Metrics Scrape Endpoint via REST API

Source: https://context7.com/emqx/emqttb/llms.txt

Access the Prometheus metrics scrape endpoint at `/metrics` via the REST API.

```bash
# Prometheus metrics scrape endpoint
curl -s http://localhost:8017/metrics
```

--------------------------------

### Health Check via REST API

Source: https://context7.com/emqx/emqttb/llms.txt

Perform a health check by accessing the `/healthcheck` endpoint of the REST API. It always returns HTTP 200 with an empty body.

```bash
# Health check — always returns HTTP 200 with empty body
curl -s http://localhost:8017/healthcheck
# Response: HTTP 200
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.