ElixirScope.Capture.InstrumentationRuntime (elixir_scope v0.0.1)
Runtime API for instrumented code to report events to ElixirScope.
This module provides the interface that AST-transformed code will call. It must be extremely fast and have graceful degradation when ElixirScope is disabled or not available.
Key design principles:
- Minimal overhead when disabled (single boolean check)
- No crashes if ElixirScope is not running
- Efficient correlation ID management
- Support for nested function calls
Summary
Functions
Clears the instrumentation context for the current process.
Gets the current correlation ID (for nested calls).
Checks if instrumentation is enabled for the current process.
Gets AST correlation metadata for the current context.
Initializes the instrumentation context for the current process.
Measures the overhead of instrumentation calls.
Reports AST conditional branch execution with node correlation.
Reports AST correlation performance metrics.
Reports AST expression evaluation with node correlation.
Reports AST function entry with source tagging.
Reports AST function entry with enhanced correlation metadata.
Reports AST function exit with source tagging. Enhanced to support AST node correlation for hybrid architecture.
Reports AST function exit with enhanced correlation metadata.
Reports AST line execution with node correlation.
Reports AST loop iteration with node correlation.
Reports AST pattern match with node correlation.
Reports a local variable snapshot with AST node correlation.
Reports Ecto query completion.
Reports Ecto query start.
Reports an error event.
Reports an expression value (AST-specific).
Reports a function call entry.
Reports function entry (4-arity version).
Reports a function call exit.
Reports function exit (5-arity version).
Reports GenServer callback completion.
Reports GenServer callback error.
Reports GenServer callback start.
Reports GenServer callback success.
Reports line execution (AST-specific).
Reports LiveView assigns.
Reports LiveView callback.
Reports LiveView callback error.
Reports LiveView callback success.
Reports LiveView event.
Reports LiveView handle_event completion.
Reports LiveView handle_event start.
Reports LiveView mount completion.
Reports LiveView mount start.
Reports a local variable snapshot (AST-specific).
Reports a message send event.
Reports node events.
Reports partition detection.
Reports Phoenix action completion.
Reports Phoenix action error.
Reports Phoenix action parameters.
Reports Phoenix action start.
Reports Phoenix action success.
Reports Phoenix channel join completion.
Reports Phoenix channel join start.
Reports Phoenix channel message completion.
Reports Phoenix channel message start.
Reports Phoenix controller entry.
Reports Phoenix controller exit.
Reports Phoenix request completion.
Reports Phoenix request start.
Reports a process spawn event.
Reports a state change event (for GenServer, Agent, etc.).
Validates AST node ID format for correlation.
Temporarily disables instrumentation for the current process.
Types
@type correlation_id() :: term()
@type instrumentation_context() :: %{ buffer: ElixirScope.Capture.RingBuffer.t() | nil, correlation_id: correlation_id(), call_stack: [correlation_id()], enabled: boolean() }
Functions
@spec clear_context() :: :ok
Clears the instrumentation context for the current process.
@spec current_correlation_id() :: correlation_id() | nil
Gets the current correlation ID (for nested calls).
@spec enabled?() :: boolean()
Checks if instrumentation is enabled for the current process.
This is the fastest possible check - just a process dictionary lookup.
@spec get_ast_correlation_metadata() :: map()
Gets AST correlation metadata for the current context.
Returns metadata that can be used to correlate runtime events with AST nodes. Used internally by AST correlation functions.
@spec initialize_context() :: :ok
Initializes the instrumentation context for the current process.
This should be called when a process starts or when ElixirScope is enabled.
@spec measure_overhead(pos_integer()) :: %{ entry_avg_ns: float(), exit_avg_ns: float(), disabled_avg_ns: float() }
Measures the overhead of instrumentation calls.
Returns timing statistics for performance validation.
report_ast_branch_execution(correlation_id, branch_type, condition, branch_taken, line, ast_node_id)
@spec report_ast_branch_execution( correlation_id(), atom(), term(), boolean(), non_neg_integer(), String.t() ) :: :ok
Reports AST conditional branch execution with node correlation.
Used to track which branches of conditionals (if/case/cond) are taken. Provides insights into code path execution patterns.
@spec report_ast_correlation_performance( correlation_id(), String.t(), non_neg_integer() ) :: :ok
Reports AST correlation performance metrics.
Used to track the performance impact of AST correlation features. Helps ensure <5ms correlation latency target is met.
@spec report_ast_expression_value( correlation_id(), String.t(), term(), non_neg_integer(), String.t() ) :: :ok
Reports AST expression evaluation with node correlation.
This version includes AST node ID for direct correlation with the AST Repository. Used to track specific expression evaluations in the hybrid architecture.
@spec report_ast_function_entry(module(), atom(), list(), correlation_id()) :: :ok
Reports AST function entry with source tagging.
This is similar to report_function_entry but specifically for AST-injected calls. Enhanced to support AST node correlation for hybrid architecture.
@spec report_ast_function_entry_with_node_id( module(), atom(), list(), correlation_id(), String.t() ) :: :ok
Reports AST function entry with enhanced correlation metadata.
This version includes AST node ID for direct correlation with the AST Repository. Used by the enhanced AST transformer for hybrid architecture support.
@spec report_ast_function_exit(correlation_id(), term(), non_neg_integer()) :: :ok
Reports AST function exit with source tagging. Enhanced to support AST node correlation for hybrid architecture.
@spec report_ast_function_exit_with_node_id( correlation_id(), term(), non_neg_integer(), String.t() ) :: :ok
Reports AST function exit with enhanced correlation metadata.
This version includes AST node ID for direct correlation with the AST Repository. Used by the enhanced AST transformer for hybrid architecture support.
@spec report_ast_line_execution( correlation_id(), non_neg_integer(), map(), String.t() ) :: :ok
Reports AST line execution with node correlation.
This version includes AST node ID for direct correlation with the AST Repository. Used to track specific line executions in the hybrid architecture.
report_ast_loop_iteration(correlation_id, loop_type, iteration_count, current_value, line, ast_node_id)
@spec report_ast_loop_iteration( correlation_id(), atom(), non_neg_integer(), term(), non_neg_integer(), String.t() ) :: :ok
Reports AST loop iteration with node correlation.
Used to track loop iterations (Enum.map, for comprehensions, etc.). Provides insights into iteration patterns and performance.
@spec report_ast_pattern_match( correlation_id(), term(), term(), boolean(), non_neg_integer(), String.t() ) :: :ok
Reports AST pattern match with node correlation.
Used to track pattern matching operations in the hybrid architecture. Provides insights into pattern match success/failure and variable bindings.
@spec report_ast_variable_snapshot( correlation_id(), map(), non_neg_integer(), String.t() ) :: :ok
Reports a local variable snapshot with AST node correlation.
This version includes AST node ID for direct correlation with the AST Repository. Used by the enhanced AST transformer for hybrid architecture support.
@spec report_ecto_query_complete( correlation_id(), String.t(), list(), term(), non_neg_integer() ) :: :ok
Reports Ecto query completion.
@spec report_ecto_query_start(correlation_id(), String.t(), list(), map(), atom()) :: :ok
Reports Ecto query start.
Reports an error event.
@spec report_expression_value( correlation_id(), String.t(), term(), non_neg_integer(), atom() ) :: :ok
Reports an expression value (AST-specific).
This is called by AST-injected code to capture the value of specific expressions during execution. Enhanced to support AST node correlation for hybrid architecture.
@spec report_function_entry(module(), atom(), list()) :: correlation_id() | nil
Reports a function call entry.
This is called at the beginning of every instrumented function. Must be extremely fast - target <100ns when disabled, <500ns when enabled.
@spec report_function_entry(atom(), integer(), boolean(), term()) :: correlation_id() | nil
Reports function entry (4-arity version).
@spec report_function_exit(correlation_id(), term(), non_neg_integer()) :: :ok
Reports a function call exit.
This is called at the end of every instrumented function.
Reports function exit (5-arity version).
Reports GenServer callback completion.
Reports GenServer callback error.
Reports GenServer callback start.
Reports GenServer callback success.
@spec report_line_execution(correlation_id(), non_neg_integer(), map(), atom()) :: :ok
Reports line execution (AST-specific).
This is called by AST-injected code to mark execution of specific lines. Enhanced to support AST node correlation for hybrid architecture.
Reports LiveView assigns.
Reports LiveView callback.
Reports LiveView callback error.
Reports LiveView callback success.
Reports LiveView event.
@spec report_liveview_handle_event_complete( correlation_id(), String.t(), map(), map(), term() ) :: :ok
Reports LiveView handle_event completion.
@spec report_liveview_handle_event_start(correlation_id(), String.t(), map(), map()) :: :ok
Reports LiveView handle_event start.
@spec report_liveview_mount_complete(correlation_id(), module(), map()) :: :ok
Reports LiveView mount completion.
@spec report_liveview_mount_start(correlation_id(), module(), map(), map()) :: :ok
Reports LiveView mount start.
@spec report_local_variable_snapshot( correlation_id(), map(), non_neg_integer(), atom() ) :: :ok
Reports a local variable snapshot (AST-specific).
This is called by AST-injected code to capture local variable values at specific points in function execution. Enhanced to support AST node correlation for hybrid architecture.
Reports a message send event.
Reports node events.
Reports partition detection.
Reports Phoenix action completion.
Reports Phoenix action error.
Reports Phoenix action parameters.
Reports Phoenix action start.
Reports Phoenix action success.
@spec report_phoenix_channel_join_complete( correlation_id(), String.t(), map(), term() ) :: :ok
Reports Phoenix channel join completion.
@spec report_phoenix_channel_join_start(correlation_id(), String.t(), map(), map()) :: :ok
Reports Phoenix channel join start.
@spec report_phoenix_channel_message_complete( correlation_id(), String.t(), map(), term() ) :: :ok
Reports Phoenix channel message completion.
@spec report_phoenix_channel_message_start(correlation_id(), String.t(), map(), map()) :: :ok
Reports Phoenix channel message start.
@spec report_phoenix_controller_entry(correlation_id(), module(), atom(), map()) :: :ok
Reports Phoenix controller entry.
@spec report_phoenix_controller_exit(correlation_id(), module(), atom(), term()) :: :ok
Reports Phoenix controller exit.
@spec report_phoenix_request_complete( correlation_id(), integer(), String.t(), non_neg_integer() ) :: :ok
Reports Phoenix request completion.
@spec report_phoenix_request_start( correlation_id(), String.t(), String.t(), map(), tuple() ) :: :ok
Reports Phoenix request start.
@spec report_process_spawn(pid()) :: :ok
Reports a process spawn event.
Reports a state change event (for GenServer, Agent, etc.).
Validates AST node ID format for correlation.
Ensures AST node IDs follow the expected format for the hybrid architecture. Returns {:ok, node_id} or {:error, reason}.
Temporarily disables instrumentation for the current process.
Useful for avoiding recursive instrumentation in ElixirScope's own code.