Observability¶

from sqlspec.observability import (
    AWSLogFormatter,
    AzureLogFormatter,
    CloudLogFormatter,
    GCPLogFormatter,
    LifecycleContext,
    LifecycleDispatcher,
    LoggingConfig,
    ObservabilityConfig,
    ObservabilityRuntime,
    OTelConsoleFormatter,
    OTelJSONFormatter,
    RedactionConfig,
    SamplingConfig,
    SpanManager,
    StatementEvent,
    TelemetryConfig,
    TelemetryDiagnostics,
    create_statement_observer,
    default_statement_observer,
    format_statement_event,
)

Structured statement observers, parameter redaction, OpenTelemetry span management, lifecycle hooks, and cloud-native log formatters (GCP, AWS, Azure, OTel). See Observability for setup guides.

Configuration & Runtime¶

ObservabilityConfig ¶

Aggregates lifecycle hooks, observers, and telemetry toggles.

copy ¶

copy()

Return a deep copy of the configuration.

merge ¶

merge(base_config, override_config)

Merge registry-level and adapter-level configuration objects.

TelemetryConfig ¶

Span emission and tracer provider settings.

LoggingConfig ¶

Controls log output format and verbosity.

RedactionConfig ¶

Controls SQL and parameter redaction before observers run.

SamplingConfig ¶

Configuration for log and metric sampling.

Controls when observability data (logs, spans, metrics) is emitted. Supports both random and deterministic sampling modes, with force-sample conditions for errors and slow queries.

Attributes:

Name	Type	Description
`sample_rate`		Probability of sampling (0.0 to 1.0). 1.0 means always sample.
`force_sample_on_error`		If True, always sample when an error occurs.
`force_sample_slow_queries_ms`	`float \| None`	If set, always sample queries slower than this threshold.
`deterministic`		If True, use hash-based sampling for consistency across distributed systems.

ObservabilityRuntime ¶

Aggregates dispatchers, observers, spans, and custom metrics.

emit_statement_event ¶

emit_statement_event(
    *,
    sql,
    parameters,
    driver,
    operation,
    execution_mode,
    is_many,
    is_script,
    rows_affected,
    duration_s,
    storage_backend,
    started_at=None,
    precomputed_sql_hash=None,
    transaction_state=None,
    prepared_statement=None,
    is_error=False,
    profile=None,
    script_ordinal=None,
    script_statement_index=None,
    script_statement_count=None,
)

Emit a statement event to all registered observers.

start_span ¶

start_span(name, *, attributes=None)

Start a custom span enriched with configuration context.

increment_metric ¶

increment_metric(name, amount=1.0)

Increment a custom metric counter.

Statement Events & Observers¶

StatementEvent ¶

Structured payload describing a SQL execution.

create_event ¶

create_event(
    *,
    sql,
    parameters,
    driver,
    adapter,
    bind_key,
    operation,
    execution_mode,
    is_many,
    is_script,
    rows_affected,
    duration_s,
    correlation_id,
    storage_backend=None,
    started_at=None,
    db_system=None,
    sql_hash=None,
    sql_truncated=False,
    sql_original_length=None,
    transaction_state=None,
    prepared_statement=None,
    trace_id=None,
    span_id=None,
    sampled=True,
    profile=None,
    script_ordinal=None,
    script_statement_index=None,
    script_statement_count=None,
)

Factory helper for runtime statement events.

create_statement_observer ¶

create_statement_observer(logging_config, cloud_formatter=None)

Create a statement observer bound to the provided logging config.

default_statement_observer ¶

default_statement_observer(event)

Log statement execution payload when no custom observer is supplied.

format_statement_event ¶

format_statement_event(event)

Create a concise human-readable representation of a statement event.

Spans, Lifecycle & Diagnostics¶

SpanManager ¶

Lazy OpenTelemetry span manager with graceful degradation.

LifecycleDispatcher ¶

Dispatches lifecycle hooks with guard flags and diagnostics counters.

LifecycleContext ¶

LifecycleContext = dict[str, Any]

TelemetryDiagnostics ¶

Aggregates lifecycle counters, custom metrics, and storage telemetry.

Cloud & OpenTelemetry Log Formatters¶

CloudLogFormatter ¶

Bases: Protocol

Protocol for cloud-specific log formatting.

Implementations format log entries according to cloud provider structured logging requirements (GCP, AWS, Azure).

GCPLogFormatter ¶

Formatter for Google Cloud Logging structured format.

Produces JSON-compatible dictionaries that conform to GCP's structured logging format, including: - severity field with GCP severity levels - logging.googleapis.com/trace for trace correlation - logging.googleapis.com/spanId for span tracking - logging.googleapis.com/labels for custom labels - logging.googleapis.com/sourceLocation for code location

Reference

https://cloud.google.com/logging/docs/structured-logging

AWSLogFormatter ¶

Formatter for AWS CloudWatch Logs structured format.

Produces JSON-compatible dictionaries that conform to AWS CloudWatch structured logging conventions, including: - level field with AWS log level conventions - requestId for correlation ID - xray_trace_id for X-Ray integration - ISO 8601 timestamp

Reference

https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html

AzureLogFormatter ¶

Formatter for Azure Monitor / Application Insights structured format.

Produces JSON-compatible dictionaries that conform to Azure Monitor structured logging conventions, including: - severityLevel with numeric severity (0-4) - operation_Id for trace correlation - operation_ParentId for span tracking - properties dict for custom fields

Reference

https://docs.microsoft.com/en-us/azure/azure-monitor/app/data-model

OTelJSONFormatter ¶

Bases: StructuredFormatter

Structured JSON formatter for OTel-aligned log fields.

OTelConsoleFormatter ¶

Bases: Formatter

Console formatter that orders OTel-aligned fields consistently.