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
Functions
Returns a specification to start this module under a supervisor.
See Supervisor
.
@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)
@spec flush_buffer(bridge_ref()) :: :ok | {:error, term()}
Flushes the event buffer to TemporalStorage.
Examples
:ok = TemporalBridge.flush_buffer(bridge)
@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)
@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")
@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")
@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)
@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()
@spec get_stats(bridge_ref()) :: {:ok, map()} | {:error, term()}
Gets bridge statistics and performance metrics.
Examples
{:ok, stats} = TemporalBridge.get_stats(bridge)
@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)
@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)
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)
@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)
@spec unregister_handler() :: :ok
Unregisters this bridge as the temporal correlation handler.
Examples
:ok = TemporalBridge.unregister_handler()