Skip to main content

hdds-admin

Command-line administration tool for monitoring HDDS systems via the Gateway REST API.

Overview​

hdds-admin connects to an hdds-gateway instance and provides formatted views of system health, participant mesh, active topics, and runtime metrics. It supports both one-shot queries and continuous watch mode.

  • Health checks -- System status and uptime
  • Mesh view -- Discovered participants with GUID, name, and state
  • Topic listing -- Active topics with writer/reader counts
  • Metrics display -- Message counters and latency percentiles
  • Watch mode -- Continuous dashboard with configurable refresh interval

Installation​

Build from the HDDS workspace:

cd tools/hdds-admin
cargo build --release

Prerequisites​

hdds-admin requires a running hdds-gateway instance connected to your HDDS application:

  1. Enable the Admin API in your application:
let participant = ParticipantBuilder::new()
    .domain_id(0)
    .enable_admin_api(4243)
    .build()?;
  1. Start the gateway:
hdds-gateway --admin-addr 127.0.0.1:4243
  1. Use hdds-admin to query:
hdds-admin health

CLI Reference​

hdds-admin [OPTIONS] <COMMAND>

Options:
  -g, --gateway <URL>    Gateway URL [default: http://127.0.0.1:8080]
  -h, --help             Print help
  -V, --version          Print version

Commands:
  health    Show system health
  mesh      List discovered participants
  topics    Show active topics
  metrics   Show runtime metrics
  info      Show gateway info
  watch     Continuous monitoring dashboard
  status    Show all information (health + mesh + metrics)

Commands​

health​

Show system health status:

hdds-admin health

Output:

HDDS Health Status
  Status:  ok
  Uptime:  1h 23m
  Version: 1.0.0

mesh​

List all discovered DDS participants:

hdds-admin mesh

Output:

Participant Mesh
  Epoch: 42
  Count: 3

+-------------------+------------------+-------+-------+
| GUID              | Name             | Local | State |
+-------------------+------------------+-------+-------+
| 01.0f.aa.bb.cc... | sensor-publisher | yes   | alive |
| 01.0f.dd.ee.ff... | control-node     | yes   | alive |
| 02.01.11.22.33... | remote-monitor   | no    | alive |
+-------------------+------------------+-------+-------+

topics​

Show active topics with type information:

hdds-admin topics

Output:

Active Topics
  Count: 3

+----------------------+------------+---------+---------+
| Name                 | Type       | Writers | Readers |
+----------------------+------------+---------+---------+
| sensor/temperature   | SensorData | 1       | 2       |
| robot/state          | RobotState | 1       | 1       |
| rt/cmd_vel           | Twist      | 0       | 1       |
+----------------------+------------+---------+---------+

metrics​

Show runtime message counters and latency percentiles:

hdds-admin metrics

Output:

Runtime Metrics
  Epoch: 42

  Messages
    Sent:     12.5K
    Received: 8.9K
    Dropped:  0

  Latency
    p50: 45.2 us
    p99: 312.5 us

info​

Show gateway endpoint information:

hdds-admin info

watch​

Continuous monitoring dashboard with configurable refresh:

# Update every second
hdds-admin watch --interval 1

# Update every 5 seconds
hdds-admin watch --interval 5

The watch command clears the terminal and displays a compact dashboard combining health, mesh count, and metrics. Press Ctrl+C to stop.

status​

Combined view of health, mesh, and metrics in a single output:

hdds-admin status

Custom Gateway URL​

By default, hdds-admin connects to http://127.0.0.1:8080. Use --gateway to specify a different address:

# Remote gateway
hdds-admin --gateway http://192.168.1.100:8080 status

# Custom port
hdds-admin --gateway http://localhost:3000 health