Statifier.Logging.LogManager (statifier v1.5.0)

View Source

Central logging manager for the Statifier logging system.

LogManager provides a unified interface for logging throughout Statifier, with automatic metadata extraction from StateChart instances. It handles log level filtering and delegates to the configured logging adapter.

Automatic Metadata Extraction

LogManager automatically extracts core metadata from the StateChart:

  • current_state: List of currently active leaf states
  • event: Name of the current event being processed (if any)

Additional context-specific metadata can be provided by callers.

Log Levels

Supports standard log levels in order of increasing severity:

  • :trace - Very detailed information
  • :debug - Debugging information
  • :info - General information
  • :warn - Warning messages
  • :error - Error messages

Examples

# Basic logging with automatic metadata
state_chart = LogManager.info(state_chart, "Processing started")

# Logging with additional metadata
state_chart = LogManager.debug(state_chart, "Evaluating condition", %{
  action_type: "transition",
  condition: "x > 5"
})

# Check if level is enabled before expensive operations
if LogManager.enabled?(state_chart, :debug) do
  expensive_debug_info = build_complex_debug_data()
  state_chart = LogManager.debug(state_chart, expensive_debug_info)
end

Summary

Functions

configure_from_options(state_chart, opts)

Configure logging for a StateChart from initialization options.

debug(state_chart, message, metadata \\ %{})

Logs a debug message with automatic metadata extraction.

enabled?(state_chart, level)

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

error(state_chart, message, metadata \\ %{})

Logs an error message with automatic metadata extraction.

info(state_chart, message, metadata \\ %{})

Logs an info message with automatic metadata extraction.

log(state_chart, level, message, additional_metadata \\ %{})

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

trace(state_chart, message, metadata \\ %{})

Logs a trace message with automatic metadata extraction.

warn(state_chart, message, metadata \\ %{})

Logs a warning message with automatic metadata extraction.

Functions

configure_from_options(state_chart, opts)

@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:

    • 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, :warn, :error)

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

Examples

# Use with runtime options
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, [])

debug(state_chart, message, metadata \\ %{})

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

Logs a debug message with automatic metadata extraction.

Debug level is for information useful for debugging.

enabled?(state_chart, level)

@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

error(state_chart, message, metadata \\ %{})

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

Logs an error message with automatic metadata extraction.

Error level is for error conditions that don't halt execution.

info(state_chart, message, metadata \\ %{})

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

Logs an info message with automatic metadata extraction.

Info level is for general informational messages.

log(state_chart, level, message, additional_metadata \\ %{})

@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)

trace(state_chart, message, metadata \\ %{})

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

Logs a trace message with automatic metadata extraction.

Trace level is for very detailed diagnostic information.

warn(state_chart, message, metadata \\ %{})

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

Logs a warning message with automatic metadata extraction.

Warning level is for potentially problematic situations.