reckon_db_causation (reckon_db v1.6.0)

Causation and correlation tracking for reckon-db

Provides functionality to trace event lineage: - Causation ID: Links an event to its direct cause - Correlation ID: Groups related events in a business process/saga - Actor ID: Identifies who/what triggered the event

Standard metadata fields (convention):

  #{
      causation_id => binary(),     %% ID of event/command that caused this
      correlation_id => binary(),   %% Business process/saga ID
      actor_id => binary()          %% Who/what triggered this
  }

Use cases: - Debugging distributed event flows - Audit trails - Saga/process manager state reconstruction - Dependency analysis

Summary

Types

causation_graph/0

event/0

Functions

build_graph(StoreId, Id)

Build a causation graph for visualization.

get_cause(StoreId, EventId)

Get the event that caused the given event.

get_chain(StoreId, EventId)

Get the full causation chain from root to the given event.

get_correlated(StoreId, CorrelationId)

Get all events sharing the same correlation ID.

get_effects(StoreId, EventId)

Get all events caused by the given event.

to_dot(_)

Export a causation graph as DOT format for Graphviz.

Types

causation_graph/0

-type causation_graph() ::
          #{nodes := [event()], edges := [{binary(), binary()}], root := binary() | undefined}.

event/0

-type event() ::
          #event{event_id :: binary(),
                 event_type :: binary(),
                 stream_id :: binary(),
                 version :: non_neg_integer(),
                 data :: map() | binary(),
                 metadata :: map(),
                 tags :: [binary()] | undefined,
                 timestamp :: integer(),
                 epoch_us :: integer(),
                 data_content_type :: binary(),
                 metadata_content_type :: binary()}.

Functions

build_graph(StoreId, Id)

-spec build_graph(atom(), binary()) -> {ok, causation_graph()} | {error, term()}.

Build a causation graph for visualization.

Accepts either an event_id (builds graph from that event) or a correlation_id (builds graph from all correlated events). Returns nodes and edges suitable for graph rendering.

get_cause(StoreId, EventId)

-spec get_cause(atom(), binary()) -> {ok, event()} | {error, not_found | term()}.

Get the event that caused the given event.

Finds the event whose event_id matches this event's causation_id.

get_chain(StoreId, EventId)

-spec get_chain(atom(), binary()) -> {ok, [event()]} | {error, term()}.

Get the full causation chain from root to the given event.

Walks backward through causation_id links until reaching an event with no cause. Returns events in order from root to target.

get_correlated(StoreId, CorrelationId)

-spec get_correlated(atom(), binary()) -> {ok, [event()]} | {error, term()}.

Get all events sharing the same correlation ID.

Useful for finding all events in a saga or business process.

get_effects(StoreId, EventId)

-spec get_effects(atom(), binary()) -> {ok, [event()]} | {error, term()}.

Get all events caused by the given event.

Returns events whose causation_id matches the given event_id.

to_dot(_)

-spec to_dot(causation_graph()) -> binary().

Export a causation graph as DOT format for Graphviz.

Usage: dot -Tpng -o graph.png with the output.