Packages
reckon_db
2.3.5
5.11.0
5.10.4
5.10.3
5.10.1
5.10.0
5.9.1
5.9.0
5.8.3
5.8.2
5.8.1
5.8.0
5.7.0
5.6.1
5.6.0
5.5.5
5.5.4
5.5.3
5.5.2
5.5.1
5.5.0
5.4.0
5.2.2
5.2.1
5.2.0
5.1.0
5.0.0
4.0.0
3.1.2
3.1.1
3.0.0
2.3.7
2.3.6
2.3.5
2.3.4
2.3.3
2.3.2
2.3.1
2.3.0
2.2.2
2.2.0
2.1.4
2.1.3
2.1.2
2.1.1
2.1.0
2.0.0
1.7.7
1.7.6
1.7.5
1.7.4
1.7.3
1.7.2
1.7.1
1.7.0
1.6.3
1.6.2
1.6.1
1.6.0
1.5.1
1.5.0
1.4.5
1.4.4
1.4.3
1.4.2
1.4.1
1.4.0
1.3.3
1.3.2
1.3.1
1.3.0
1.2.7
1.2.6
1.2.5
1.2.4
1.2.3
1.2.2
1.2.1
1.2.0
1.1.1
1.1.0
1.0.3
1.0.2
1.0.1
1.0.0
BEAM-native Event Store built on Khepri/Ra with Raft consensus. Event sourcing, persistent subscriptions, snapshots, and automatic cluster formation via UDP multicast discovery. Ships embedded Rust NIFs for 3-15x acceleration of crypto, hashing, compression, aggregation, filter matching, and grap...
Current section
Files
Jump to
Current section
Files
guides/store_inspector.md
# Store Inspector
The Store Inspector provides aggregate introspection for debugging and monitoring ReckonDB stores. It answers questions like:
- How many streams and events does this store have?
- What event types are being used?
- Are subscriptions keeping up or falling behind?
- Which streams have snapshots?
## Usage
All functions take a `StoreId` atom and return `{ok, Data}` or `{error, Reason}`.
### Store Statistics
```erlang
{ok, Stats} = reckon_db_store_inspector:store_stats(my_store).
%% #{store_id => my_store,
%% stream_count => 42,
%% total_events => 1337,
%% snapshot_count => 5,
%% subscription_count => 3,
%% has_events => true}
```
### List All Snapshots
Returns snapshot summaries across all streams, sorted newest first. Data payloads are not included (only metadata).
```erlang
{ok, Snapshots} = reckon_db_store_inspector:list_all_snapshots(my_store).
%% [#{stream_id => <<"user-123">>, version => 50, timestamp => 1710000000000, metadata => #{}},
%% #{stream_id => <<"order-456">>, version => 20, timestamp => 1709000000000, metadata => #{}}]
```
### List Subscriptions
Returns all active subscriptions with their checkpoint positions.
```erlang
{ok, Subs} = reckon_db_store_inspector:list_subscriptions(my_store).
%% [#{subscription_name => <<"prj_users">>,
%% type => event_type,
%% selector => <<"user_registered_v1">>,
%% checkpoint => 42,
%% pool_size => 1,
%% created_at => 1710000000000,
%% subscriber_pid => <<"<0.500.0>">>}]
```
### Subscription Lag
How far behind is a specific subscription?
```erlang
{ok, Lag} = reckon_db_store_inspector:subscription_lag(my_store, <<"prj_users">>).
%% #{subscription_name => <<"prj_users">>,
%% checkpoint => 42,
%% latest_position => 100,
%% lag_events => 57}
```
### Event Type Summary
Census of which event types appear and how many of each. Can be expensive for large stores.
```erlang
{ok, Types} = reckon_db_store_inspector:event_type_summary(my_store).
%% [#{event_type => <<"user_registered_v1">>, count => 500},
%% #{event_type => <<"user_promoted_v1">>, count => 50},
%% #{event_type => <<"user_archived_v1">>, count => 10}]
```
### Stream Info
Detailed information about a single stream, including snapshot coverage.
```erlang
{ok, Info} = reckon_db_store_inspector:stream_info(my_store, <<"user-123">>).
%% #{stream_id => <<"user-123">>,
%% version => 50,
%% event_count => 51,
%% first_event_at => 1700000000000,
%% last_event_at => 1710000000000,
%% snapshots => #{count => 1, latest_version => 50}}
```
## Architecture
The inspector reads directly from the Khepri tree via existing facade modules (`reckon_db_streams`, `reckon_db_snapshots_store`, `reckon_db_subscriptions_store`). It never modifies data.
Gateway worker clauses route inspector requests through the standard `reckon_gater_api` dispatch chain, making these operations available to any client (including the Hecate Observer UI).
## Performance Notes
- `store_stats/1` — O(streams) — fast for typical stores (<1000 streams)
- `list_all_snapshots/1` — O(streams) — iterates all streams checking for snapshots
- `list_subscriptions/1` — O(subscriptions) — typically very fast (<50 subscriptions)
- `subscription_lag/2` — O(streams) — needs total event count
- `event_type_summary/1` — O(total events) — **expensive for large stores**, walks all events
- `stream_info/2` — O(1) — reads single stream metadata + first/last events