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

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)