ElixirScope.Capture.TemporalStorage (elixir_scope v0.0.1)

Temporal storage for events with AST correlation and time-based indexing.

Provides efficient storage and querying of events with temporal ordering and AST node correlation for Cinema Debugger functionality.

Features

  • Time-ordered event storage
  • AST node correlation tracking
  • Efficient time-range queries
  • Memory-efficient indexing

Usage

{:ok, storage} = TemporalStorage.start_link()

event = %{
  timestamp: 1000,
  ast_node_id: "node1", 
  correlation_id: "corr1",
  data: %{...}
}

:ok = TemporalStorage.store_event(storage, event)

{:ok, events} = TemporalStorage.get_events_in_range(storage, 1000, 2000)

Summary

Functions

Returns a specification to start this module under a supervisor.

Gets all events in chronological order.

Gets events associated with a specific AST node.

Gets events associated with a specific correlation ID.

Retrieves events within a time range, ordered chronologically.

Gets storage statistics.

Starts a new TemporalStorage process.

Stores an event with temporal indexing.

Types

event()

@type event() :: %{
  timestamp: integer(),
  ast_node_id: binary() | nil,
  correlation_id: binary() | nil,
  data: term()
}

storage_ref()

@type storage_ref() :: pid() | atom()

t()

@type t() :: %ElixirScope.Capture.TemporalStorage{
  ast_index: term(),
  config: term(),
  correlation_index: term(),
  events_table: term(),
  stats: term(),
  storage_id: term()
}

time_range()

@type time_range() :: {integer(), integer()}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_all_events(storage)

@spec get_all_events(storage_ref()) :: {:ok, [event()]} | {:error, term()}

Gets all events in chronological order.

Examples

{:ok, all_events} = TemporalStorage.get_all_events(storage)

get_events_for_ast_node(storage, ast_node_id)

@spec get_events_for_ast_node(storage_ref(), binary()) ::
  {:ok, [event()]} | {:error, term()}

Gets events associated with a specific AST node.

Examples

{:ok, events} = TemporalStorage.get_events_for_ast_node(storage, "function_def_123")

get_events_for_correlation(storage, correlation_id)

@spec get_events_for_correlation(storage_ref(), binary()) ::
  {:ok, [event()]} | {:error, term()}

Gets events associated with a specific correlation ID.

Examples

{:ok, events} = TemporalStorage.get_events_for_correlation(storage, "exec_456")

get_events_in_range(storage, start_time, end_time)

@spec get_events_in_range(storage_ref(), integer(), integer()) ::
  {:ok, [event()]} | {:error, term()}

Retrieves events within a time range, ordered chronologically.

Examples

# Get events from last 5 seconds
now = Utils.monotonic_timestamp()
{:ok, events} = TemporalStorage.get_events_in_range(storage, now - 5000, now)

# Get all events in a specific window
{:ok, events} = TemporalStorage.get_events_in_range(storage, 1000, 2000)

get_stats(storage)

@spec get_stats(storage_ref()) :: {:ok, map()} | {:error, term()}

Gets storage statistics.

Examples

{:ok, stats} = TemporalStorage.get_stats(storage)
# %{
#   total_events: 1234,
#   memory_usage: 5678,
#   oldest_event: 1000,
#   newest_event: 2000
# }

start_link(opts \\ [])

@spec start_link(keyword()) :: {:ok, pid()} | {:error, term()}

Starts a new TemporalStorage process.

Options

  • :name - Process name (optional)
  • :max_events - Maximum events to store (default: 100,000)
  • :cleanup_interval - Cleanup interval in ms (default: 60,000)

Examples

{:ok, storage} = TemporalStorage.start_link()
{:ok, storage} = TemporalStorage.start_link(name: :my_storage)

store_event(storage, event)

@spec store_event(storage_ref(), event()) :: :ok | {:error, term()}

Stores an event with temporal indexing.

Events are automatically indexed by timestamp and optionally by AST node ID and correlation ID for efficient querying.

Examples

event = %{
  timestamp: Utils.monotonic_timestamp(),
  ast_node_id: "function_def_123",
  correlation_id: "exec_456",
  data: %{function: :my_function, args: [1, 2, 3]}
}

:ok = TemporalStorage.store_event(storage, event)