Documentation Index
Fetch the complete documentation index at: https://mintlify.com/nubskr/walrus/llms.txt
Use this file to discover all available pages before exploring further.
The STATE command returns detailed metadata about a topic, including its segments, leaders, entry counts, and cursor position.
Syntax
The name of the topic to inspect. Must be a single word (no spaces).
[4 bytes: length] STATE <topic>
[4 bytes: length] OK <json_payload>
OK followed by a space and the JSON payload (not just the JSON).
Error Response:
[4 bytes: length] ERR <error message>
{
"topic": "logs",
"segments": [
{
"segment_id": 0,
"leader_node": 1,
"sealed": false,
"entry_count": 42
},
{
"segment_id": 1,
"leader_node": 2,
"sealed": true,
"entry_count": 1000050
}
],
"cursor_position": 15,
"total_entries": 1000092
}
Response Fields
List of all segments for this topicZero-based segment identifier
Node ID that owns this segment (handles writes if active, reads if sealed)
Whether the segment is sealed (read-only) or active (accepting writes)
Number of entries in this segment
Current shared cursor position (next entry to be read by GET)
Total number of entries across all segments
Examples
Interactive Shell
🦭 > REGISTER logs
OK
🦭 > STATE logs
{
"topic": "logs",
"segments": [
{
"segment_id": 0,
"leader_node": 1,
"sealed": false,
"entry_count": 0
}
],
"cursor_position": 0,
"total_entries": 0
}
🦭 > PUT logs "hello"
OK
🦭 > STATE logs
{
"topic": "logs",
"segments": [
{
"segment_id": 0,
"leader_node": 1,
"sealed": false,
"entry_count": 1
}
],
"cursor_position": 0,
"total_entries": 1
}
🦭 > GET logs
OK hello
🦭 > STATE logs
{
"topic": "logs",
"segments": [
{
"segment_id": 0,
"leader_node": 1,
"sealed": false,
"entry_count": 1
}
],
"cursor_position": 1,
"total_entries": 1
}
One-off Command
# Get topic state
cargo run --bin walrus-cli -- state logs
# Pretty-print JSON with jq
cargo run --bin walrus-cli -- state logs | jq .
# Extract specific fields
cargo run --bin walrus-cli -- state logs | jq '.total_entries'
cargo run --bin walrus-cli -- state logs | jq '.segments[].leader_node'
Programmatic Usage (Rust)
use distributed_walrus::cli_client::CliClient;
use serde_json::Value;
#[tokio::main]
async fn main() -> Result<()> {
let client = CliClient::new("127.0.0.1:9091");
// Get state as JSON string
let state_json = client.state("logs").await?;
// Parse JSON
let state: Value = serde_json::from_str(&state_json)?;
println!("Total entries: {}", state["total_entries"]);
println!("Cursor position: {}", state["cursor_position"]);
Ok(())
}
Use Cases
Monitor Topic Growth
# Watch topic size grow
watch -n 1 'cargo run --bin walrus-cli -- state logs | jq .total_entries'
Check Segment Distribution
# List all segments and their leaders
cargo run --bin walrus-cli -- state logs | jq '.segments[] | "Segment \(.segment_id): Node \(.leader_node) (\(.entry_count) entries)"'
Verify Rollover
# Check if rollover has occurred (multiple segments)
cargo run --bin walrus-cli -- state logs | jq '.segments | length'
Track Consumer Progress
# Calculate lag (unread entries)
cargo run --bin walrus-cli -- state logs | jq '.total_entries - .cursor_position'
Error Cases
Missing Topic Name
Request:
Response:
ERR STATE requires a topic
Topic Does Not Exist
Request:
Response:
Understanding Segments
Active Segment
The newest segment with sealed: false:
- Accepts new PUT operations
- Has a designated leader node
- Entry count grows as data is written
- Becomes sealed when it reaches ~1M entries
Sealed Segments
Older segments with sealed: true:
- Read-only (no more writes)
- Entry count is fixed
- Original leader retains the data for reads
- Can be read from any replica with the data
Leadership Rotation
Each segment has a different leader:
{
"segments": [
{"segment_id": 0, "leader_node": 1, "sealed": true},
{"segment_id": 1, "leader_node": 2, "sealed": true},
{"segment_id": 2, "leader_node": 3, "sealed": false}
]
}
Replicated State
- Topic metadata is replicated via Raft across all nodes
- Any node can answer STATE queries
- Consistent view of segments and leaders
- Updates happen through Raft consensus
Eventually Consistent
- Slight delays during metadata updates (100ms sync loop)
- Entry counts may be stale by a few entries
- Cursor position reflects local view
- REGISTER - Create a topic to inspect
- PUT - Append data to increase entry count
- GET - Advance cursor position
- METRICS - View cluster-wide Raft metrics
