litewave-logger 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

litewave_logger/__init__.py

@@ -1,5 +1,5 @@
 import logging
-import uuid
+import json
 from contextvars import ContextVar
 
 # Context variable to hold the request ID
@@ -8,6 +8,9 @@ from contextvars import ContextVar
 # Magically, this is maintained across multiple requests without it getting mixed up.
 request_id_var = ContextVar("request_id", default=None)
 
+# List of endpoints that should not be logged
+_excluded_endpoints = []
+
 
 class RequestIdFilter(logging.Filter):
     """
@@ -17,21 +20,45 @@ class RequestIdFilter(logging.Filter):
         record.request_id = request_id_var.get()
         return True
 
+class JsonLogFormatter(logging.Formatter):
+    """
+    Formatter that outputs logs as JSON with required fields.
+    """
+    def format(self, record):
+        # Collect fields with fallback to None for path, method, and status_code
+        log_object = {
+            "timestamp": self.formatTime(record, self.datefmt),
+            "level": record.levelname,
+            "request_id": getattr(record, "request_id", None),
+            "path": getattr(record, "path", None),
+            "method": getattr(record, "method", None),
+            "message": record.getMessage(),
+            "status_code": getattr(record, "status_code", None),
+            "error": getattr(record, "error", None),
+        }
+        return json.dumps(log_object)
 
-def setup_logging():
+def setup_logging(excluded_endpoints=[]):
     """
     Configures the logging for the application.
-    It sets up a handler, a formatter, and adds the RequestIdFilter.
+    Uses a JSON formatter and adds the RequestIdFilter.
+
+    Args:
+        excluded_endpoints: List of endpoint paths that should not be logged.
+                          For example: ['/health', '/metrics']
+                          Defaults to None (empty list).
     """
+    global _excluded_endpoints
+
+    _excluded_endpoints = excluded_endpoints
+
     logger = logging.getLogger()
     logger.setLevel(logging.INFO)
 
     # Prevent adding duplicate handlers
     if not logger.handlers:
         handler = logging.StreamHandler()
-        formatter = logging.Formatter(
-            "%(asctime)s - %(name)s - %(levelname)s - [%(request_id)s] - %(message)s"
-        )
+        formatter = JsonLogFormatter()
         handler.setFormatter(formatter)
         logger.addHandler(handler)
 
@@ -42,4 +69,10 @@ def setup_logging():
 
     return logger
 
-__all__ = ["setup_logging", "request_id_var", "RequestIdFilter"]
+def get_excluded_endpoints():
+    """
+    Returns the list of excluded endpoints.
+    """
+    return _excluded_endpoints
+
+__all__ = ["setup_logging", "request_id_var", "RequestIdFilter", "get_excluded_endpoints"]

litewave_logger/middleware.py

@@ -1,31 +1,64 @@
 import uuid
+import time
+import logging
+from datetime import datetime
 from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.requests import Request
 
-from . import request_id_var
+from . import request_id_var, get_excluded_endpoints
 
-# This middleware is used to handle the request ID.
+logger = logging.getLogger(__name__)
+RequestIdHeader = "X-Request-ID"
+# This middleware is used to handle the request ID and provide comprehensive debugging.
 # It checks for a 'X-Request-ID' header in the incoming request.
 # If the header is present, its value is used as the request ID.
 # If not, a new UUID is generated.
 # The request ID is then stored in a context variable.
 class RequestIdMiddleware(BaseHTTPMiddleware):
     """
-    FastAPI middleware to handle the request ID.
+    FastAPI middleware to handle the request ID and provide comprehensive debugging.
     It checks for a 'X-Request-ID' header in the incoming request.
     If the header is present, its value is used as the request ID.
     If not, a new UUID is generated.
     The request ID is then stored in a context variable.
+    Provides detailed logging for incoming requests and outgoing responses.
     """
     async def dispatch(self, request: Request, call_next):
-        request_id = request.headers.get("X-Request-ID")
+        # Extract request information
+        method = request.method
+        path = request.url.path
+        # Get or generate request ID
+        request_id = request.headers.get(RequestIdHeader)
         if not request_id:
             request_id = str(uuid.uuid4())
-        
+
+        # Set request ID in context
         request_id_var.set(request_id)
-        
-        response = await call_next(request)
-        response.headers["X-Request-ID"] = request_id_var.get()
-        return response
+
+        # Check if this endpoint should be excluded from logging
+        excluded_endpoints = get_excluded_endpoints()
+        should_log = path not in excluded_endpoints
+
+        if should_log:
+            logger.info("request received", extra={"method": method, "path": path})
+
+        try:
+            # Process the request
+            response = await call_next(request)
+
+            # Add request ID to response headers
+            response.headers[RequestIdHeader] = request_id
+
+            # Log response details only if endpoint is not excluded
+            if should_log:
+                logger.info("response sent", extra={"status_code": response.status_code})
+
+            return response
+
+        except Exception as e:
+            logger.error("request failed", extra={"method": method, "path": path, "error": str(e)})
+
+            # Re-raise the exception
+            raise
 
 __all__ = ["RequestIdMiddleware"]

{litewave_logger-0.1.0.dist-info → litewave_logger-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: litewave_logger
-Version: 0.1.0
+Version: 0.3.0
 Summary: A lightweight logging library with context carry forward
 Author: Litewave
 Author-email: Sonu Sudhakaran <sonu@litewave.ai>
@@ -18,10 +18,12 @@ This module provides a centralized and consistent logging solution for Litewave
 ## Features
 
 - **Centralized Logging**: A single module to configure and manage logging across all services.
+- **JSON Logging**: All logs are formatted as JSON for easy parsing and integration with log aggregation systems.
 - **Request ID Propagation**: Automatically injects a `request-id` into all log messages.
-- **FastAPI Integration**: Middleware for FastAPI to handle `request-id` for incoming HTTP requests.
-- **Celery Integration**: Signal handlers to propagate the `request-id` to Celery tasks.
+- **FastAPI Integration**: Middleware for FastAPI to handle `request-id` for incoming HTTP requests and adds it to response headers.
+- **Celery Integration**: Signal handlers to propagate the `request-id` to Celery tasks automatically.
 - **Requests Library Patching**: Automatically injects the `request-id` into outgoing HTTP requests made with the `requests` library.
+- **Endpoint Exclusion**: Configure endpoints that should not be logged (e.g., health checks, metrics).
 
 ## Installation
 
@@ -37,7 +39,8 @@ To use the `litewave_logger` in your service, follow these steps:
     ```python
     from litewave_logger import setup_logging
 
-    setup_logging()
+    # Optionally exclude endpoints from logging (e.g., health checks, metrics)
+    setup_logging(excluded_endpoints=['/health', '/metrics'])
     ```
 
 2.  **Add the FastAPI middleware**: If your service is a FastAPI application, add the `RequestIdMiddleware` to your FastAPI app.
@@ -58,10 +61,11 @@ To use the `litewave_logger` in your service, follow these steps:
     patch_requests()
     ```
 
-4.  **Connect Celery signals**: If your service uses Celery, you need to import the Celery signal handlers to ensure they are registered. You don't need to call them directly.
+4.  **Connect Celery signals**: If your service uses Celery, you need to import the Celery module to ensure the signal handlers are registered. The signal handlers are automatically connected via decorators, so you don't need to call them directly.
 
     ```python
-    from litewave_logger.celery import propagate_request_id_to_celery, clear_request_id_after_celery
+    # Just import the module - signal handlers are automatically registered
+    import litewave_logger.celery
     ```
 
 ### Example
@@ -74,11 +78,11 @@ from litewave_logger import setup_logging
 from litewave_logger.middleware import RequestIdMiddleware
 from litewave_logger.requests import patch_requests
 
-# These imports are needed to register the signal handlers
-from litewave_logger.celery import propagate_request_id_to_celery, clear_request_id_after_celery
+# Import Celery module to register signal handlers (if using Celery)
+import litewave_logger.celery
 
-# 1. Initialize logging
-setup_logging()
+# 1. Initialize logging (optionally exclude endpoints)
+setup_logging(excluded_endpoints=['/health', '/metrics'])
 
 # 2. Patch requests library
 patch_requests()
@@ -90,3 +94,31 @@ app.add_middleware(RequestIdMiddleware)
 
 # Your application code here...
 ```
+
+## How It Works
+
+### Request ID Flow
+
+1. **Incoming HTTP Request**: The `RequestIdMiddleware` checks for an `X-Request-ID` header. If present, it uses that value; otherwise, it generates a new UUID.
+2. **Context Variable**: The request ID is stored in a context variable (`request_id_var`) that is automatically maintained across async operations.
+3. **Logging**: All log messages automatically include the request ID via the `RequestIdFilter`.
+4. **Outgoing Requests**: When using the `requests` library, the request ID is automatically injected as the `X-Request-ID` header.
+5. **Response Headers**: The request ID is added to the response headers as `X-Request-ID`.
+6. **Celery Tasks**: When a Celery task is published, the request ID is automatically included in the task headers and propagated to the worker process.
+
+### Log Format
+
+All logs are formatted as JSON with the following structure:
+
+```json
+{
+  "timestamp": "2024-01-01 12:00:00",
+  "level": "INFO",
+  "request_id": "550e8400-e29b-41d4-a716-446655440000",
+  "path": "/api/users",
+  "method": "GET",
+  "message": "request received",
+  "status_code": 200,
+  "error": null
+}
+```

litewave_logger-0.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+litewave_logger/__init__.py,sha256=gow3U-Op3f4xNTQ3ppBUD8mEAA0d_3hVa_u88mKLigg,2599
+litewave_logger/celery.py,sha256=KkeuXNTQm7P_TFj_POdt7WTHL-mcP_Jv60g06Fkw_M4,3358
+litewave_logger/middleware.py,sha256=P3Mjv0RZ7Bh7cxmJ4pH537wsORSXP-Dgn1PE9EKUcgQ,2375
+litewave_logger/requests.py,sha256=tagJVwWWSVnrYHYRJ24HXu7YNBs9WxIHql0E1fRkbGA,1236
+litewave_logger-0.3.0.dist-info/METADATA,sha256=3aIHcutM1eocQhI50SVjKpB3U1rCglvbwbL9CW5v7OQ,4839
+litewave_logger-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+litewave_logger-0.3.0.dist-info/top_level.txt,sha256=omvs1vFc7ccmip7_gMDjF_3F8omnR-Gdfm2UudrqWuo,16
+litewave_logger-0.3.0.dist-info/RECORD,,

litewave_logger-0.1.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-litewave_logger/__init__.py,sha256=NgRQIlAbGXrlVoL5hcWHs3jbeNZPJ3j9zLuPfpf6vPc,1443
-litewave_logger/celery.py,sha256=KkeuXNTQm7P_TFj_POdt7WTHL-mcP_Jv60g06Fkw_M4,3358
-litewave_logger/middleware.py,sha256=oiWsRO9i8W7hlQrg0wJvOmAxqTkjkvASKa2psaA9Tbk,1161
-litewave_logger/requests.py,sha256=tagJVwWWSVnrYHYRJ24HXu7YNBs9WxIHql0E1fRkbGA,1236
-litewave_logger-0.1.0.dist-info/METADATA,sha256=0TSMGW8hGWb42X7Ls7Hfe7LN7gIqv3eyPBDD0C7StwA,3211
-litewave_logger-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-litewave_logger-0.1.0.dist-info/top_level.txt,sha256=omvs1vFc7ccmip7_gMDjF_3F8omnR-Gdfm2UudrqWuo,16
-litewave_logger-0.1.0.dist-info/RECORD,,