ElixirScope.ASTRepository.InstrumentationMapper (elixir_scope v0.0.1)

Maps AST nodes to instrumentation strategies and points.

Provides systematic instrumentation point mapping for compile-time transformation. This module analyzes AST structures and determines the optimal instrumentation strategy for each node type, enabling intelligent compile-time instrumentation.

Key responsibilities:

  • Map AST nodes to appropriate instrumentation strategies
  • Generate instrumentation point configurations
  • Support different instrumentation levels (function, expression, line)
  • Integrate with the Enhanced Parser for systematic instrumentation

Summary

Functions

Configures instrumentation for a specific point.

Estimates the performance impact of an instrumentation configuration.

Maps AST nodes to instrumentation points with appropriate strategies.

Optimizes instrumentation points for performance.

Selects the appropriate instrumentation strategy for a specific AST node.

Types

ast_node()

@type ast_node() :: term()

ast_node_id()

@type ast_node_id() :: binary()

context()

@type context() :: %{
  module_name: atom(),
  function_name: atom() | nil,
  arity: non_neg_integer() | nil,
  instrumentation_level: instrumentation_level(),
  parent_context: context() | nil
}

instrumentation_level()

@type instrumentation_level() :: :minimal | :balanced | :comprehensive | :debug

instrumentation_point()

@type instrumentation_point() :: %{
  ast_node_id: ast_node_id(),
  strategy: instrumentation_strategy(),
  priority: non_neg_integer(),
  metadata: map(),
  configuration: map()
}

instrumentation_strategy()

@type instrumentation_strategy() ::
  :function_boundary
  | :expression_trace
  | :line_execution
  | :variable_capture
  | :none

Functions

configure_instrumentation(instrumentation_point, opts \\ [])

@spec configure_instrumentation(
  instrumentation_point(),
  keyword()
) :: map()

Configures instrumentation for a specific point.

Generates the configuration map that will be used by the AST transformer to inject the appropriate instrumentation code.

estimate_performance_impact(instrumentation_points)

@spec estimate_performance_impact([instrumentation_point()]) :: float()

Estimates the performance impact of an instrumentation configuration.

Returns a performance impact score from 0.0 (no impact) to 1.0 (high impact).

map_instrumentation_points(ast, opts \\ [])

@spec map_instrumentation_points(
  ast_node(),
  keyword()
) :: {:ok, [instrumentation_point()]} | {:error, term()}

Maps AST nodes to instrumentation points with appropriate strategies.

Analyzes the AST structure and generates a comprehensive list of instrumentation points, each with an appropriate strategy based on the node type and context.

Options

  • :instrumentation_level - :minimal, :balanced, :comprehensive, or :debug
  • :include_expressions - Whether to instrument individual expressions
  • :include_variables - Whether to capture variable snapshots
  • :performance_focus - Optimize for performance vs. completeness

optimize_for_performance(instrumentation_points, opts \\ [])

@spec optimize_for_performance(
  [instrumentation_point()],
  keyword()
) :: [instrumentation_point()]

Optimizes instrumentation points for performance.

Reduces the number of instrumentation points while maintaining essential debugging capabilities.

select_instrumentation_strategy(ast_node, context)

@spec select_instrumentation_strategy(ast_node(), context()) ::
  instrumentation_strategy()

Selects the appropriate instrumentation strategy for a specific AST node.

Determines the best instrumentation approach based on the node type, context, and configuration preferences.