ElixirScope.Capture.TemporalBridge (elixir_scope v0.0.1)

Bridge between InstrumentationRuntime and TemporalStorage for real-time temporal correlation.

This module provides the integration layer that connects runtime event capture with temporal storage and AST correlation, enabling Cinema Debugger functionality.

Features

  • Real-time event correlation with AST nodes
  • Temporal indexing of runtime events
  • Integration with existing InstrumentationRuntime
  • Cinema Debugger query interface
  • Performance-optimized event processing

Architecture

InstrumentationRuntime  TemporalBridge  TemporalStorage
                              
                      AST Node Correlation
                              
                      Cinema Debugger Queries

Usage

# Start the temporal bridge
{:ok, bridge} = TemporalBridge.start_link()

# Events from InstrumentationRuntime are automatically correlated
# and stored in TemporalStorage for Cinema Debugger queries

# Query temporal events
{:ok, events} = TemporalBridge.get_events_in_range(bridge, start_time, end_time)
{:ok, events} = TemporalBridge.get_events_for_ast_node(bridge, "function_def_123")

Summary

Functions

Returns a specification to start this module under a supervisor.

Correlates and stores a runtime event with temporal indexing.

Flushes the event buffer to TemporalStorage.

Gets AST nodes that were active during a time range.

Gets events associated with a specific AST node.

Gets events associated with a specific correlation ID.

Gets events within a time range with AST correlation.

Gets the currently registered temporal bridge.

Gets bridge statistics and performance metrics.

Reconstructs system state at a specific point in time.

Registers this bridge as the temporal correlation handler.

Starts the TemporalBridge process.

Traces execution path leading to a specific event.

Unregisters this bridge as the temporal correlation handler.

Types

ast_node_id()

@type ast_node_id() :: binary()

bridge_ref()

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

correlation_id()

@type correlation_id() :: term()

t()

@type t() :: %ElixirScope.Capture.TemporalBridge{
  bridge_id: term(),
  config: term(),
  correlation_cache: term(),
  event_buffer: term(),
  stats: term(),
  temporal_storage: term()
}

temporal_event()

@type temporal_event() :: map()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

correlate_event(bridge, event)

@spec correlate_event(bridge_ref(), temporal_event()) :: :ok | {:error, term()}

Correlates and stores a runtime event with temporal indexing.

This is called by InstrumentationRuntime to store events with AST correlation and temporal indexing.

Examples

event = %{
  timestamp: Utils.monotonic_timestamp(),
  correlation_id: "exec_123",
  ast_node_id: "function_def_456",
  event_type: :function_entry,
  data: %{module: MyModule, function: :my_function}
}

:ok = TemporalBridge.correlate_event(bridge, event)

flush_buffer(bridge)

@spec flush_buffer(bridge_ref()) :: :ok | {:error, term()}

Flushes the event buffer to TemporalStorage.

Examples

:ok = TemporalBridge.flush_buffer(bridge)

get_active_ast_nodes(bridge, start_time, end_time)

@spec get_active_ast_nodes(bridge_ref(), integer(), integer()) ::
  {:ok, [ast_node_id()]} | {:error, term()}

Gets AST nodes that were active during a time range.

This is a Cinema Debugger primitive that shows which AST nodes had events during a specific time window.

Examples

{:ok, nodes} = TemporalBridge.get_active_ast_nodes(bridge, start_time, end_time)

get_events_for_ast_node(bridge, ast_node_id)

@spec get_events_for_ast_node(bridge_ref(), ast_node_id()) ::
  {:ok, [temporal_event()]} | {:error, term()}

Gets events associated with a specific AST node.

Examples

{:ok, events} = TemporalBridge.get_events_for_ast_node(bridge, "function_def_123")

get_events_for_correlation(bridge, correlation_id)

@spec get_events_for_correlation(bridge_ref(), correlation_id()) ::
  {:ok, [temporal_event()]} | {:error, term()}

Gets events associated with a specific correlation ID.

Examples

{:ok, events} = TemporalBridge.get_events_for_correlation(bridge, "exec_456")

get_events_in_range(bridge, start_time, end_time)

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

Gets events within a time range with AST correlation.

Examples

{:ok, events} = TemporalBridge.get_events_in_range(bridge, start_time, end_time)

get_registered_bridge()

@spec get_registered_bridge() :: {:ok, bridge_ref()} | {:error, :not_registered}

Gets the currently registered temporal bridge.

This is used by InstrumentationRuntime to send events to the bridge.

Examples

{:ok, bridge} = TemporalBridge.get_registered_bridge()

get_stats(bridge)

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

Gets bridge statistics and performance metrics.

Examples

{:ok, stats} = TemporalBridge.get_stats(bridge)

reconstruct_state_at(bridge, timestamp)

@spec reconstruct_state_at(bridge_ref(), integer()) :: {:ok, map()} | {:error, term()}

Reconstructs system state at a specific point in time.

This is a Cinema Debugger primitive that analyzes all events up to a specific timestamp to reconstruct system state.

Examples

{:ok, state} = TemporalBridge.reconstruct_state_at(bridge, timestamp)

register_as_handler(bridge)

@spec register_as_handler(bridge_ref()) :: :ok | {:error, term()}

Registers this bridge as the temporal correlation handler.

This integrates the bridge with InstrumentationRuntime so that events are automatically correlated and stored.

Examples

:ok = TemporalBridge.register_as_handler(bridge)

start_link(opts \\ [])

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

Starts the TemporalBridge process.

Options

  • :name - Process name (optional)
  • :temporal_storage - Existing TemporalStorage process (optional)
  • :buffer_size - Event buffer size (default: 1000)
  • :flush_interval - Buffer flush interval in ms (default: 100)

Examples

{:ok, bridge} = TemporalBridge.start_link()
{:ok, bridge} = TemporalBridge.start_link(name: :main_bridge)

trace_execution_path(bridge, target_event)

@spec trace_execution_path(bridge_ref(), temporal_event()) ::
  {:ok, [temporal_event()]} | {:error, term()}

Traces execution path leading to a specific event.

This is a Cinema Debugger primitive that reconstructs the execution sequence that led to a particular event.

Examples

{:ok, path} = TemporalBridge.trace_execution_path(bridge, target_event)

unregister_handler()

@spec unregister_handler() :: :ok

Unregisters this bridge as the temporal correlation handler.

Examples

:ok = TemporalBridge.unregister_handler()