intellicrack.core.logging

Structured logging infrastructure for Intellicrack.

This module provides comprehensive structured logging using structlog, with JSON file output for log aggregation and colored console output for development. Includes automatic cleanup of old log files on startup.

class ColoredConsoleRenderer[source]

Bases: object

Custom structlog renderer for colored console output.

Provides human-readable colored output to the console with ANSI color codes based on log level.

Variables:

  • LEVEL_COLORS (ClassVar[dict[str, str]]) – Mapping of log level names to ANSI color codes.

  • RESET (ClassVar[str]) – ANSI reset code.

LEVEL_COLORS: ClassVar[dict[str, str]] = {'critical': '\x1b[35m', 'debug': '\x1b[36m', 'error': '\x1b[31m', 'info': '\x1b[32m', 'warning': '\x1b[33m'}
RESET: ClassVar[str] = '\x1b[0m'
__call__(_logger, _name, event_dict)[source]

Render log event with colors.

Parameters:

  • _logger (WrappedLogger) – The wrapped logger instance (unused, required by interface).

  • _name (str) – The name of the wrapped logger method (unused, required by interface).

  • event_dict (EventDict) – The event dictionary to render.

Returns:

Formatted colored log message string.

Return type:

str

cleanup_old_logs(log_dir, retention_days)[source]

Delete log files older than retention_days on startup.

Parameters:

  • log_dir (Path) – Directory containing log files.

  • retention_days (int) – Number of days to retain log files.

Returns:

Number of files deleted.

Return type:

int

class IntellicrackLogger[source]

Bases: object

Application logger with structlog integration.

This class manages the logging configuration for the entire application, providing structured logging with both file-based JSON output and colorized console output.

Variables:

name (str) – The name for this logger instance.

__init__(name='intellicrack')[source]

Initialize the IntellicrackLogger with a logger name.

Parameters:

name (str) – The name for this logger instance.

Return type:

None

name: str
static configure(level='INFO', log_dir=None, *, file_enabled=True, console_enabled=True, max_file_size_mb=10, backup_count=5, retention_days=14, json_file=True, filename='intellicrack.log')[source]

Configure the logger with structlog handlers.

Parameters:

  • level (str) – Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).

  • log_dir (Path | None) – Directory for log files.

  • file_enabled (bool) – Whether to enable file logging.

  • console_enabled (bool) – Whether to enable console logging.

  • max_file_size_mb (int) – Maximum log file size in megabytes.

  • backup_count (int) – Number of backup files to keep.

  • retention_days (int) – Number of days to retain log files.

  • json_file (bool) – Whether to output JSON to file.

  • filename (str) – Name of the rotated log file written into log_dir. Defaults to intellicrack.log; auxiliary processes (e.g. the docker-sandbox driver) override this so they don’t collide with the application’s log file.

Return type:

None

get_logger(name=None)[source]

Get a structlog BoundLogger instance.

Parameters:

name (str | None) – Optional child logger name. If None, returns the root logger.

Returns:

Configured BoundLogger instance for structured logging.

Return type:

structlog.stdlib.BoundLogger

setup_logging(config, log_dir=None)[source]

Set up application logging from configuration.

Records the resolved log directory in the global _logger_state so later calls to _default_log_dir() honour the user-configured location.

Parameters:

  • config (LogConfig) – LogConfig instance with logging settings.

  • log_dir (Path | None) – Optional directory for log files. When None, _default_log_dir() resolves the configured Config.logs_directory if available; otherwise falls back to Path.cwd() / "logs". Callers that have a loaded Config instance should pass config.logs_directory here.

Returns:

Configured IntellicrackLogger instance.

Return type:

IntellicrackLogger

get_logger(name=None)[source]

Get a structlog BoundLogger instance for a module.

Parameters:

name (str | None) – Module name for the logger. If None, returns root app logger.

Returns:

Configured BoundLogger instance for structured logging.

Return type:

structlog.stdlib.BoundLogger

get_stdlib_root_logger()[source]

Return the stdlib logging root logger for handler installation.

Centralises the single legitimate use of logging.getLogger() with no argument: callers that need to add or remove a logging.Handler on the root logger (for example, the Qt log viewer’s signaling handler) must operate on the stdlib Logger instance directly because structlog BoundLogger does not expose handler-management APIs.

Returns:

The stdlib root logger that owns every installed handler in the process.

Return type:

Logger

log_tool_call(tool_name, function_name, arguments, duration_ms=None, *, success=None)[source]

Log a tool call for debugging and auditing.

Parameters:

  • tool_name (str) – Name of the tool being called.

  • function_name (str) – Name of the function being invoked.

  • arguments (dict[str, object]) – Dictionary of function arguments.

  • duration_ms (float | None) – Optional execution duration in milliseconds.

  • success (bool | None) – Optional success indicator.

Return type:

None

log_provider_request(provider, model, messages_count, tools_count, temperature=None)[source]

Log an LLM provider request.

Parameters:

  • provider (str) – Name of the LLM provider.

  • model (str) – Model ID being used.

  • messages_count (int) – Number of messages in the request.

  • tools_count (int) – Number of tools available.

  • temperature (float | None) – Sampling temperature requested by the caller, if any. Recorded so operators can see the requested value even when a provider does not forward it to its backend (for example Anthropic, whose current models reject the parameter).

Return type:

None

log_provider_response(provider, model, tool_calls_count, duration_ms, tokens_used=None)[source]

Log an LLM provider response.

Parameters:

  • provider (str) – Name of the LLM provider.

  • model (str) – Model ID that responded.

  • tool_calls_count (int) – Number of tool calls in the response.

  • duration_ms (float) – Response time in milliseconds.

  • tokens_used (int | None) – Optional number of tokens used.

Return type:

None

log_binary_operation(operation, path, **kwargs)[source]

Log a binary analysis operation.

Parameters:

  • operation (str) – Type of operation (load, patch, save, etc.).

  • path (str | Path) – Path to the binary file.

  • **kwargs (object) – Additional operation-specific context.

Return type:

None

log_sandbox_operation(operation, sandbox_type, **kwargs)[source]

Log a sandbox operation.

Parameters:

  • operation (str) – Type of operation (start, stop, execute, etc.).

  • sandbox_type (str) – Type of sandbox (windows, qemu, etc.).

  • **kwargs (object) – Additional operation-specific context.

Return type:

None

log_session_operation(operation, session_id=None, **kwargs)[source]

Log a session operation.

Parameters:

  • operation (str) – Type of operation (create, load, save, etc.).

  • session_id (str | None) – Optional session identifier.

  • **kwargs (object) – Additional operation-specific context.

Return type:

None

log_analysis_operation(operation, target, **kwargs)[source]

Log a license analysis operation.

Parameters:

  • operation (str) – Type of analysis operation.

  • target (str) – Target being analyzed.

  • **kwargs (object) – Additional analysis-specific context.

Return type:

None

class OperationTimer[source]

Bases: object

Context manager for timing operations and logging duration.

Variables:

  • operation (str) – The operation name.

  • logger_name (str) – The logger name to use.

  • context (dict[str, object]) – Additional context for the log.

__init__(operation, logger_name='operations', **context)[source]

Initialize the OperationTimer with an operation name and context.

Parameters:

  • operation (str) – The operation name.

  • logger_name (str) – The logger name to use.

  • **context (object) – Additional context for the log.

Return type:

None

operation: str
logger_name: str
context: dict[str, object]
property elapsed_ms: float

The elapsed time in milliseconds since the timer started.

Returns:

Elapsed time in milliseconds, or 0.0 if the timer has not started.

Return type:

float

__enter__()[source]

Start the timer and log operation start.

Returns:

Self for context manager use.

Return type:

Self

__exit__(exc_type, exc_val, exc_tb)[source]

Stop the timer and log operation completion.

Parameters:

  • exc_type (type[BaseException] | None) – Exception type if an exception occurred.

  • exc_val (BaseException | None) – Exception value if an exception occurred.

  • exc_tb (TracebackType | None) – Exception traceback if an exception occurred.

Return type:

None