observability

sqllocks_spindle.observability

Operational observability — structured JSON logging and per-run metrics.

Provides a structured logging setup and a lightweight metrics collector for Spindle generation runs. All output is JSON-formatted for easy ingestion by log aggregators (Azure Monitor, Datadog, Splunk, etc.).

Usage::

from sqllocks_spindle.observability import configure_logging, RunMetrics

configure_logging(level="INFO")

metrics = RunMetrics(run_id="20240301_120000_retail_small_s42")
metrics.start_table("customer")
# ... generate ...
metrics.end_table("customer", rows=1000, columns=8)
metrics.record_event("chaos_injected", category="value", count=12)
summary = metrics.finish()

Classes

JsonFormatter

Bases: Formatter

Emit log records as single-line JSON objects.

Fields: timestamp, level, logger, message, plus any extra keys passed via the extra parameter of logging calls.

TableMetric dataclass

Timing and size metrics for a single table generation.

RunMetrics dataclass

Collect per-run operational metrics.

Parameters:

Name	Type	Description	Default
run_id	str	The generation run identifier.	required

Methods:

start_table(table_name)

Mark the start of table generation.

end_table(table_name, rows=0, columns=0)

Mark the end of table generation and record metrics.

record_event(event_type, **kwargs)

Record an arbitrary operational event.

finish()

Finalize metrics collection and return a summary dict.

Returns:

Type	Description
dict[str, Any]	A dict suitable for JSON serialization containing:
dict[str, Any]	run_id, total_elapsed_seconds, tables, events.

to_json()

Return the metrics summary as a JSON string.

Functions:

configure_logging(*, level='INFO', stream=None, logger_name='sqllocks_spindle')

Configure structured JSON logging for Spindle.

Parameters:

Name	Type	Description	Default
level	str	Log level string (DEBUG, INFO, WARNING, etc.).	'INFO'
stream	Any	Output stream (defaults to sys.stderr).	None
logger_name	str	Root logger name to configure.	'sqllocks_spindle'

Returns:

Type	Description
Logger	The configured :class:logging.Logger.