Command-line tools

The ursa launcher and the ursa-admin subcommands for inspecting streams, compaction tasks and tables.

Ursa ships a command-line launcher with administrative subcommands for inspecting streams, compaction tasks and locks, and benchmark tools for measuring throughput.

These tools are not on Maven Central

ursa-storage-tools is excluded from the published artifacts, so the launcher and its subcommands come from a source build rather than a dependency. See build from source.

Building produces ursa-storage-<version>-bin.tar.gz under ursa-storage-tools/target. Unpack it and run bin/ursa from the resulting directory.

The launcher

bin/ursa <command> [options]

Command	Runs
`produce`	Benchmark producer.
`consume`	Benchmark consumer.
`tailing-read`	Benchmark tailing reader.
`storage`	Object-store benchmark.
`perf`	Combined benchmark driver.
`admin`	The `ursa-admin` subcommands below.

Anything else is treated as a fully-qualified class name with a main method, which is how the internal tools are reached.

Library settings come from conf/ursa-storage.conf beside the launcher. Environment variables URSA_STORAGE_CONF, URSA_STORAGE_LOG_CONF, URSA_STORAGE_MEM, URSA_STORAGE_GC, URSA_STORAGE_GC_LOG, URSA_STORAGE_EXTRA_OPTS and URSA_STORAGE_EXTRA_CLASSPATH override the defaults, and can also be set in conf/ursa-storage-perf-env.sh.

Administration

bin/ursa admin [-c <configuration-file>] <subcommand> [options]

-c / --config is inherited by every subcommand.

Streams

Subcommand	Purpose
`list`	List all streams.
`read`	Read entries from a stream. Requires `-s` / `--stream-id` and `-o` / `--offset`.
`delete`	Delete a stream. Requires `-s` / `--stream-id`.
`set-delete-prefixes`	Set storage path prefixes for the deletion policy, comma-separated.
`migrate-stream-id`	Migrate stream-id entries from an empty value to JSON stream metadata.

Compaction tasks

Subcommand	Purpose
`get-compact-tasks`	Retrieve compaction tasks from the metadata store. `-n` sets how many (default 100); `-i` runs interactively.
`get-first-n-compact-tasks`	Retrieve the first N tasks for a stream. Requires `-o` / `--oxia-server-addr`.
`commit-tasks`	Commit tasks by hand. `-t` filters by topic.
`update-publish-task-offset`	Rewrite the published-task offset for a stream. Requires `--stream` and `--stream-id`; use `-1` when no task has been published.
`check-lock`	Inspect and manage locks in the metadata store. Requires `-o`; `-ns` sets the namespace, default `default`.

commit-tasks and update-publish-task-offset write coordination state that the compaction service otherwise owns. Use them to recover a stuck stream, with the service's behaviour in mind — see operations.

Tables

bin/ursa admin table <subcommand> [options]

Subcommand	Purpose
`probe`	Probe a table. Takes comma-separated namespaces.
`expire-snapshots`	Expire snapshots of a stream's Iceberg table.
`dedup-files`	Detect and fix duplicate Parquet data-file references in a stream's Iceberg table.

Benchmarks

The producer and consumer measure throughput and latency against a running metadata store, writing an HdrHistogram file if asked and exposing Prometheus metrics on a port.

Producing to ten streams across three threads at 20,000 messages per second, against local-disk storage:

bin/ursa produce -sp data -o localhost:6648 -th 3 -s 10 -r 20000

Consuming the same:

bin/ursa consume -o localhost:6648 -sp data -th 3

Selected producer options:

Option	Default	Purpose
`-o`, `--oxia-url`	required	Metadata store URL.
`-s`, `--num-streams`	`1`	Streams to write to.
`-th`, `--threads`	`1`	Writer threads.
`-r`, `--rate`	`10000`	Messages per second across all streams.
`-size`, `--message-size`	`1024`	Message size in bytes.
`-m`, `--num-messages`	`0`	Total messages; `0` or below writes until stopped.
`-time`, `--test-duration`	`0`	Duration in seconds; `0` or below runs until stopped.
`-w`, `--warmup-time`	`30`	Warm-up seconds before measurement.
`-b`, `--bucket`, `-p`, `--prefix`, `-rg`, `--region`, `-sp`, `--storagePath`	—	Backend location, as in a properties file.
`--histogram-file`	—	HdrHistogram output file.
`-ef`, `--exit-on-failure`	`false`	Exit the process on a publish failure.

Selected consumer options:

Option	Default	Purpose
`-o`, `--oxia-url`	required	Metadata store URL.
`-th`, `--threads`	`1`	Fetch threads.
`-bs`, `--batch-size`	`1000`	Entries per request.
`-bfs`, `--buffer-size`	`1048576`	Buffer size per consumer.
`-s`, `--start-streamId`	`0`	First stream to read.
`-e`, `--end-streamId`	unbounded	Last stream to read.
`-t`, `--time`	`0`	Duration in seconds; `0` or below runs until stopped.

The consumer discovers new streams while running, reads several concurrently, and resumes from the last message it consumed.