sqlspec 0.36.0__cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

sqlspec/observability/_formatters/_aws.py

@@ -0,0 +1,102 @@
+"""Amazon Web Services log formatter."""
+
+from datetime import datetime, timezone
+from typing import Any, ClassVar
+
+__all__ = ("AWSLogFormatter",)
+
+
+class 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
+
+    Example:
+        ```python
+        formatter = AWSLogFormatter()
+        entry = formatter.format(
+            "INFO",
+            "Query executed",
+            correlation_id="abc-123",
+            trace_id="1-5f84c7a1-sample",
+            duration_ms=15.5,
+        )
+        ```
+
+    Reference:
+        https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html
+    """
+
+    __slots__ = ()
+
+    LEVEL_MAP: ClassVar[dict[str, str]] = {
+        "DEBUG": "DEBUG",
+        "INFO": "INFO",
+        "WARNING": "WARN",
+        "ERROR": "ERROR",
+        "CRITICAL": "FATAL",
+    }
+
+    def format(
+        self,
+        level: str,
+        message: str,
+        *,
+        correlation_id: str | None = None,
+        trace_id: str | None = None,
+        span_id: str | None = None,
+        duration_ms: float | None = None,
+        extra: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Format log entry for AWS CloudWatch.
+
+        Args:
+            level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+            message: Log message.
+            correlation_id: Request correlation ID (maps to requestId).
+            trace_id: X-Ray trace ID.
+            span_id: X-Ray segment ID.
+            duration_ms: Operation duration in milliseconds.
+            extra: Additional fields to include in the log entry.
+
+        Returns:
+            Dictionary formatted for AWS CloudWatch structured logging.
+        """
+        entry: dict[str, Any] = {
+            "level": self.LEVEL_MAP.get(level.upper(), "INFO"),
+            "message": message,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+
+        if correlation_id:
+            entry["requestId"] = correlation_id
+
+        if trace_id:
+            entry["xray_trace_id"] = trace_id
+
+        if span_id:
+            entry["xray_segment_id"] = span_id
+
+        if duration_ms is not None:
+            entry["duration_ms"] = duration_ms
+
+        if extra:
+            entry.update(extra)
+
+        return entry
+
+    def __hash__(self) -> int:
+        return hash(self.__class__.__name__)
+
+    def __repr__(self) -> str:
+        return "AWSLogFormatter()"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, AWSLogFormatter):
+            return NotImplemented
+        return True

sqlspec/observability/_formatters/_azure.py

@@ -0,0 +1,96 @@
+"""Microsoft Azure log formatter."""
+
+from typing import Any, ClassVar
+
+__all__ = ("AzureLogFormatter",)
+
+
+class 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
+
+    Example:
+        ```python
+        formatter = AzureLogFormatter()
+        entry = formatter.format(
+            "INFO",
+            "Query executed",
+            correlation_id="abc-123",
+            trace_id="4bf92f3577b34da6a3ce929d0e0e4736",
+            duration_ms=15.5,
+        )
+        ```
+
+    Reference:
+        https://docs.microsoft.com/en-us/azure/azure-monitor/app/data-model
+    """
+
+    __slots__ = ()
+
+    SEVERITY_MAP: ClassVar[dict[str, int]] = {"DEBUG": 0, "INFO": 1, "WARNING": 2, "ERROR": 3, "CRITICAL": 4}
+
+    def format(
+        self,
+        level: str,
+        message: str,
+        *,
+        correlation_id: str | None = None,
+        trace_id: str | None = None,
+        span_id: str | None = None,
+        duration_ms: float | None = None,
+        extra: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Format log entry for Azure Monitor.
+
+        Args:
+            level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+            message: Log message.
+            correlation_id: Request correlation ID.
+            trace_id: Operation ID for distributed tracing.
+            span_id: Parent operation ID.
+            duration_ms: Operation duration in milliseconds.
+            extra: Additional fields to include in properties.
+
+        Returns:
+            Dictionary formatted for Azure Monitor structured logging.
+        """
+        entry: dict[str, Any] = {"message": message, "severityLevel": self.SEVERITY_MAP.get(level.upper(), 1)}
+
+        if trace_id:
+            entry["operation_Id"] = trace_id
+
+        if span_id:
+            entry["operation_ParentId"] = span_id
+
+        properties: dict[str, Any] = {}
+
+        if correlation_id:
+            properties["correlationId"] = correlation_id
+
+        if duration_ms is not None:
+            properties["durationMs"] = duration_ms
+
+        if extra:
+            properties.update(extra)
+
+        if properties:
+            entry["properties"] = properties
+
+        return entry
+
+    def __hash__(self) -> int:
+        return hash(self.__class__.__name__)
+
+    def __repr__(self) -> str:
+        return "AzureLogFormatter()"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, AzureLogFormatter):
+            return NotImplemented
+        return True

sqlspec/observability/_formatters/_base.py

@@ -0,0 +1,57 @@
+"""Base protocol for cloud log formatters."""
+
+from typing import Any, Protocol
+
+__all__ = ("CloudLogFormatter",)
+
+
+class CloudLogFormatter(Protocol):
+    """Protocol for cloud-specific log formatting.
+
+    Implementations format log entries according to cloud provider
+    structured logging requirements (GCP, AWS, Azure).
+
+    Example:
+        ```python
+        class GCPLogFormatter:
+            def format(
+                self,
+                level: str,
+                message: str,
+                *,
+                correlation_id: str | None = None,
+                trace_id: str | None = None,
+                span_id: str | None = None,
+                duration_ms: float | None = None,
+                extra: dict[str, Any] | None = None,
+            ) -> dict[str, Any]:
+                return {"severity": level, "message": message, ...}
+        ```
+    """
+
+    def format(
+        self,
+        level: str,
+        message: str,
+        *,
+        correlation_id: str | None = None,
+        trace_id: str | None = None,
+        span_id: str | None = None,
+        duration_ms: float | None = None,
+        extra: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Format log entry for cloud provider.
+
+        Args:
+            level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+            message: Log message.
+            correlation_id: Request correlation ID.
+            trace_id: Distributed trace ID.
+            span_id: Span ID within the trace.
+            duration_ms: Operation duration in milliseconds.
+            extra: Additional fields to include in the log entry.
+
+        Returns:
+            Dictionary formatted for the cloud provider's structured logging.
+        """
+        ...

sqlspec/observability/_formatters/_gcp.py

@@ -0,0 +1,131 @@
+"""Google Cloud Platform log formatter."""
+
+import os
+from typing import Any, ClassVar
+
+__all__ = ("GCPLogFormatter",)
+
+
+class 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
+
+    Example:
+        ```python
+        formatter = GCPLogFormatter(project_id="my-project")
+        entry = formatter.format(
+            "INFO",
+            "Query executed",
+            correlation_id="abc-123",
+            trace_id="4bf92f3577b34da6a3ce929d0e0e4736",
+            duration_ms=15.5,
+        )
+        ```
+
+    Reference:
+        https://cloud.google.com/logging/docs/structured-logging
+    """
+
+    __slots__ = ("_project_id",)
+
+    SEVERITY_MAP: ClassVar[dict[str, str]] = {
+        "DEBUG": "DEBUG",
+        "INFO": "INFO",
+        "WARNING": "WARNING",
+        "ERROR": "ERROR",
+        "CRITICAL": "CRITICAL",
+    }
+
+    def __init__(self, project_id: str | None = None) -> None:
+        """Initialize GCP log formatter.
+
+        Args:
+            project_id: GCP project ID for trace URL construction.
+                If not provided, attempts to read from GOOGLE_CLOUD_PROJECT
+                environment variable.
+        """
+        self._project_id = project_id or os.environ.get("GOOGLE_CLOUD_PROJECT")
+
+    @property
+    def project_id(self) -> str | None:
+        """Get the configured GCP project ID."""
+        return self._project_id
+
+    def format(
+        self,
+        level: str,
+        message: str,
+        *,
+        correlation_id: str | None = None,
+        trace_id: str | None = None,
+        span_id: str | None = None,
+        duration_ms: float | None = None,
+        source_file: str | None = None,
+        source_line: int | None = None,
+        source_function: str | None = None,
+        extra: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Format log entry for Google Cloud Logging.
+
+        Args:
+            level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+            message: Log message.
+            correlation_id: Request correlation ID.
+            trace_id: Distributed trace ID.
+            span_id: Span ID within the trace.
+            duration_ms: Operation duration in milliseconds.
+            source_file: Source file path.
+            source_line: Source line number.
+            source_function: Source function name.
+            extra: Additional fields to include in the log entry.
+
+        Returns:
+            Dictionary formatted for GCP structured logging.
+        """
+        entry: dict[str, Any] = {"severity": self.SEVERITY_MAP.get(level.upper(), "DEFAULT"), "message": message}
+
+        if trace_id and self._project_id:
+            entry["logging.googleapis.com/trace"] = f"projects/{self._project_id}/traces/{trace_id}"
+
+        if span_id:
+            entry["logging.googleapis.com/spanId"] = span_id
+
+        if correlation_id:
+            entry.setdefault("logging.googleapis.com/labels", {})
+            entry["logging.googleapis.com/labels"]["correlation_id"] = correlation_id
+
+        if source_file or source_line is not None or source_function:
+            source_location: dict[str, str] = {}
+            if source_file:
+                source_location["file"] = source_file
+            if source_line is not None:
+                source_location["line"] = str(source_line)
+            if source_function:
+                source_location["function"] = source_function
+            entry["logging.googleapis.com/sourceLocation"] = source_location
+
+        if duration_ms is not None:
+            entry["duration_ms"] = duration_ms
+
+        if extra:
+            entry.update(extra)
+
+        return entry
+
+    def __hash__(self) -> int:
+        return hash((self.__class__.__name__, self._project_id))
+
+    def __repr__(self) -> str:
+        return f"GCPLogFormatter(project_id={self._project_id!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, GCPLogFormatter):
+            return NotImplemented
+        return self._project_id == other._project_id

sqlspec/observability/_formatting.py

@@ -0,0 +1,58 @@
+"""Formatters for standardized SQLSpec observability logs."""
+
+import logging
+from logging import LogRecord
+from typing import Any
+
+from sqlspec.utils.logging import StructuredFormatter
+
+__all__ = ("OTelConsoleFormatter", "OTelJSONFormatter")
+
+
+class OTelConsoleFormatter(logging.Formatter):
+    """Console formatter that orders OTel-aligned fields consistently."""
+
+    def __init__(self, datefmt: str | None = None) -> None:
+        super().__init__(datefmt=datefmt)
+        self._field_order = (
+            "db.system",
+            "db.operation",
+            "trace_id",
+            "span_id",
+            "correlation_id",
+            "duration_ms",
+            "rows_affected",
+            "execution_mode",
+            "is_many",
+            "is_script",
+            "sqlspec.driver",
+            "sqlspec.bind_key",
+            "sqlspec.transaction_state",
+            "sqlspec.prepared_statement",
+            "db.statement",
+            "db.statement.truncated",
+            "db.statement.length",
+            "db.statement.preview_length",
+            "db.statement.hash",
+        )
+
+    def format(self, record: LogRecord) -> str:
+        timestamp = self.formatTime(record, self.datefmt)
+        parts = [timestamp, f"[{record.levelname}]", record.getMessage()]
+        record_dict = record.__dict__
+        parts.extend(
+            self._format_field(key, record_dict[key])
+            for key in self._field_order
+            if key in record_dict and record_dict[key] is not None
+        )
+        return " ".join(parts)
+
+    @staticmethod
+    def _format_field(key: str, value: Any) -> str:
+        if isinstance(value, bool):
+            return f"{key}={str(value).lower()}"
+        return f"{key}={value}"
+
+
+class OTelJSONFormatter(StructuredFormatter):
+    """Structured JSON formatter for OTel-aligned log fields."""