asap-protocol 0.1.0__py3-none-any.whl

asap/observability/__init__.py

@@ -0,0 +1,43 @@
+"""Observability module for ASAP protocol.
+
+This module provides structured logging, metrics, and observability utilities
+for the ASAP protocol transport layer.
+
+Features:
+- Structured logging with JSON output for production
+- Console output with colors for development
+- Automatic trace_id and correlation_id propagation
+- Logger factory with common context binding
+- Prometheus-compatible metrics collection
+
+Example:
+    >>> from asap.observability import get_logger, get_metrics
+    >>>
+    >>> logger = get_logger(__name__)
+    >>> logger.info("asap.request.received", envelope_id="env_123", payload_type="task.request")
+    >>>
+    >>> metrics = get_metrics()
+    >>> metrics.increment_counter("asap_requests_total", {"payload_type": "task.request"})
+"""
+
+from asap.observability.logging import (
+    bind_context,
+    clear_context,
+    configure_logging,
+    get_logger,
+)
+from asap.observability.metrics import (
+    MetricsCollector,
+    get_metrics,
+    reset_metrics,
+)
+
+__all__ = [
+    "bind_context",
+    "clear_context",
+    "configure_logging",
+    "get_logger",
+    "get_metrics",
+    "reset_metrics",
+    "MetricsCollector",
+]

asap/observability/logging.py

@@ -0,0 +1,216 @@
+"""Structured logging configuration for ASAP protocol.
+
+This module configures structlog for structured logging with support for
+both development (console) and production (JSON) output formats.
+
+The logging configuration includes:
+- JSON renderer for production environments
+- Console renderer with colors for development
+- Automatic timestamp and log level injection
+- Context binding for trace_id, correlation_id, etc.
+
+Environment Variables:
+    ASAP_LOG_FORMAT: Set to "json" for JSON output, "console" for colored output
+    ASAP_LOG_LEVEL: Set log level (DEBUG, INFO, WARNING, ERROR)
+    ASAP_SERVICE_NAME: Service name to include in logs
+
+Example:
+    >>> from asap.observability.logging import get_logger, configure_logging
+    >>>
+    >>> # Configure logging (typically done once at startup)
+    >>> configure_logging(log_format="json", log_level="INFO")
+    >>>
+    >>> # Get a logger and use it
+    >>> logger = get_logger("asap.transport.server")
+    >>> logger.info("request.received", envelope_id="env_123")
+"""
+
+import logging
+import os
+import sys
+from typing import Any
+
+import structlog
+from structlog.typing import Processor
+
+# Default configuration
+DEFAULT_LOG_LEVEL = "INFO"
+DEFAULT_LOG_FORMAT = "console"
+DEFAULT_SERVICE_NAME = "asap-protocol"
+
+# Environment variable names
+ENV_LOG_FORMAT = "ASAP_LOG_FORMAT"
+ENV_LOG_LEVEL = "ASAP_LOG_LEVEL"
+ENV_SERVICE_NAME = "ASAP_SERVICE_NAME"
+
+# Module-level flag to track if logging has been configured
+_logging_configured = False
+
+
+def _get_log_level() -> str:
+    """Get log level from environment or use default."""
+    return os.environ.get(ENV_LOG_LEVEL, DEFAULT_LOG_LEVEL).upper()
+
+
+def _get_log_format() -> str:
+    """Get log format from environment or use default."""
+    return os.environ.get(ENV_LOG_FORMAT, DEFAULT_LOG_FORMAT).lower()
+
+
+def _get_service_name() -> str:
+    """Get service name from environment or use default."""
+    return os.environ.get(ENV_SERVICE_NAME, DEFAULT_SERVICE_NAME)
+
+
+def _get_shared_processors() -> list[Processor]:
+    """Get shared processors for all log formats."""
+    return [
+        structlog.contextvars.merge_contextvars,
+        structlog.stdlib.add_log_level,
+        structlog.stdlib.add_logger_name,
+        structlog.stdlib.PositionalArgumentsFormatter(),
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.UnicodeDecoder(),
+    ]
+
+
+def _get_console_renderer() -> Processor:
+    """Get console renderer for development."""
+    return structlog.dev.ConsoleRenderer(
+        colors=True,
+        exception_formatter=structlog.dev.plain_traceback,
+    )
+
+
+def _get_json_renderer() -> Processor:
+    """Get JSON renderer for production."""
+    return structlog.processors.JSONRenderer()
+
+
+def configure_logging(
+    log_format: str | None = None,
+    log_level: str | None = None,
+    service_name: str | None = None,
+    force: bool = False,
+) -> None:
+    """Configure structured logging for the application.
+
+    This function sets up structlog with the appropriate processors and
+    renderers based on the specified format.
+
+    Args:
+        log_format: Output format - "json" or "console". Defaults to env var or "console"
+        log_level: Minimum log level. Defaults to env var or "INFO"
+        service_name: Service name for log context. Defaults to env var or "asap-protocol"
+        force: If True, reconfigure even if already configured
+
+    Example:
+        >>> # Configure for production
+        >>> configure_logging(log_format="json", log_level="INFO")
+        >>>
+        >>> # Configure for development
+        >>> configure_logging(log_format="console", log_level="DEBUG")
+    """
+    global _logging_configured
+
+    if _logging_configured and not force:
+        return
+
+    # Get configuration values
+    log_format = log_format or _get_log_format()
+    log_level = log_level or _get_log_level()
+    service_name = service_name or _get_service_name()
+
+    # Get shared processors
+    shared_processors = _get_shared_processors()
+
+    # Add format-specific renderer
+    if log_format == "json":
+        renderer: Processor = _get_json_renderer()
+    else:
+        renderer = _get_console_renderer()
+
+    # Configure structlog
+    structlog.configure(
+        processors=[
+            *shared_processors,
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        wrapper_class=structlog.stdlib.BoundLogger,
+        cache_logger_on_first_use=True,
+    )
+
+    # Configure standard logging
+    formatter = structlog.stdlib.ProcessorFormatter(
+        foreign_pre_chain=shared_processors,
+        processors=[
+            structlog.stdlib.ProcessorFormatter.remove_processors_meta,
+            renderer,
+        ],
+    )
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(formatter)
+
+    root_logger = logging.getLogger()
+    root_logger.handlers.clear()
+    root_logger.addHandler(handler)
+    root_logger.setLevel(getattr(logging, log_level))
+
+    # Set service name in context
+    structlog.contextvars.bind_contextvars(service=service_name)
+
+    _logging_configured = True
+
+
+def get_logger(name: str) -> structlog.stdlib.BoundLogger:
+    """Get a structured logger for the given name.
+
+    Creates a bound logger with the given name. If logging has not been
+    configured, it will be configured with default settings.
+
+    Args:
+        name: Logger name (typically __name__ of the module)
+
+    Returns:
+        Bound structlog logger
+
+    Example:
+        >>> logger = get_logger(__name__)
+        >>> logger.info("event.happened", key="value")
+        >>>
+        >>> # With bound context
+        >>> logger = logger.bind(trace_id="trace_123")
+        >>> logger.info("request.processed")  # trace_id automatically included
+    """
+    # Ensure logging is configured
+    if not _logging_configured:
+        configure_logging()
+
+    return structlog.stdlib.get_logger(name)
+
+
+def bind_context(**kwargs: Any) -> None:
+    """Bind context variables that will be included in all subsequent logs.
+
+    This is useful for setting trace_id, correlation_id, or other context
+    that should be included in all logs within the current context.
+
+    Args:
+        **kwargs: Key-value pairs to bind to the log context
+
+    Example:
+        >>> bind_context(trace_id="trace_123", user_id="user_456")
+        >>> logger.info("event")  # Will include trace_id and user_id
+    """
+    structlog.contextvars.bind_contextvars(**kwargs)
+
+
+def clear_context() -> None:
+    """Clear all bound context variables.
+
+    Useful for cleaning up context at the end of a request.
+    """
+    structlog.contextvars.clear_contextvars()

asap/observability/metrics.py

@@ -0,0 +1,399 @@
+"""ASAP Protocol Metrics Collection.
+
+This module provides Prometheus-compatible metrics collection for ASAP servers.
+Metrics are collected during request processing and exposed via the /asap/metrics endpoint.
+
+Supported metric types:
+- Counter: Monotonically increasing values (e.g., total requests)
+- Histogram: Distribution of values with configurable buckets (e.g., latency)
+
+Example:
+    >>> from asap.observability.metrics import MetricsCollector, get_metrics
+    >>> collector = MetricsCollector()
+    >>> collector.increment_counter("asap_requests_total", {"payload_type": "task.request"})
+    >>> collector.observe_histogram("asap_request_duration_seconds", 0.125, {"status": "success"})
+    >>> print(collector.export_prometheus())
+"""
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+
+@dataclass
+class Counter:
+    """A monotonically increasing counter metric.
+
+    Attributes:
+        name: Metric name
+        help_text: Human-readable description
+        values: Dictionary mapping label combinations to counts
+    """
+
+    name: str
+    help_text: str
+    values: dict[tuple[tuple[str, str], ...], float] = field(default_factory=dict)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def increment(self, labels: dict[str, str] | None = None, value: float = 1.0) -> None:
+        """Increment the counter by value.
+
+        Args:
+            labels: Optional label key-value pairs
+            value: Amount to increment (default: 1.0)
+        """
+        label_key = tuple(sorted((labels or {}).items()))
+        with self._lock:
+            self.values[label_key] = self.values.get(label_key, 0.0) + value
+
+    def get(self, labels: dict[str, str] | None = None) -> float:
+        """Get current counter value for labels.
+
+        Args:
+            labels: Optional label key-value pairs
+
+        Returns:
+            Current counter value
+        """
+        label_key = tuple(sorted((labels or {}).items()))
+        with self._lock:
+            return self.values.get(label_key, 0.0)
+
+
+# Default histogram buckets for latency (in seconds)
+DEFAULT_LATENCY_BUCKETS = (0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0)
+
+
+@dataclass
+class Histogram:
+    """A histogram metric for measuring distributions.
+
+    Attributes:
+        name: Metric name
+        help_text: Human-readable description
+        buckets: Upper bounds for histogram buckets
+        values: Dictionary mapping label combinations to bucket counts and sum
+    """
+
+    name: str
+    help_text: str
+    buckets: tuple[float, ...] = DEFAULT_LATENCY_BUCKETS
+    # values[label_key] = {"buckets": {bound: count}, "sum": total, "count": n}
+    values: dict[tuple[tuple[str, str], ...], dict[str, float | dict[float, float]]] = field(
+        default_factory=dict
+    )
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def observe(self, value: float, labels: dict[str, str] | None = None) -> None:
+        """Record an observation in the histogram.
+
+        Args:
+            value: The observed value
+            labels: Optional label key-value pairs
+        """
+        label_key = tuple(sorted((labels or {}).items()))
+        with self._lock:
+            if label_key not in self.values:
+                self.values[label_key] = {
+                    "buckets": dict.fromkeys(self.buckets, 0.0),
+                    "sum": 0.0,
+                    "count": 0.0,
+                }
+
+            data = self.values[label_key]
+            buckets = data["buckets"]
+            if isinstance(buckets, dict):
+                for bound in self.buckets:
+                    if value <= bound:
+                        buckets[bound] += 1.0
+
+            if isinstance(data["sum"], float):
+                data["sum"] += value
+            if isinstance(data["count"], float):
+                data["count"] += 1.0
+
+    def get_count(self, labels: dict[str, str] | None = None) -> float:
+        """Get total observation count for labels.
+
+        Args:
+            labels: Optional label key-value pairs
+
+        Returns:
+            Total observation count
+        """
+        label_key = tuple(sorted((labels or {}).items()))
+        with self._lock:
+            if label_key not in self.values:
+                return 0.0
+            count = self.values[label_key].get("count", 0.0)
+            return count if isinstance(count, float) else 0.0
+
+
+class MetricsCollector:
+    """Collects and exports metrics in Prometheus format.
+
+    This class provides thread-safe metric collection with support for
+    counters and histograms. Metrics are exported in Prometheus text format.
+
+    Example:
+        >>> collector = MetricsCollector()
+        >>> collector.increment_counter(
+        ...     "asap_requests_total",
+        ...     {"payload_type": "task.request", "status": "success"}
+        ... )
+        >>> collector.observe_histogram(
+        ...     "asap_request_duration_seconds",
+        ...     0.125,
+        ...     {"payload_type": "task.request"}
+        ... )
+        >>> print(collector.export_prometheus())
+    """
+
+    # Default metric definitions
+    DEFAULT_COUNTERS: ClassVar[dict[str, str]] = {
+        "asap_requests_total": "Total number of ASAP requests received",
+        "asap_requests_success_total": "Total number of successful ASAP requests",
+        "asap_requests_error_total": "Total number of failed ASAP requests",
+    }
+
+    DEFAULT_HISTOGRAMS: ClassVar[dict[str, str]] = {
+        "asap_request_duration_seconds": "Request processing duration in seconds",
+    }
+
+    def __init__(self) -> None:
+        """Initialize the metrics collector with default metrics."""
+        self._lock = threading.Lock()
+        self._counters: dict[str, Counter] = {}
+        self._histograms: dict[str, Histogram] = {}
+        self._start_time = time.time()
+
+        # Initialize default metrics
+        for name, help_text in self.DEFAULT_COUNTERS.items():
+            self._counters[name] = Counter(name=name, help_text=help_text)
+
+        for name, help_text in self.DEFAULT_HISTOGRAMS.items():
+            self._histograms[name] = Histogram(name=name, help_text=help_text)
+
+    def register_counter(self, name: str, help_text: str) -> None:
+        """Register a new counter metric.
+
+        Args:
+            name: Metric name (should follow Prometheus naming conventions)
+            help_text: Human-readable description
+        """
+        with self._lock:
+            if name not in self._counters:
+                self._counters[name] = Counter(name=name, help_text=help_text)
+
+    def register_histogram(
+        self, name: str, help_text: str, buckets: tuple[float, ...] = DEFAULT_LATENCY_BUCKETS
+    ) -> None:
+        """Register a new histogram metric.
+
+        Args:
+            name: Metric name (should follow Prometheus naming conventions)
+            help_text: Human-readable description
+            buckets: Upper bounds for histogram buckets
+        """
+        with self._lock:
+            if name not in self._histograms:
+                self._histograms[name] = Histogram(name=name, help_text=help_text, buckets=buckets)
+
+    def increment_counter(
+        self, name: str, labels: dict[str, str] | None = None, value: float = 1.0
+    ) -> None:
+        """Increment a counter metric.
+
+        Args:
+            name: Metric name
+            labels: Optional label key-value pairs
+            value: Amount to increment (default: 1.0)
+        """
+        with self._lock:
+            if name in self._counters:
+                self._counters[name].increment(labels, value)
+
+    def observe_histogram(
+        self, name: str, value: float, labels: dict[str, str] | None = None
+    ) -> None:
+        """Record an observation in a histogram.
+
+        Args:
+            name: Metric name
+            value: The observed value
+            labels: Optional label key-value pairs
+        """
+        with self._lock:
+            if name in self._histograms:
+                self._histograms[name].observe(value, labels)
+
+    def get_counter(self, name: str, labels: dict[str, str] | None = None) -> float:
+        """Get current counter value.
+
+        Args:
+            name: Metric name
+            labels: Optional label key-value pairs
+
+        Returns:
+            Current counter value or 0.0 if not found
+        """
+        with self._lock:
+            if name in self._counters:
+                return self._counters[name].get(labels)
+            return 0.0
+
+    def get_histogram_count(self, name: str, labels: dict[str, str] | None = None) -> float:
+        """Get histogram observation count.
+
+        Args:
+            name: Metric name
+            labels: Optional label key-value pairs
+
+        Returns:
+            Total observation count or 0.0 if not found
+        """
+        with self._lock:
+            if name in self._histograms:
+                return self._histograms[name].get_count(labels)
+            return 0.0
+
+    def _format_labels(self, labels: tuple[tuple[str, str], ...]) -> str:
+        """Format labels for Prometheus output.
+
+        Prometheus label values must escape backslashes and double quotes.
+        Backslashes are escaped as \\, and double quotes are escaped as \\".
+
+        Args:
+            labels: Sorted tuple of label key-value pairs
+
+        Returns:
+            Formatted label string (e.g., '{key="value",key2="value2"}')
+        """
+        if not labels:
+            return ""
+
+        def escape_label_value(value: str) -> str:
+            """Escape label value per Prometheus specification."""
+            # Escape backslashes first (to avoid double-escaping)
+            value = value.replace("\\", "\\\\")
+            # Escape double quotes
+            return value.replace('"', '\\"')
+
+        parts = [f'{k}="{escape_label_value(v)}"' for k, v in labels]
+        return "{" + ",".join(parts) + "}"
+
+    def export_prometheus(self) -> str:
+        """Export all metrics in Prometheus text format.
+
+        Returns:
+            Metrics in Prometheus exposition format
+
+        Example:
+            >>> collector = MetricsCollector()
+            >>> collector.increment_counter("asap_requests_total", {"status": "success"})
+            >>> output = collector.export_prometheus()
+            >>> "asap_requests_total" in output
+            True
+        """
+        lines: list[str] = []
+
+        with self._lock:
+            # Export counters
+            for counter in self._counters.values():
+                lines.append(f"# HELP {counter.name} {counter.help_text}")
+                lines.append(f"# TYPE {counter.name} counter")
+                if not counter.values:
+                    # Export zero value if no data
+                    lines.append(f"{counter.name} 0")
+                else:
+                    for label_key, value in counter.values.items():
+                        label_str = self._format_labels(label_key)
+                        lines.append(f"{counter.name}{label_str} {value}")
+
+            # Export histograms
+            for histogram in self._histograms.values():
+                lines.append(f"# HELP {histogram.name} {histogram.help_text}")
+                lines.append(f"# TYPE {histogram.name} histogram")
+                if not histogram.values:
+                    # Export zero values if no data
+                    for bound in histogram.buckets:
+                        lines.append(f'{histogram.name}_bucket{{le="{bound}"}} 0')
+                    lines.append(f'{histogram.name}_bucket{{le="+Inf"}} 0')
+                    lines.append(f"{histogram.name}_sum 0")
+                    lines.append(f"{histogram.name}_count 0")
+                else:
+                    for label_key, data in histogram.values.items():
+                        base_labels = self._format_labels(label_key)
+
+                        # Bucket values
+                        buckets = data["buckets"]
+                        cumulative = 0.0
+                        if isinstance(buckets, dict):
+                            for bound in histogram.buckets:
+                                cumulative += buckets.get(bound, 0.0)
+                                if base_labels:
+                                    # Insert le before closing brace
+                                    label_str = base_labels[:-1] + f',le="{bound}"' + "}"
+                                else:
+                                    label_str = f'{{le="{bound}"}}'
+                                lines.append(f"{histogram.name}_bucket{label_str} {cumulative}")
+
+                        # +Inf bucket (total count)
+                        count = data.get("count", 0.0)
+                        if base_labels:
+                            label_str = base_labels[:-1] + ',le="+Inf"}'
+                        else:
+                            label_str = '{le="+Inf"}'
+                        lines.append(f"{histogram.name}_bucket{label_str} {count}")
+
+                        # Sum and count
+                        sum_val = data.get("sum", 0.0)
+                        lines.append(f"{histogram.name}_sum{base_labels} {sum_val}")
+                        lines.append(f"{histogram.name}_count{base_labels} {count}")
+
+            # Add process uptime
+            uptime = time.time() - self._start_time
+            lines.append("# HELP asap_process_uptime_seconds Time since server start")
+            lines.append("# TYPE asap_process_uptime_seconds gauge")
+            lines.append(f"asap_process_uptime_seconds {uptime:.3f}")
+
+        return "\n".join(lines) + "\n"
+
+    def reset(self) -> None:
+        """Reset all metrics to zero. Useful for testing."""
+        with self._lock:
+            for counter in self._counters.values():
+                counter.values.clear()
+            for histogram in self._histograms.values():
+                histogram.values.clear()
+
+
+# Global metrics collector instance
+_metrics_collector: MetricsCollector | None = None
+_collector_lock = threading.Lock()
+
+
+def get_metrics() -> MetricsCollector:
+    """Get the global metrics collector instance.
+
+    Returns:
+        The global MetricsCollector singleton
+
+    Example:
+        >>> metrics = get_metrics()
+        >>> metrics.increment_counter("asap_requests_total")
+    """
+    global _metrics_collector
+    with _collector_lock:
+        if _metrics_collector is None:
+            _metrics_collector = MetricsCollector()
+        return _metrics_collector
+
+
+def reset_metrics() -> None:
+    """Reset the global metrics collector. Useful for testing."""
+    global _metrics_collector
+    with _collector_lock:
+        if _metrics_collector is not None:
+            _metrics_collector.reset()