auditry 0.1.0__py3-none-any.whl

auditry/__init__.py

@@ -0,0 +1,19 @@
+from .logging_config import configure_logging, get_logger
+from .correlation import get_correlation_id
+from .unified_middleware import ObservabilityMiddleware
+from .models import ObservabilityConfig, BusinessEventConfig
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Logging configuration
+    "configure_logging",
+    "get_logger",
+    # Middleware
+    "ObservabilityMiddleware",
+    # Configuration
+    "ObservabilityConfig",
+    "BusinessEventConfig",
+    # Utilities
+    "get_correlation_id",
+]

auditry/correlation.py

@@ -0,0 +1,21 @@
+"""
+Correlation ID management using asgi-correlation-id.
+
+Provides a simple function to get the current correlation ID from context.
+"""
+
+from typing import Optional
+
+from asgi_correlation_id import correlation_id
+
+__all__ = ["get_correlation_id"]
+
+
+def get_correlation_id() -> Optional[str]:
+    """
+    Get the current correlation ID from context.
+
+    Returns:
+        The correlation ID string, or None if not set
+    """
+    return correlation_id.get()

auditry/logging_config.py

@@ -0,0 +1,63 @@
+"""
+Structured logging configuration using structlog.
+
+This module provides JSON-formatted logging that integrates with
+correlation IDs and is optimized for log aggregators like Datadog.
+"""
+
+import logging
+import structlog
+
+
+def configure_logging(level: str = "INFO") -> None:
+    """
+    Configure application-wide structured logging using structlog.
+
+    Sets up JSON-formatted logging with timestamps, log levels, and
+    correlation IDs. Should be called once at application startup.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+    """
+    # Configure structlog processors
+    structlog.configure(
+        processors=[
+            # Add log level to event dict
+            structlog.stdlib.add_log_level,
+            # Add timestamp in ISO format
+            structlog.processors.TimeStamper(fmt="iso"),
+            # Add correlation_id from context if available
+            structlog.contextvars.merge_contextvars,
+            # Format exceptions
+            structlog.processors.format_exc_info,
+            # Render as JSON
+            structlog.processors.JSONRenderer(),
+        ],
+        # Use standard library logging
+        wrapper_class=structlog.stdlib.BoundLogger,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+    # Configure standard library logging
+    logging.basicConfig(
+        format="%(message)s",
+        level=getattr(logging, level.upper()),
+        force=True,
+    )
+
+
+def get_logger(name: str) -> structlog.stdlib.BoundLogger:
+    """
+    Get a structlog logger instance.
+
+    This logger automatically includes correlation IDs and outputs
+    structured JSON logs.
+
+    Args:
+        name: Logger name (typically __name__ of the module)
+
+    Returns:
+        Configured structlog logger
+    """
+    return structlog.get_logger(name)

auditry/middleware.py

@@ -0,0 +1,355 @@
+"""
+Request/Response logging middleware with sensitive data redaction.
+
+This middleware integrates with asgi-correlation-id for correlation tracking
+and uses structlog for structured logging output.
+"""
+
+import json
+import re
+import time
+from typing import Any, Dict, Optional
+
+import structlog
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import StreamingResponse
+
+from .correlation import get_correlation_id
+from .redaction import redact_data, redact_headers
+from .models import ObservabilityConfig
+
+
+logger = structlog.get_logger(__name__)
+
+
+class RequestResponseLoggingMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware to automatically log all request/response activity.
+
+    Captures comprehensive request and response data including payloads,
+    headers, timing, and user context. Integrates with asgi-correlation-id
+    for distributed tracing.
+
+    Note: This middleware should be added AFTER CorrelationIdMiddleware
+    from asgi-correlation-id to ensure correlation IDs are available.
+    """
+
+    def __init__(self, app, config: Optional[ObservabilityConfig] = None):
+        """
+        Initialize logging middleware.
+
+        Args:
+            app: FastAPI application instance
+            config: Optional configuration for logging behavior
+        """
+        super().__init__(app)
+        self.config = config or ObservabilityConfig()
+
+    async def dispatch(self, request: Request, call_next):
+        """
+        Process request/response cycle with comprehensive logging.
+
+        Captures request details, processes through application handlers,
+        captures response, and logs complete interaction with timing.
+
+        Logging strategy:
+        - On success: Log once with both request and response data
+        - On failure: Log the request data with error details
+        """
+        # Get correlation ID from context (set by CorrelationIdMiddleware)
+        correlation_id = get_correlation_id()
+
+        execution_start_time = time.time()
+
+        request_data = await self._capture_request(request, correlation_id)
+
+        try:
+            # Process the request
+            response = await call_next(request)
+
+            execution_duration_ms = (time.time() - execution_start_time) * 1000
+
+            # Capture response details
+            response_data = await self._capture_response(response, execution_duration_ms)
+
+            # Add correlation ID to response headers
+            if correlation_id:
+                response.headers[self.config.correlation_id_header] = correlation_id
+
+            # Check if this is a business event and extract context
+            business_event_data = self._extract_business_event(
+                request, request_data, response_data
+            )
+
+            # Log successful request completion with both request and response data
+            log_data = {
+                "service": self.config.service_name,
+                "request": request_data,
+                "response": response_data,
+                "execution_duration_ms": execution_duration_ms,
+            }
+
+            # Add business event data if this endpoint is tracked
+            if business_event_data:
+                log_data.update(business_event_data)
+
+            logger.info(
+                f"Request completed: {request.method} {request.url.path} - "
+                f"Status: {response.status_code} - Duration: {execution_duration_ms:.2f}ms",
+                **log_data,
+            )
+
+            return response
+
+        except Exception as e:
+            execution_duration_ms = (time.time() - execution_start_time) * 1000
+
+            # Log error with full request context
+            logger.error(
+                f"Request failed: {request.method} {request.url.path} - "
+                f"Error: {type(e).__name__}: {str(e)} - Duration: {execution_duration_ms:.2f}ms",
+                service=self.config.service_name,
+                request=request_data,
+                exception_type=type(e).__name__,
+                exception_message=str(e),
+                execution_duration_ms=execution_duration_ms,
+                exc_info=True,
+            )
+            # Re-raise to let FastAPI's exception handlers deal with it
+            raise
+
+    async def _capture_request(self, request: Request, correlation_id: Optional[str]) -> Dict[str, Any]:
+        """
+        Capture all relevant request details for logging.
+
+        Extracts method, path, headers, query params, body, and user info.
+        Applies redaction and size limits to protect sensitive data.
+        """
+        # Extract user ID from request state (set by auth middleware/dependencies)
+        # Simplified to support two common patterns:
+        # 1. request.state.user_id (direct ID)
+        # 2. request.state.user.id (AuthenticatedUser object)
+        user_id = None
+        if hasattr(request.state, "user_id"):
+            user_id = request.state.user_id
+        elif hasattr(request.state, "user") and hasattr(request.state.user, "id"):
+            user_id = request.state.user.id
+
+        # Capture headers (with redaction)
+        headers = None
+        if self.config.log_request_headers:
+            headers = redact_headers(dict(request.headers))
+
+        # Capture query params
+        query_params = None
+        if self.config.log_query_params:
+            query_params = dict(request.query_params)
+
+        # Capture request body
+        body = await self._capture_request_body(request)
+
+        return {
+            "method": request.method,
+            "path": request.url.path,
+            "query_params": query_params,
+            "headers": headers,
+            "body": body,
+            "user_id": user_id,
+            "correlation_id": correlation_id,
+        }
+
+    def _parse_body_bytes(self, body_bytes: bytes) -> Optional[Any]:
+        """
+        Parse body bytes with size limiting and JSON detection.
+
+        Truncates large payloads and attempts JSON parsing with redaction.
+        """
+        if not body_bytes:
+            return None
+
+        # Check size limit
+        if len(body_bytes) > self.config.payload_size_limit:
+            return {
+                "_truncated": True,
+                "_original_size": len(body_bytes),
+                "_preview": body_bytes[: self.config.payload_size_limit].decode(
+                    "utf-8", errors="replace"
+                ),
+            }
+
+        # Try to parse as JSON
+        try:
+            body_json = json.loads(body_bytes)
+            # Apply redaction to body
+            return redact_data(body_json, self.config.additional_redaction_patterns)
+        except json.JSONDecodeError:
+            # Not JSON, return as string
+            return body_bytes.decode("utf-8", errors="replace")
+
+    async def _capture_request_body(self, request: Request) -> Optional[Any]:
+        """
+        Capture and parse request body with size limiting.
+
+        Attempts to parse JSON bodies. Truncates large payloads to
+        prevent excessive log volume.
+        """
+        try:
+            body_bytes = await request.body()
+            return self._parse_body_bytes(body_bytes)
+        except Exception as e:
+            logger.warning(f"Failed to capture request body: {e}")
+            return None
+
+    async def _capture_response(self, response: Response, duration_ms: float) -> Dict[str, Any]:
+        """
+        Capture response details for logging.
+
+        Extracts status code, headers, and body. Handles streaming
+        responses by capturing body chunks.
+        """
+        # Capture headers (with redaction)
+        headers = None
+        if self.config.log_response_headers:
+            headers = redact_headers(dict(response.headers))
+
+        # Capture response body
+        body = await self._capture_response_body(response)
+
+        return {
+            "status_code": response.status_code,
+            "headers": headers,
+            "body": body,
+            "duration_ms": duration_ms,
+        }
+
+    async def _capture_response_body(self, response: Response) -> Optional[Any]:
+        """
+        Capture and parse response body with size limiting.
+
+        Handles regular responses and streaming responses. Truncates
+        large payloads to prevent excessive log volume.
+        """
+        try:
+            # For streaming responses, we can't easily capture the body without consuming it
+            if isinstance(response, StreamingResponse):
+                return {"_streaming": True, "_message": "Streaming response body not captured"}
+
+            # Get body if available
+            if hasattr(response, "body"):
+                return self._parse_body_bytes(response.body)
+
+            return None
+
+        except Exception as e:
+            logger.warning(f"Failed to capture response body: {e}")
+            return None
+
+    def _extract_business_event(
+        self,
+        request: Request,
+        request_data: Dict[str, Any],
+        response_data: Dict[str, Any],
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Check if this request matches a configured business event and extract relevant fields.
+
+        Returns dict with event_type and business_context if matched, None otherwise.
+        """
+        if not self.config.business_events:
+            return None
+
+        # Build endpoint pattern: "METHOD /path"
+        endpoint_pattern = f"{request.method} {request.url.path}"
+
+        # Check each configured business event
+        for pattern, event_config in self.config.business_events.items():
+            if self._matches_endpoint_pattern(endpoint_pattern, pattern):
+                # Extract business context fields
+                business_context = {}
+
+                # Extract from request body
+                if event_config.extract_from_request and request_data.get("body"):
+                    request_body = request_data["body"]
+                    if isinstance(request_body, dict):
+                        for field in event_config.extract_from_request:
+                            if field in request_body:
+                                business_context[field] = request_body[field]
+
+                # Extract from response body
+                if event_config.extract_from_response and response_data.get("body"):
+                    response_body = response_data["body"]
+                    if isinstance(response_body, dict):
+                        for field in event_config.extract_from_response:
+                            if field in response_body:
+                                business_context[field] = response_body[field]
+
+                # Extract from path parameters
+                if event_config.extract_from_path:
+                    path_params = self._extract_path_params(request.url.path, pattern)
+                    for param in event_config.extract_from_path:
+                        if param in path_params:
+                            business_context[param] = path_params[param]
+
+                return {
+                    "event_type": event_config.event_type,
+                    "business_context": business_context,
+                }
+
+        return None
+
+    def _matches_endpoint_pattern(self, endpoint: str, pattern: str) -> bool:
+        """
+        Check if an endpoint matches a pattern.
+
+        Supports exact matches and path parameter patterns like /folders/{folder_id}
+        """
+        # Extract method and path
+        endpoint_parts = endpoint.split(" ", 1)
+        pattern_parts = pattern.split(" ", 1)
+
+        if len(endpoint_parts) != 2 or len(pattern_parts) != 2:
+            return False
+
+        endpoint_method, endpoint_path = endpoint_parts
+        pattern_method, pattern_path = pattern_parts
+
+        # Method must match exactly
+        if endpoint_method != pattern_method:
+            return False
+
+        # Convert pattern to regex (handle {param} placeholders)
+        pattern_regex = re.sub(r"\{[^}]+\}", r"[^/]+", pattern_path)
+        pattern_regex = f"^{pattern_regex}$"
+
+        return bool(re.match(pattern_regex, endpoint_path))
+
+    def _extract_path_params(self, path: str, pattern: str) -> Dict[str, str]:
+        """
+        Extract path parameters from a path based on a pattern.
+
+        Example:
+            path = "/folders/123"
+            pattern = "DELETE /folders/{folder_id}"
+            returns {"folder_id": "123"}
+        """
+        # Extract just the path part from pattern
+        pattern_path = pattern.split(" ", 1)[1] if " " in pattern else pattern
+
+        # Find parameter names in pattern
+        param_names = re.findall(r"\{([^}]+)\}", pattern_path)
+
+        if not param_names:
+            return {}
+
+        # Convert pattern to regex with capture groups
+        pattern_regex = re.sub(r"\{[^}]+\}", r"([^/]+)", pattern_path)
+        pattern_regex = f"^{pattern_regex}$"
+
+        # Match and extract values
+        match = re.match(pattern_regex, path)
+        if not match:
+            return {}
+
+        # Build dict of param_name -> value
+        return dict(zip(param_names, match.groups()))

auditry/models.py

@@ -0,0 +1,71 @@
+from typing import Optional, Dict, List
+from pydantic import BaseModel, Field, field_validator
+
+
+class BusinessEventConfig(BaseModel):
+    """
+    Configuration for a business event to track.
+
+    Defines what event type to tag and what fields to extract for analytics.
+    """
+
+    event_type: str = Field(
+        description="Business event type (e.g., 'folder.created', 'file.uploaded')"
+    )
+    extract_from_request: Optional[List[str]] = Field(
+        default=None,
+        description="Field names to extract from request body for business context"
+    )
+    extract_from_response: Optional[List[str]] = Field(
+        default=None,
+        description="Field names to extract from response body for business context"
+    )
+    extract_from_path: Optional[List[str]] = Field(
+        default=None,
+        description="Path parameter names to extract (e.g., ['folder_id'] for /folders/{folder_id})"
+    )
+
+
+class ObservabilityConfig(BaseModel):
+    """
+    Configuration options for observability logging behavior.
+
+    Allows services to customize logging behavior including payload
+    size limits, redaction patterns, and verbosity.
+    """
+
+    service_name: str = Field(
+        min_length=1,
+        description="Name of the service for logging context (e.g., 'vault-api', 'auth-service')"
+    )
+    correlation_id_header: str = Field(
+        default="X-Correlation-ID",
+        description="HTTP header name for correlation ID (default: X-Correlation-ID)",
+    )
+
+    @field_validator("service_name")
+    @classmethod
+    def validate_service_name(cls, v: str) -> str:
+        """Validate service name is not empty or whitespace."""
+        if not v or not v.strip():
+            raise ValueError("service_name cannot be empty or whitespace")
+        return v.strip()
+    business_events: Optional[Dict[str, BusinessEventConfig]] = Field(
+        default=None,
+        description="Map of endpoint patterns to business event configurations for analytics tracking"
+    )
+    payload_size_limit: int = Field(
+        default=10_240,
+        description="Maximum size in bytes for logged request/response bodies (default 10KB)",
+    )
+    additional_redaction_patterns: Optional[list[str]] = Field(
+        default=None,
+        description="Additional field name patterns to redact beyond defaults",
+    )
+    log_request_headers: bool = Field(
+        default=True, description="Whether to log request headers (redacted)"
+    )
+    log_response_headers: bool = Field(
+        default=False, description="Whether to log response headers (redacted)"
+    )
+    log_query_params: bool = Field(default=True, description="Whether to log query parameters")

auditry/redaction.py

@@ -0,0 +1,144 @@
+from typing import Any, Dict, List, Set
+
+
+DEFAULT_REDACTION_PATTERNS: List[str] = [
+    "password",
+    "token",
+    "api_key",
+    "apikey",
+    "secret",
+    "ssn",
+    "social_security_number",
+    "credit_card",
+    "creditcard",
+    "authorization",
+    "x-api-key",
+]
+
+REDACTED_VALUE = "[REDACTED]"
+
+
+class SensitiveDataRedactor:
+    """
+    Redacts sensitive data from dictionaries and JSON-serializable objects.
+
+    Uses field name pattern matching to identify and replace sensitive
+    values with a redaction marker. Supports nested dictionaries and lists.
+    """
+
+    def __init__(self, additional_patterns: List[str] = None):
+        """
+        Initialize redactor with field patterns to redact.
+
+        Args:
+            additional_patterns: Additional field name patterns beyond defaults
+        """
+        self.patterns: Set[str] = set(pattern.lower() for pattern in DEFAULT_REDACTION_PATTERNS)
+        if additional_patterns:
+            self.patterns.update(pattern.lower() for pattern in additional_patterns)
+
+    def should_redact(self, field_name: str) -> bool:
+        """
+        Determine if a field should be redacted based on its name.
+
+        Performs case-insensitive matching against known sensitive
+        field patterns.
+
+        Args:
+            field_name: Name of the field to check
+
+        Returns:
+            True if field should be redacted, False otherwise
+        """
+        field_lower = field_name.lower()
+        # Exact match
+        if field_lower in self.patterns:
+            return True
+        # Partial match (e.g., "user_password" matches "password")
+        return any(pattern in field_lower for pattern in self.patterns)
+
+    def redact(self, data: Any) -> Any:
+        """
+        Recursively redact sensitive data from a data structure.
+
+        Handles dictionaries, lists, and primitive types. Creates a new
+        structure with sensitive values replaced, leaving original unchanged.
+
+        Args:
+            data: Data structure to redact (dict, list, or primitive)
+
+        Returns:
+            New data structure with sensitive values redacted
+        """
+        if isinstance(data, dict):
+            return self._redact_dict(data)
+        elif isinstance(data, list):
+            return self._redact_list(data)
+        else:
+            # Primitive type, return as-is
+            return data
+
+    def _redact_dict(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Redact sensitive fields in a dictionary.
+
+        Creates new dictionary with sensitive field values replaced
+        with redaction marker. Recursively processes nested structures.
+        """
+        redacted = {}
+        for key, value in data.items():
+            if self.should_redact(key):
+                redacted[key] = REDACTED_VALUE
+            elif isinstance(value, dict):
+                redacted[key] = self._redact_dict(value)
+            elif isinstance(value, list):
+                redacted[key] = self._redact_list(value)
+            else:
+                redacted[key] = value
+        return redacted
+
+    def _redact_list(self, data: List[Any]) -> List[Any]:
+        """
+        Redact sensitive data in a list.
+
+        Recursively processes each list element, handling nested
+        dictionaries and lists.
+        """
+        return [self.redact(item) for item in data]
+
+
+_default_redactor = SensitiveDataRedactor()
+
+
+def redact_headers(headers: Dict[str, str]) -> Dict[str, str]:
+    """
+    Redact sensitive headers for logging.
+
+    Specifically handles common authentication and API key headers
+    that should never appear in logs.
+
+    Args:
+        headers: Dictionary of HTTP headers
+
+    Returns:
+        New dictionary with sensitive headers redacted
+    """
+    return _default_redactor.redact(headers)
+
+
+def redact_data(data: Any, additional_patterns: List[str] = None) -> Any:
+    """
+    Convenience function to redact sensitive data.
+
+    Args:
+        data: Data structure to redact
+        additional_patterns: Optional additional field patterns to redact
+
+    Returns:
+        Redacted copy of the data
+    """
+    if additional_patterns:
+        # Only create new instance if custom patterns are needed
+        redactor = SensitiveDataRedactor(additional_patterns)
+        return redactor.redact(data)
+    return _default_redactor.redact(data)

auditry/unified_middleware.py

@@ -0,0 +1,74 @@
+"""
+Unified observability middleware that handles both correlation IDs and request/response logging.
+
+This middleware combines correlation ID management and comprehensive logging into a single,
+easy-to-use middleware that requires minimal configuration.
+"""
+
+from typing import Optional
+
+from asgi_correlation_id import CorrelationIdMiddleware as BaseCorrelationIdMiddleware
+from starlette.applications import Starlette
+
+from .middleware import RequestResponseLoggingMiddleware
+from .models import ObservabilityConfig
+
+
+class ObservabilityMiddleware:
+    """
+    Unified middleware for comprehensive observability.
+
+    Combines correlation ID management and request/response logging into a single
+    middleware that's easy to configure. Automatically handles proper ordering
+    of sub-middlewares.
+
+    Example:
+        app = FastAPI()
+        app.add_middleware(
+            ObservabilityMiddleware,
+            config=ObservabilityConfig(service_name="vault-api")
+        )
+    """
+
+    def __init__(
+        self,
+        app: Starlette,
+        config: Optional[ObservabilityConfig] = None,
+    ):
+        """
+        Initialize the unified observability middleware.
+
+        Args:
+            app: FastAPI/Starlette application instance
+            config: Observability configuration with service name and options
+        """
+        if config is None:
+            raise ValueError(
+                "ObservabilityConfig is required"
+            )
+
+        self.app = app
+        self.config = config
+
+        # Wrap the app with sub-middlewares in the correct order
+        # Order matters: Correlation ID must be set first, then logging can use it
+
+        # 1. First, wrap with logging middleware
+        logging_app = RequestResponseLoggingMiddleware(app, config=config)
+
+        # 2. Then wrap with correlation ID middleware
+        # This ensures correlation ID is available to the logging middleware
+        correlation_app = BaseCorrelationIdMiddleware(
+            logging_app.app,
+            header_name=config.correlation_id_header,
+        )
+
+        self.wrapped_app = correlation_app
+
+    async def __call__(self, scope, receive, send):
+        """
+        ASGI application interface.
+
+        Delegates to the wrapped middleware stack.
+        """
+        await self.wrapped_app(scope, receive, send)

auditry-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Liv Stark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

auditry-0.1.0.dist-info/METADATA

@@ -0,0 +1,392 @@
+Metadata-Version: 2.1
+Name: auditry
+Version: 0.1.0
+Summary: FastAPI middleware for request/response logging, correlation IDs, and sensitive data redaction
+Author-email: Liv Stark <livstark.work@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/lst4rk/auditry
+Project-URL: Repository, https://github.com/lst4rk/auditry
+Project-URL: Issues, https://github.com/lst4rk/auditry/issues
+Keywords: fastapi,observability,logging,middleware,correlation-id,redaction
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: structlog>=23.0.0
+Requires-Dist: asgi-correlation-id>=4.0.0
+
+# auditry
+
+FastAPI observability middleware with automatic request/response logging, correlation IDs, and sensitive data redaction.
+
+[![PyPI version](https://badge.fury.io/py/auditry.svg)](https://badge.fury.io/py/auditry)
+[![Python Versions](https://img.shields.io/pypi/pyversions/auditry.svg)](https://pypi.org/project/auditry/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install auditry
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from auditry import configure_logging, ObservabilityMiddleware, ObservabilityConfig
+from auditry import get_logger
+
+# Configure structured logging at startup
+configure_logging(level="INFO")
+
+app = FastAPI()
+
+# Add observability middleware (single line!)
+app.add_middleware(
+    ObservabilityMiddleware,
+    config=ObservabilityConfig(
+        service_name="my-service-name",
+    ),
+)
+
+logger = get_logger(__name__) # always use the get_logger from this package
+
+@app.get("/")
+async def root():
+   
+    logger.info("Hello World")
+
+    return {"message": "Hello World"}
+```
+
+## Configuration
+
+### Required Configuration
+
+```python
+config = ObservabilityConfig(
+    service_name="your-service-name",  # REQUIRED
+)
+```
+
+### Full Configuration Options
+
+```python
+config = ObservabilityConfig(
+    # REQUIRED: Service name for log filtering
+    service_name="my-service-name",
+
+    # Correlation ID header name (default: X-Correlation-ID)
+    # Use this if your org uses a different header, such as X-Request-ID
+    correlation_id_header="X-Correlation-ID",
+
+    # Maximum request/response body size to log (default: 10KB)
+    payload_size_limit=10_240,
+
+    # Additional sensitive field patterns to redact
+    additional_redaction_patterns=["internal_id", "employee_ssn"],
+
+    # Whether to log request headers (default: True)
+    log_request_headers=True,
+
+    # Whether to log response headers (default: False)
+    log_response_headers=False,
+
+    # Whether to log query parameters (default: True)
+    log_query_params=True,
+)
+
+app.add_middleware(ObservabilityMiddleware, config=config)
+```
+
+## Correlation IDs
+
+Correlation IDs are automatically handled:
+
+- **Incoming requests**: Extracts from `X-Correlation-ID` header (or your custom header)
+- **Generated if missing**: Creates a new UUID if no correlation ID provided
+- **Added to response**: Returns the correlation ID in the response header
+- **Included in logs**: Automatically included in all structured logs
+
+### Using Correlation IDs in Your Code
+
+```python
+from auditry import get_logger, get_correlation_id
+
+logger = get_logger(__name__)
+
+@app.get("/users/{user_id}")
+async def get_user(user_id: str):
+    # Correlation ID is automatically available
+    correlation_id = get_correlation_id()
+
+    # All logs automatically include the correlation ID
+    logger.info(f"Fetching user {user_id}")
+
+    return {"user_id": user_id, "correlation_id": correlation_id}
+```
+
+### Propagating to Downstream Services
+
+```python
+import httpx
+from auditry import get_correlation_id
+
+@app.get("/proxy")
+async def proxy_request():
+    # Get the current correlation ID
+    correlation_id = get_correlation_id()
+
+    # Pass it to downstream services
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            "https://downstream-service.com/api/data",
+            headers={"X-Correlation-ID": correlation_id}  # Use your org's header name
+        )
+
+    return response.json()
+```
+
+## User Tracking
+
+The middleware automatically extracts user IDs from FastAPI dependencies and includes them in logs.
+
+### Supported User Patterns
+
+The middleware automatically detects user IDs from these patterns:
+
+1. **Object with `id` attribute**: `current_user.id`
+2. **Object with `user_id` attribute**: `current_user.user_id`
+3. **Dict with `id` key**: `user["id"]`
+4. **Dict with `user_id` key**: `user["user_id"]`
+5. **Dict with `sub` key**: `user["sub"]` (JWT standard)
+6. **Request state**: `request.state.user_id`
+
+**You don't need to modify any existing code** - the middleware automatically finds the user ID!
+
+## Business Event Tagging (For Analytics)
+
+Tag specific endpoints as "business events" to make analytics queries easier for your sales/product teams.
+
+### Configuration
+
+Tag endpoints in your middleware config - zero code changes needed in your actual endpoints:
+
+```python
+from auditry import ObservabilityMiddleware, ObservabilityConfig, BusinessEventConfig
+
+app.add_middleware(
+    ObservabilityMiddleware,
+    config=ObservabilityConfig(
+        service_name="my-service-name",
+        
+        # Define which endpoints to tag for analytics
+        business_events={
+            "POST /workflows": BusinessEventConfig(
+                event_type="workflow.created",
+                extract_from_request=["file_id"],  # Pull file_id from request body
+                extract_from_response=["id"],       # Pull workflow id from response
+            ),
+            "DELETE /workflows/{workflow_id}": BusinessEventConfig(
+                event_type="workflow.deleted",
+                extract_from_path=["workflow_id"],    # Pull workflow_id from URL path
+            ),
+        },
+    ),
+)
+```
+
+### Log Output with Event Tags
+
+Regular log (no tagging):
+```json
+{
+  "service": "my-service-name",
+  "message": "Request completed: POST /workflows - Status: 201",
+  "request": {...},
+  "response": {...}
+}
+```
+
+Tagged business event log:
+```json
+{
+  "service": "my-service-name",
+  "message": "Request completed: POST /workflows - Status: 201",
+  "event_type": "workflow.created",          // ← Filterable in log platform
+  "business_context": {
+    "file_id": "file_123",                   // ← From request body
+    "id": "workflow_789"                    // ← From response body
+  },
+  "request": {...},
+  "response": {...}
+}
+```
+
+### Supported Extract Locations
+
+- `extract_from_request`: Fields from request JSON body
+- `extract_from_response`: Fields from response JSON body  
+- `extract_from_path`: Parameters from URL path (e.g., `/workflows/{workflow_id}`)
+
+## Log Output
+
+All logs are structured JSON, ready for log aggregators:
+
+```json
+{
+  "timestamp": "2025-10-28T12:34:56.789012+00:00",
+  "level": "INFO",
+  "service": "my-service-name",
+  "correlation_id": "550e8400-e29b-41d4-a716-446655440000",
+  "message": "Request completed: POST /workflows - Status: 201 - Duration: 45.23ms",
+  "request": {
+    "method": "POST",
+    "path": "/workflows",
+    "query_params": {},
+    "headers": {"user-agent": "curl/7.64.1", "authorization": "[REDACTED]"},
+    "body": {"name": "My Workflow", "password": "[REDACTED]"},
+    "user_id": "user_12345"
+  },
+  "response": {
+    "status_code": 201,
+    "duration_ms": 45.23,
+    "body": {"id": "workflow_789", "name": "My Workflow"}
+  }
+}
+```
+
+## Sensitive Data Redaction
+
+Automatically redacts these sensitive field patterns:
+
+- `password`
+- `token`
+- `api_key` / `apikey`
+- `secret`
+- `authorization`
+- `ssn` / `social_security_number`
+- `credit_card` / `creditcard`
+- `x-api-key`
+
+Add custom patterns via configuration:
+
+```python
+config = ObservabilityConfig(
+    service_name="my-service-name",
+    additional_redaction_patterns=["internal_token", "employee_id"],
+)
+```
+## Best Practices
+
+### 1. Configure Logging Early
+
+Call `configure_logging()` at application startup, before any other code:
+
+```python
+from auditry import configure_logging
+
+# First thing in your app
+configure_logging(level="INFO")
+
+app = FastAPI()
+# ... rest of your app
+```
+
+### 2. Use Structured Logging
+
+Always use `get_logger(__name__)` instead of standard Python logging:
+
+```python
+from auditry import get_logger
+
+logger = get_logger(__name__)
+
+# Good - structured with correlation ID
+logger.info("Processing payment", amount=100.50, currency="USD")
+
+# Bad - loses structured data
+import logging
+logging.info("Processing payment")
+```
+
+### 3. Propagate Correlation IDs
+
+When calling downstream services, always pass the correlation ID:
+
+```python
+from auditry import get_correlation_id
+
+correlation_id = get_correlation_id()
+headers = {"X-Correlation-ID": correlation_id}  # Use your org's header name
+response = await client.get(url, headers=headers)
+```
+
+### 4. Customize for Your Organization
+
+Match your org's conventions:
+
+```python
+config = ObservabilityConfig(
+    service_name="my-service-name",
+    correlation_id_header="X-Request-ID",  # If your org uses this header instead
+    additional_redaction_patterns=["ssn", "tax_id"],  # Your sensitive fields
+)
+```
+
+## Example Output: Success vs Failure
+
+### Successful Request
+
+```json
+{
+  "level": "INFO",
+  "service": "my-service-name",
+  "correlation_id": "abc-123",
+  "message": "Request completed: POST /workflows - Status: 201 - Duration: 45ms",
+  "request": {...},
+  "response": {...}
+}
+```
+
+### Failed Request
+
+```json
+{
+  "level": "ERROR",
+  "service": "my-service-name",
+  "correlation_id": "abc-123",
+  "message": "Request failed: POST /workflows - Error: ValueError: Invalid name",
+  "request": {...},
+  "exception_type": "ValueError",
+  "exception_message": "Invalid name",
+  "execution_duration_ms": 12.34
+}
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions welcome! Please submit a Pull Request.
+
+## Support
+
+For issues and questions: [GitHub Issues](https://github.com/lst4rk/auditry/issues)
+
+## Author
+
+**Liv Stark** - [livstark.work@gmail.com](mailto:livstark.work@gmail.com)

auditry-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+auditry/__init__.py,sha256=dOYQFaeKndof_cmHVBKMwRIW6Fviu4IBRWSHsVg5AD0,491
+auditry/correlation.py,sha256=NHBWtxkRa155a9iEMZy6hjrOE_GDatIkt53HkXwST74,457
+auditry/logging_config.py,sha256=jQ05tPBhoBGAL-4Z3MdQf-gbU0vZZrVq90waYiE-9Qo,1859
+auditry/middleware.py,sha256=F1f1Nrsvf4Tp5028Pq0v9z4hXUqyVtut2Qm2nvpvAMY,13081
+auditry/models.py,sha256=GRjgvfzNb0_X3aaqf-BGcYf6xTezgiR0zC3aaso1Ksk,2666
+auditry/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auditry/redaction.py,sha256=otD1qAFVb7_S-wITWfmMEjNP75Bc5DydiCiw9Ppgcp0,4344
+auditry/unified_middleware.py,sha256=FDtqpKqke8IJFb63LAklWI4yhgg70cHgikuBWov0eFw,2324
+auditry-0.1.0.dist-info/LICENSE,sha256=tYlACwTkk8vCn2Q5wpldpGI17PmyRYy48Ssa_zKN0Ow,1065
+auditry-0.1.0.dist-info/METADATA,sha256=hx6LsWn-zDxLT201ToVp_eECmwq3rmWVcvajcjSuJhQ,10643
+auditry-0.1.0.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+auditry-0.1.0.dist-info/top_level.txt,sha256=ZsUpu_j54GA1Cj1nsfiMm5Ino9h_Gv4F9QTVbGspIp8,8
+auditry-0.1.0.dist-info/RECORD,,

auditry-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.45.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

auditry-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+auditry