@spec configure_from_options(
  Statifier.StateChart.t(),
  keyword()
) :: Statifier.StateChart.t()

Configure logging for a StateChart from initialization options.

This function is called by Interpreter.initialize/2 to set up logging based on provided options, application configuration, or environment defaults.

Options

• :log_adapter - Logging adapter configuration. Can be:

  • Atom shorthand: :elixir, :internal, :test, or :silent
  • An adapter struct (e.g., %TestAdapter{max_entries: 100})
  • A tuple {AdapterModule, opts} (e.g., {TestAdapter, [max_entries: 50]})
  • If not provided, uses environment-specific defaults

• :log_level - Minimum log level (:trace, :debug, :info, :warning, :error)

  • Defaults to :debug in test environment, :info otherwise

Adapter Shortcuts

• :elixir - Uses ElixirLoggerAdapter (integrates with Elixir's Logger)
• :internal - Uses TestAdapter for internal debugging
• :test - Uses TestAdapter (alias for test environments)
• :silent - Uses TestAdapter with no log storage (disables logging)

Examples

# Simple atom configuration for debugging
state_chart = LogManager.configure_from_options(state_chart, [
  log_adapter: :elixir,
  log_level: :trace
])

# Traditional module+options configuration
state_chart = LogManager.configure_from_options(state_chart, [
  log_adapter: {TestAdapter, [max_entries: 100]},
  log_level: :debug
])

# Use with application configuration set
state_chart = LogManager.configure_from_options(state_chart, [])

Logs a debug message with automatic metadata extraction.

Debug level is for information useful for debugging. This is a macro that only evaluates the message and metadata arguments if debug logging is enabled, providing optimal performance.

Examples

# Arguments are only evaluated if debug logging is enabled
state_chart = LogManager.debug(state_chart, "Processing step", %{
  current_data: expensive_calculation()  # Only called if debug enabled
})

@spec enabled?(Statifier.StateChart.t(), atom()) :: boolean()

Checks if a log level is enabled for the given StateChart.

A level is enabled if:

1. It meets the StateChart's minimum log level
2. The adapter reports it as enabled

Parameters

• state_chart - Current StateChart instance
• level - Log level to check

Returns

true if logging at this level will produce output, false otherwise

Logs an error message with automatic metadata extraction.

Error level is for error conditions that don't halt execution. This is a macro that only evaluates the message and metadata arguments if error logging is enabled, providing optimal performance.

Examples

# Arguments are only evaluated if error logging is enabled
state_chart = LogManager.error(state_chart, "Processing failed", %{
  error_context: build_error_context()  # Only called if error enabled
})

Logs an info message with automatic metadata extraction.

Info level is for general informational messages. This is a macro that only evaluates the message and metadata arguments if info logging is enabled, providing optimal performance.

Examples

# Arguments are only evaluated if info logging is enabled
state_chart = LogManager.info(state_chart, "Operation complete", %{
  result_summary: summarize_results()  # Only called if info enabled
})

@spec log(Statifier.StateChart.t(), atom(), String.t(), map()) ::
  Statifier.StateChart.t()

Logs a message at the specified level with automatic metadata extraction.

Extracts core metadata from the StateChart and merges it with any additional metadata provided. Only logs if the level is enabled.

Parameters

• state_chart - Current StateChart instance
• level - Log level atom
• message - Log message string
• additional_metadata - Optional additional metadata map

Returns

Updated StateChart (may be unchanged if adapter doesn't modify it)

Logs a trace message with automatic metadata extraction.

Trace level is for very detailed diagnostic information. This is a macro that only evaluates the message and metadata arguments if trace logging is enabled, providing optimal performance.

Examples

# Arguments are only evaluated if trace logging is enabled
state_chart = LogManager.trace(state_chart, "Complex operation", %{
  expensive_data: build_debug_info()  # Only called if trace enabled
})

Logs a warning message with automatic metadata extraction.

Warning level is for potentially problematic situations. This is a macro that only evaluates the message and metadata arguments if warn logging is enabled, providing optimal performance.

Examples

# Arguments are only evaluated if warn logging is enabled
state_chart = LogManager.warn(state_chart, "Unexpected condition", %{
  diagnostic_info: gather_diagnostics()  # Only called if warn enabled
})