alma-memory 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

alma/observability/__init__.py

@@ -0,0 +1,91 @@
+"""
+ALMA Observability Module.
+
+Provides comprehensive observability features including:
+- OpenTelemetry integration for distributed tracing
+- Structured JSON logging
+- Metrics collection (counters, histograms, gauges)
+- Performance monitoring
+
+This module follows the OpenTelemetry specification and supports
+integration with common observability backends (Jaeger, Prometheus,
+DataDog, etc.).
+
+Usage:
+    from alma.observability import (
+        get_tracer,
+        get_meter,
+        get_logger,
+        configure_observability,
+        ALMAMetrics,
+    )
+
+    # Initialize observability (typically at app startup)
+    configure_observability(
+        service_name="alma-memory",
+        enable_tracing=True,
+        enable_metrics=True,
+        log_format="json",
+    )
+
+    # Use in code
+    tracer = get_tracer(__name__)
+    with tracer.start_as_current_span("my_operation"):
+        # ... your code
+        pass
+"""
+
+from alma.observability.config import (
+    ObservabilityConfig,
+    configure_observability,
+    shutdown_observability,
+)
+from alma.observability.guidelines import (
+    OPERATION_LOG_LEVELS,
+    get_recommended_level,
+)
+from alma.observability.logging import (
+    JSONFormatter,
+    StructuredLogger,
+    get_logger,
+    setup_logging,
+)
+from alma.observability.metrics import (
+    ALMAMetrics,
+    MetricsCollector,
+    get_meter,
+    get_metrics,
+)
+from alma.observability.tracing import (
+    SpanKind,
+    TracingContext,
+    get_tracer,
+    trace_async,
+    trace_method,
+)
+
+__all__ = [
+    # Configuration
+    "ObservabilityConfig",
+    "configure_observability",
+    "shutdown_observability",
+    # Logging
+    "JSONFormatter",
+    "StructuredLogger",
+    "get_logger",
+    "setup_logging",
+    # Metrics
+    "ALMAMetrics",
+    "MetricsCollector",
+    "get_meter",
+    "get_metrics",
+    # Tracing
+    "SpanKind",
+    "TracingContext",
+    "get_tracer",
+    "trace_method",
+    "trace_async",
+    # Guidelines
+    "OPERATION_LOG_LEVELS",
+    "get_recommended_level",
+]

alma/observability/config.py

@@ -0,0 +1,302 @@
+"""
+ALMA Observability Configuration.
+
+Centralized configuration for observability features including
+tracing, metrics, and logging setup.
+"""
+
+import logging
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+# Global state for observability configuration
+_observability_initialized = False
+_tracer_provider = None
+_meter_provider = None
+
+
+@dataclass
+class ObservabilityConfig:
+    """
+    Configuration for ALMA observability features.
+
+    Attributes:
+        service_name: Name of the service for tracing/metrics
+        service_version: Version of the service
+        environment: Deployment environment (dev, staging, prod)
+        enable_tracing: Whether to enable distributed tracing
+        enable_metrics: Whether to enable metrics collection
+        enable_logging: Whether to enable structured logging
+        log_level: Logging level (DEBUG, INFO, WARNING, ERROR)
+        log_format: Log format ("json" or "text")
+        otlp_endpoint: OpenTelemetry collector endpoint
+        otlp_headers: Headers for OTLP exporter
+        trace_sample_rate: Sampling rate for traces (0.0-1.0)
+        metric_export_interval_ms: How often to export metrics
+        resource_attributes: Additional resource attributes
+    """
+
+    service_name: str = "alma-memory"
+    service_version: str = "0.5.1"
+    environment: str = field(
+        default_factory=lambda: os.environ.get("ALMA_ENVIRONMENT", "development")
+    )
+    enable_tracing: bool = True
+    enable_metrics: bool = True
+    enable_logging: bool = True
+    log_level: str = field(
+        default_factory=lambda: os.environ.get("ALMA_LOG_LEVEL", "INFO")
+    )
+    log_format: str = field(
+        default_factory=lambda: os.environ.get("ALMA_LOG_FORMAT", "json")
+    )
+    otlp_endpoint: Optional[str] = field(
+        default_factory=lambda: os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
+    )
+    otlp_headers: Dict[str, str] = field(default_factory=dict)
+    trace_sample_rate: float = 1.0
+    metric_export_interval_ms: int = 60000
+    resource_attributes: Dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert config to dictionary."""
+        return {
+            "service_name": self.service_name,
+            "service_version": self.service_version,
+            "environment": self.environment,
+            "enable_tracing": self.enable_tracing,
+            "enable_metrics": self.enable_metrics,
+            "enable_logging": self.enable_logging,
+            "log_level": self.log_level,
+            "log_format": self.log_format,
+            "otlp_endpoint": self.otlp_endpoint,
+            "trace_sample_rate": self.trace_sample_rate,
+            "metric_export_interval_ms": self.metric_export_interval_ms,
+        }
+
+
+def configure_observability(
+    service_name: str = "alma-memory",
+    service_version: str = "0.5.1",
+    environment: Optional[str] = None,
+    enable_tracing: bool = True,
+    enable_metrics: bool = True,
+    enable_logging: bool = True,
+    log_level: str = "INFO",
+    log_format: str = "json",
+    otlp_endpoint: Optional[str] = None,
+    trace_sample_rate: float = 1.0,
+    resource_attributes: Optional[Dict[str, str]] = None,
+) -> ObservabilityConfig:
+    """
+    Configure ALMA observability features.
+
+    This function should be called once at application startup to initialize
+    tracing, metrics, and logging.
+
+    Args:
+        service_name: Name of the service
+        service_version: Version of the service
+        environment: Deployment environment
+        enable_tracing: Enable distributed tracing
+        enable_metrics: Enable metrics collection
+        enable_logging: Enable structured logging
+        log_level: Logging level
+        log_format: Log format ("json" or "text")
+        otlp_endpoint: OpenTelemetry collector endpoint
+        trace_sample_rate: Sampling rate for traces
+        resource_attributes: Additional resource attributes
+
+    Returns:
+        ObservabilityConfig with applied settings
+    """
+    global _observability_initialized, _tracer_provider, _meter_provider
+
+    config = ObservabilityConfig(
+        service_name=service_name,
+        service_version=service_version,
+        environment=environment or os.environ.get("ALMA_ENVIRONMENT", "development"),
+        enable_tracing=enable_tracing,
+        enable_metrics=enable_metrics,
+        enable_logging=enable_logging,
+        log_level=log_level,
+        log_format=log_format,
+        otlp_endpoint=otlp_endpoint,
+        trace_sample_rate=trace_sample_rate,
+        resource_attributes=resource_attributes or {},
+    )
+
+    # Setup logging first
+    if config.enable_logging:
+        from alma.observability.logging import setup_logging
+
+        setup_logging(
+            level=config.log_level,
+            format_type=config.log_format,
+            service_name=config.service_name,
+        )
+
+    # Setup tracing
+    if config.enable_tracing:
+        _tracer_provider = _setup_tracing(config)
+
+    # Setup metrics
+    if config.enable_metrics:
+        _meter_provider = _setup_metrics(config)
+
+    _observability_initialized = True
+
+    logger = logging.getLogger(__name__)
+    logger.info(
+        "ALMA observability configured",
+        extra={
+            "service_name": config.service_name,
+            "environment": config.environment,
+            "tracing_enabled": config.enable_tracing,
+            "metrics_enabled": config.enable_metrics,
+        },
+    )
+
+    return config
+
+
+def _setup_tracing(config: ObservabilityConfig):
+    """Setup OpenTelemetry tracing."""
+    try:
+        from opentelemetry import trace
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.sampling import TraceIdRatioBased
+
+        # Build resource attributes
+        resource_attrs = {
+            "service.name": config.service_name,
+            "service.version": config.service_version,
+            "deployment.environment": config.environment,
+        }
+        resource_attrs.update(config.resource_attributes)
+
+        resource = Resource.create(resource_attrs)
+
+        # Create sampler
+        sampler = TraceIdRatioBased(config.trace_sample_rate)
+
+        # Create and set tracer provider
+        provider = TracerProvider(resource=resource, sampler=sampler)
+
+        # Add OTLP exporter if endpoint is configured
+        if config.otlp_endpoint:
+            try:
+                from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+                    OTLPSpanExporter,
+                )
+                from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+                otlp_exporter = OTLPSpanExporter(
+                    endpoint=config.otlp_endpoint,
+                    headers=config.otlp_headers or {},
+                )
+                provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
+            except ImportError:
+                logging.getLogger(__name__).warning(
+                    "OTLP exporter not available. Install with: "
+                    "pip install opentelemetry-exporter-otlp-proto-grpc"
+                )
+
+        trace.set_tracer_provider(provider)
+        return provider
+
+    except ImportError:
+        logging.getLogger(__name__).warning(
+            "OpenTelemetry SDK not available. Tracing disabled. "
+            "Install with: pip install opentelemetry-sdk"
+        )
+        return None
+
+
+def _setup_metrics(config: ObservabilityConfig):
+    """Setup OpenTelemetry metrics."""
+    try:
+        from opentelemetry import metrics
+        from opentelemetry.sdk.metrics import MeterProvider
+        from opentelemetry.sdk.resources import Resource
+
+        # Build resource attributes
+        resource_attrs = {
+            "service.name": config.service_name,
+            "service.version": config.service_version,
+            "deployment.environment": config.environment,
+        }
+        resource_attrs.update(config.resource_attributes)
+
+        resource = Resource.create(resource_attrs)
+
+        # Create meter provider
+        provider = MeterProvider(resource=resource)
+
+        # Add OTLP exporter if endpoint is configured
+        if config.otlp_endpoint:
+            try:
+                from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
+                    OTLPMetricExporter,
+                )
+                from opentelemetry.sdk.metrics.export import (
+                    PeriodicExportingMetricReader,
+                )
+
+                otlp_exporter = OTLPMetricExporter(
+                    endpoint=config.otlp_endpoint,
+                    headers=config.otlp_headers or {},
+                )
+                reader = PeriodicExportingMetricReader(
+                    otlp_exporter,
+                    export_interval_millis=config.metric_export_interval_ms,
+                )
+                provider = MeterProvider(resource=resource, metric_readers=[reader])
+            except ImportError:
+                logging.getLogger(__name__).warning(
+                    "OTLP metric exporter not available. Install with: "
+                    "pip install opentelemetry-exporter-otlp-proto-grpc"
+                )
+
+        metrics.set_meter_provider(provider)
+        return provider
+
+    except ImportError:
+        logging.getLogger(__name__).warning(
+            "OpenTelemetry SDK not available. Metrics disabled. "
+            "Install with: pip install opentelemetry-sdk"
+        )
+        return None
+
+
+def shutdown_observability():
+    """
+    Shutdown observability providers.
+
+    Should be called at application shutdown to ensure all telemetry
+    data is exported.
+    """
+    global _observability_initialized, _tracer_provider, _meter_provider
+
+    if _tracer_provider is not None:
+        try:
+            _tracer_provider.shutdown()
+        except Exception as e:
+            logging.getLogger(__name__).error(f"Error shutting down tracer: {e}")
+
+    if _meter_provider is not None:
+        try:
+            _meter_provider.shutdown()
+        except Exception as e:
+            logging.getLogger(__name__).error(f"Error shutting down meter: {e}")
+
+    _observability_initialized = False
+    _tracer_provider = None
+    _meter_provider = None
+
+
+def is_observability_initialized() -> bool:
+    """Check if observability has been initialized."""
+    return _observability_initialized

alma/observability/guidelines.py

@@ -0,0 +1,170 @@
+"""
+ALMA Logging Level Guidelines.
+
+This module documents the standardized logging levels for ALMA.
+All modules should follow these guidelines for consistent logging.
+
+Logging Level Standards
+=======================
+
+DEBUG
+-----
+Use for detailed diagnostic information useful during development
+and debugging. This level should NOT be enabled in production under
+normal circumstances.
+
+Examples:
+- Cache hits/misses for individual queries
+- Internal state changes (e.g., "Updated work item: {item_id}")
+- Function entry/exit with parameters
+- Detailed timing breakdowns
+- Query/embedding details
+
+INFO
+----
+Use for high-level operation completion and significant lifecycle events.
+These logs confirm that things are working as expected.
+
+Examples:
+- Service startup/shutdown
+- Memory retrieval/learning operations completed (with summary metrics)
+- Scheduled job execution completed
+- Configuration loaded successfully
+- Database/storage connections established
+- Batch operations completed with counts
+
+WARNING
+-------
+Use for recoverable issues that may indicate problems but don't prevent
+operation. The system continues to function but something unexpected happened.
+
+Examples:
+- Agent has no defined scope, using defaults
+- Optional feature unavailable (e.g., "aiohttp not installed")
+- Failed to retrieve optional data (e.g., git commands timeout)
+- Near-quota conditions
+- Deprecated feature usage
+- Retry attempts
+- Missing optional configuration
+
+ERROR
+-----
+Use for failures that need attention. These indicate that an operation
+failed and likely requires investigation or intervention.
+
+Examples:
+- Storage operation failures
+- Failed to process required data
+- Authentication/authorization failures
+- Configuration errors preventing operation
+- Unrecoverable API errors
+- Data corruption detected
+- Resource exhaustion
+
+CRITICAL
+--------
+Use for severe failures that may cause application shutdown or
+complete loss of functionality. These require immediate attention.
+
+Examples:
+- Database connection permanently lost
+- Critical configuration missing
+- Unrecoverable system state
+- Security breach detected
+
+Implementation Notes
+====================
+
+1. Logger Initialization:
+   - Use standard logging: logger = logging.getLogger(__name__)
+   - For structured logging features, also use: structured_logger = get_logger(__name__)
+
+2. Message Format:
+   - Start with action or subject (e.g., "Memory retrieval completed", "Failed to save heuristic")
+   - Include relevant context as structured fields
+   - Keep messages concise but informative
+
+3. Structured Logging:
+   - Use structured_logger for operations that benefit from structured fields
+   - Pass context as keyword arguments for JSON serialization
+   - Example: structured_logger.info("Retrieved memories", agent=agent, count=count)
+
+4. Exception Logging:
+   - Use logger.error(..., exc_info=True) or logger.exception() for exceptions
+   - Include context about what operation was being attempted
+
+5. Performance Logging:
+   - Log duration for operations > 100ms at INFO level
+   - Log internal operation timing at DEBUG level
+
+Examples
+========
+
+# DEBUG - Internal diagnostics
+logger.debug(f"Cache hit for query: {query[:50]}...")
+logger.debug(f"Updated heuristic: {heuristic_id}")
+logger.debug(f"Saved outcome: {outcome.id}")
+
+# INFO - Operation completions
+logger.info(f"Memory retrieval completed: {count} items in {duration_ms}ms")
+logger.info(f"Cleanup scheduler started (interval: {interval}s)")
+logger.info("ChromaDB storage closed")
+
+# WARNING - Recoverable issues
+logger.warning(f"Agent '{agent}' has no defined scope, using defaults")
+logger.warning("aiohttp not installed - webhook delivery unavailable")
+logger.warning(f"Failed to retrieve memories: {e}")
+
+# ERROR - Failures requiring attention
+logger.error(f"Failed to save heuristic {heuristic_id}: {e}")
+logger.error(f"Redis connection error: {e}")
+logger.error("Config file not found, cannot proceed")
+"""
+
+# Log level constants for programmatic use
+import logging
+
+# Map of operation types to recommended log levels
+OPERATION_LOG_LEVELS = {
+    # Storage operations
+    "save_success": logging.DEBUG,
+    "save_failure": logging.ERROR,
+    "batch_save_success": logging.DEBUG,
+    "delete_success": logging.DEBUG,
+    "delete_failure": logging.ERROR,
+    # Retrieval operations
+    "cache_hit": logging.DEBUG,
+    "cache_miss": logging.DEBUG,
+    "cache_invalidate": logging.DEBUG,
+    "retrieval_complete": logging.INFO,
+    # Learning operations
+    "learn_complete": logging.INFO,
+    "heuristic_updated": logging.DEBUG,
+    # Lifecycle events
+    "service_start": logging.INFO,
+    "service_stop": logging.INFO,
+    "connection_established": logging.INFO,
+    "config_loaded": logging.INFO,
+    # Warnings
+    "missing_scope": logging.WARNING,
+    "optional_feature_unavailable": logging.WARNING,
+    "retry_attempt": logging.WARNING,
+    "deprecation": logging.WARNING,
+    # Errors
+    "operation_failure": logging.ERROR,
+    "connection_failure": logging.ERROR,
+    "validation_failure": logging.ERROR,
+}
+
+
+def get_recommended_level(operation: str) -> int:
+    """
+    Get the recommended log level for a given operation type.
+
+    Args:
+        operation: The operation type (e.g., "save_success", "cache_hit")
+
+    Returns:
+        Logging level constant (e.g., logging.DEBUG, logging.INFO)
+    """
+    return OPERATION_LOG_LEVELS.get(operation, logging.INFO)