Logger

This section documents the logging classes that provide structured logging capabilities.

MatrixOneLogger

class matrixone.logger.MatrixOneLogger(logger: Logger | None = None, level: int = 20, format_string: str | None = None, sql_log_mode: str = 'auto', slow_query_threshold: float = 1.0, max_sql_display_length: int = 500)

Bases: object

MatrixOne Logger class that provides structured logging for the SDK

Features: - Default logger configuration - Custom logger integration - Performance logging - Error tracking - Structured log messages

__init__(logger: Logger | None = None, level: int = 20, format_string: str | None = None, sql_log_mode: str = 'auto', slow_query_threshold: float = 1.0, max_sql_display_length: int = 500)

Initialize MatrixOne logger

Args:

logger: Custom logger instance. If None, creates a default logger
level: Logging level (default: INFO)
format_string: Custom format string for log messages
sql_log_mode: SQL logging mode ('off', 'auto', 'simple', 'full')
    - 'off': No SQL logging
    - 'auto': Smart logging - short SQL shown fully, long SQL summarized (default)
    - 'simple': Show operation summary only (e.g., "INSERT INTO table (5 rows)")
    - 'full': Show complete SQL regardless of length
slow_query_threshold: Threshold in seconds for slow query warnings (default: 1.0)
max_sql_display_length: Maximum SQL length in auto mode before summarizing (default: 500)

debug(message: str, **kwargs)

Log debug message

info(message: str, **kwargs)

Log info message

warning(message: str, **kwargs)

Log warning message

error(message: str, **kwargs)

Log error message

critical(message: str, **kwargs)

Log critical message

log_connection(host: str, port: int, user: str, database: str, success: bool = True)

Log connection events

log_disconnection(success: bool = True)

Log disconnection events

log_error(error: Exception, context: str | None = None, include_traceback: bool = False)

Log errors with context and optional traceback.

Parameters:

• error – The exception object

• context – Optional context description (e.g., “Query execution”, “Table creation”)

• include_traceback – If True, include full traceback in log

update_config(sql_log_mode: str | None = None, slow_query_threshold: float | None = None, max_sql_display_length: int | None = None)

Dynamically update logger configuration at runtime.

Args:

sql_log_mode: New SQL logging mode ('off', 'auto', 'simple', 'full')
slow_query_threshold: New threshold in seconds for slow query warnings
max_sql_display_length: New maximum SQL length in auto mode before summarizing

Example:

# Enable full SQL logging for debugging
client.logger.update_config(sql_log_mode='full')

# Update multiple settings
client.logger.update_config(
    sql_log_mode='auto',
    slow_query_threshold=2.0,
    max_sql_display_length=1000
)

log_query(query: str, execution_time: float | None = None, affected_rows: int | None = None, success: bool = True, log_mode: str | None = None)

Log SQL query execution with smart formatting.

Args:

query: SQL query string
execution_time: Query execution time in seconds
affected_rows: Number of rows affected
success: Whether the query succeeded
log_mode: Temporarily override sql_log_mode for this query only

set_level(level: int)

Set logging level

add_handler(handler: Handler)

Add custom handler to logger

remove_handler(handler: Handler)

Remove handler from logger

is_custom() → bool

Check if using custom logger

Logger Functions

matrixone.logger.create_default_logger(level: int = 20, format_string: str | None = None, sql_log_mode: str = 'auto', slow_query_threshold: float = 1.0, max_sql_display_length: int = 500) → MatrixOneLogger

Create a default MatrixOne logger

Args:

level: Logging level
format_string: Custom format string
sql_log_mode: SQL logging mode ('off', 'auto', 'simple', 'full')
slow_query_threshold: Threshold in seconds for slow query warnings
max_sql_display_length: Maximum SQL length in auto mode before summarizing

Returns:

MatrixOneLogger instance