setu-trafficmonitor 2.0.0__py3-none-any.whl

trafficmonitor/middleware.py

@@ -0,0 +1,383 @@
+import json
+import logging
+import time
+import traceback
+import random
+from io import BytesIO
+from threading import local
+from contextlib import contextmanager
+
+from django.db import connection, transaction
+from django.utils.deprecation import MiddlewareMixin
+from django.core.cache import cache
+
+from trafficmonitor.models import RequestLog
+from trafficmonitor.conf import TrafficMonitorConfig
+from trafficmonitor.circuit_breaker import CircuitBreaker
+
+logger = logging.getLogger(__name__)
+
+# Thread-local storage for request context
+_local = local()
+
+
+class RequestLoggingMiddleware(MiddlewareMixin):
+    """
+    Enterprise-grade middleware for HTTP request logging.
+    Features: Circuit breaker, async logging, PII sanitization, metrics collection.
+    """
+    
+    EXCLUDED_PATHS = [
+        '/admin/jsi18n/',
+        '/static/',
+        '/media/',
+        '/__debug__/',
+        '/favicon.ico',
+        '/health/',
+    ]
+
+    def __init__(self, get_response):
+        super().__init__(get_response)
+        self.circuit_breaker = CircuitBreaker() if TrafficMonitorConfig.CIRCUIT_BREAKER_ENABLED else None
+        
+    def process_request(self, request):
+        """Initialize request tracking"""
+        request._logging_start_time = time.time()
+        request._logging_query_count_start = len(connection.queries)
+        return None
+
+    def process_response(self, request, response):
+        """Log request with enterprise features"""
+        try:
+            # Skip excluded paths
+            if self._should_exclude_path(request.path):
+                return response
+            
+            # Apply sampling
+            if TrafficMonitorConfig.ENABLE_SAMPLING and random.random() > TrafficMonitorConfig.SAMPLE_RATE:
+                return response
+            
+            # Collect metrics
+            if TrafficMonitorConfig.ENABLE_METRICS:
+                self._collect_metrics(request, response)
+            
+            # Log request
+            if self.circuit_breaker:
+                self.circuit_breaker.call(self._log_request_safe, request, response)
+            else:
+                self._log_request_safe(request, response)
+                
+        except Exception as e:
+            # Never let logging break the request
+            logger.error(f"Request logging failed: {e}", exc_info=True)
+        
+        return response
+    
+    def _log_request_safe(self, request, response):
+        """Safely log request with error handling"""
+        from trafficmonitor.security import DataSanitizer, SecurityValidator
+        from trafficmonitor.monitoring import performance_timer
+        
+        with performance_timer("request_logging_duration"):
+            log_data = self._build_log_data(request, response)
+            
+            if TrafficMonitorConfig.ASYNC_LOGGING:
+                self._log_async(log_data)
+            else:
+                self._log_sync(log_data)
+    
+    def _build_log_data(self, request, response):
+        """Build sanitized log data"""
+        from trafficmonitor.security import DataSanitizer, SecurityValidator
+        
+        # Calculate metrics
+        duration_ms = (time.time() - request._logging_start_time) * 1000
+        query_count = len(connection.queries) - request._logging_query_count_start
+        
+        # Get user info
+        user_info = TrafficMonitorConfig.get_user_info_from_request(request)
+        
+        # Sanitize data
+        headers = DataSanitizer.sanitize_headers(dict(request.META))
+        body = self._get_request_body(request)
+        if TrafficMonitorConfig.ENABLE_PII_SANITIZATION:
+            body = DataSanitizer.sanitize_body(body, TrafficMonitorConfig.MAX_BODY_LENGTH)
+        
+        return {
+            'method': request.method,
+            'path': request.path,
+            'full_url': request.build_absolute_uri(),
+            'status_code': response.status_code,
+            'requested_user_id': user_info.get('user_id'),
+            'ip_address': SecurityValidator.get_client_ip(request),
+            'user_agent': request.META.get('HTTP_USER_AGENT', ''),
+            'request_headers': headers,
+            'request_body': body,
+            'operation_type': RequestLog.get_operation_type(request.method),
+            'endpoint_category': RequestLog.extract_endpoint_category(request.path),
+            'is_api_request': request.path.startswith('/api/'),
+            'response_time_ms': duration_ms,
+            'query_count': query_count,
+            'content_length': len(response.content) if hasattr(response, 'content') else None,
+        }
+    
+    def _collect_metrics(self, request, response):
+        """Collect application metrics"""
+        from trafficmonitor.monitoring import metrics
+        
+        tags = {
+            'method': request.method,
+            'status_code': str(response.status_code),
+            'endpoint': request.path[:50]  # Truncate long paths
+        }
+        
+        metrics.increment('requests_total', tags=tags)
+        
+        if response.status_code >= 400:
+            metrics.increment('requests_errors', tags=tags)
+        
+        if response.status_code >= 500:
+            metrics.increment('requests_server_errors', tags=tags)
+    
+    def _log_async(self, log_data):
+        """Log asynchronously using Celery"""
+        try:
+            from trafficmonitor.tasks import log_request_async
+            log_request_async.delay(log_data)
+        except ImportError:
+            logger.warning("Celery not available, falling back to sync logging")
+            self._log_sync(log_data)
+    
+    def _log_sync(self, log_data):
+        """Log synchronously"""
+        try:
+            RequestLog.objects.create(**log_data)
+        except Exception as e:
+            logger.error(f"Failed to create RequestLog: {e}", exc_info=True)
+    
+    def _should_exclude_path(self, path):
+        """Check if path should be excluded from logging"""
+        return any(excluded in path for excluded in TrafficMonitorConfig.EXCLUDED_PATHS)
+    
+    def _get_request_body(self, request):
+        """Safely get request body"""
+        try:
+            if hasattr(request, '_body'):
+                return request._body.decode('utf-8')
+            elif hasattr(request, 'body'):
+                return request.body.decode('utf-8')
+        except (UnicodeDecodeError, AttributeError):
+            pass
+        return ""
+
+        try:
+            # Calculate response time
+            response_time_ms = None
+            if hasattr(request, '_logging_start_time'):
+                response_time_ms = (time.time() - request._logging_start_time) * 1000
+
+            # Calculate query count
+            query_count = None
+            if hasattr(request, '_logging_query_count_start'):
+                query_count = len(connection.queries) - request._logging_query_count_start
+
+            # Extract request data
+            request_headers = self._get_request_headers(request)
+            request_body = self._get_request_body(request)
+
+            # Get user ID from header (X-User-ID)
+            requested_user_id = request.META.get('HTTP_X_USER_ID') or request.headers.get('X-User-ID')
+
+            # Get IP address
+            ip_address = self._get_client_ip(request)
+            
+            # Determine operation type and endpoint category
+            operation_type = RequestLog.get_operation_type(request.method)
+            endpoint_category = RequestLog.extract_endpoint_category(request.path)
+            is_api_request = request.path.startswith('/api/')
+
+            # Prepare log data
+            log_data = {
+                'method': request.method,
+                'path': request.path,
+                'full_url': request.build_absolute_uri(),
+                'status_code': response.status_code,
+                'requested_user_id': requested_user_id,
+                'ip_address': ip_address,
+                'user_agent': request.META.get('HTTP_USER_AGENT', ''),
+                'request_headers': request_headers,
+                'request_body': request_body,
+                'operation_type': operation_type,
+                'endpoint_category': endpoint_category,
+                'is_api_request': is_api_request,
+                'response_time_ms': response_time_ms,
+                'query_count': query_count,
+                'content_length': len(response.content) if hasattr(response, 'content') else None,
+            }
+            
+            # Log asynchronously or synchronously based on config
+            if TrafficMonitorConfig.ASYNC_LOGGING:
+                self._log_async(log_data)
+            else:
+                RequestLog.objects.create(**log_data)
+
+        except Exception as e:
+            # Log the error but don't break the request/response cycle
+            logger.error(f"Error logging request: {str(e)}", exc_info=True)
+
+        return response
+
+    def process_exception(self, request, exception):
+        """
+        Called when a view raises an exception.
+        Logs the exception details.
+        """
+        # Skip logging for excluded paths
+        if self._should_exclude_path(request.path):
+            return None
+
+        try:
+            # Calculate response time
+            response_time_ms = None
+            if hasattr(request, '_logging_start_time'):
+                response_time_ms = (time.time() - request._logging_start_time) * 1000
+
+            # Calculate query count
+            query_count = None
+            if hasattr(request, '_logging_query_count_start'):
+                query_count = len(connection.queries) - request._logging_query_count_start
+
+            # Extract request data
+            request_headers = self._get_request_headers(request)
+            request_body = self._get_request_body(request)
+
+            # Get user ID from header
+            requested_user_id = request.META.get('HTTP_X_USER_ID') or request.headers.get('X-User-ID')
+
+            # Get IP address
+            ip_address = self._get_client_ip(request)
+            
+            # Determine operation type and endpoint category
+            operation_type = RequestLog.get_operation_type(request.method)
+            endpoint_category = RequestLog.extract_endpoint_category(request.path)
+            is_api_request = request.path.startswith('/api/')
+
+            # Get exception traceback
+            exception_traceback = ''.join(traceback.format_exception(
+                type(exception), exception, exception.__traceback__
+            ))
+
+            # Prepare log data with exception
+            log_data = {
+                'method': request.method,
+                'path': request.path,
+                'full_url': request.build_absolute_uri(),
+                'status_code': 500,  # Internal Server Error
+                'requested_user_id': requested_user_id,
+                'ip_address': ip_address,
+                'user_agent': request.META.get('HTTP_USER_AGENT', ''),
+                'request_headers': request_headers,
+                'request_body': request_body,
+                'operation_type': operation_type,
+                'endpoint_category': endpoint_category,
+                'is_api_request': is_api_request,
+                'response_time_ms': response_time_ms,
+                'query_count': query_count,
+                'exception': exception_traceback,
+            }
+            
+            # Log asynchronously or synchronously
+            if TrafficMonitorConfig.ASYNC_LOGGING:
+                self._log_async(log_data)
+            else:
+                RequestLog.objects.create(**log_data)
+
+        except Exception as e:
+            # Log the error but don't break the request/response cycle
+            logger.error(f"Error logging exception: {str(e)}", exc_info=True)
+
+        return None
+
+    def _should_exclude_path(self, path):
+        """
+        Check if the request path should be excluded from logging.
+        """
+        for excluded_path in self.EXCLUDED_PATHS:
+            if path.startswith(excluded_path):
+                return True
+        return False
+    
+    def _log_async(self, log_data):
+        """
+        Log request data asynchronously using Celery.
+        Falls back to synchronous logging if Celery is unavailable.
+        """
+        try:
+            from trafficmonitor.tasks import log_request_async
+            log_request_async.delay(log_data)
+        except Exception as e:
+            logger.warning(f"Async logging failed, falling back to sync: {e}")
+            RequestLog.objects.create(**log_data)
+
+    def _get_request_body(self, request):
+        """
+        Extract and return the request body.
+        Handles both JSON and form data.
+        """
+        try:
+            if request.method in ['POST', 'PUT', 'PATCH']:
+                # Try to get JSON body
+                if request.content_type and 'application/json' in request.content_type:
+                    body = request.body.decode('utf-8')
+                    # Truncate if too long
+                    if len(body) > self.MAX_BODY_LENGTH:
+                        body = body[:self.MAX_BODY_LENGTH] + '... [truncated]'
+                    return body
+                # For form data, log the POST data
+                elif request.POST:
+                    body = json.dumps(dict(request.POST))
+                    if len(body) > self.MAX_BODY_LENGTH:
+                        body = body[:self.MAX_BODY_LENGTH] + '... [truncated]'
+                    return body
+        except Exception as e:
+            logger.debug(f"Error extracting request body: {str(e)}")
+
+        return None
+
+    def _get_request_headers(self, request):
+        """
+        Extract and return request headers as a dictionary.
+        Filters out sensitive headers and ensures JSON serializable values.
+        """
+        sensitive_headers = [
+            'HTTP_AUTHORIZATION',
+            'HTTP_COOKIE',
+            'HTTP_X_CSRFTOKEN',
+        ]
+
+        headers = {}
+        for key, value in request.META.items():
+            if key.startswith('HTTP_') and key not in sensitive_headers:
+                # Remove HTTP_ prefix and convert to title case
+                header_name = key[5:].replace('_', '-').title()
+                # Ensure value is JSON serializable
+                try:
+                    headers[header_name] = str(value)
+                except:
+                    headers[header_name] = '<non-serializable>'
+
+        return headers
+
+    def _get_client_ip(self, request):
+        """
+        Extract and return the client's IP address.
+        Handles X-Forwarded-For header for proxied requests.
+        """
+        x_forwarded_for = request.META.get('HTTP_X_FORWARDED_FOR')
+        if x_forwarded_for:
+            # Get the first IP in the chain
+            ip = x_forwarded_for.split(',')[0].strip()
+        else:
+            ip = request.META.get('REMOTE_ADDR')
+
+        return ip

trafficmonitor/migrations/0001_initial.py

@@ -0,0 +1,93 @@
+# Generated by Django 3.2.10 on 2025-12-22 10:52
+
+import django.core.serializers.json
+from django.db import migrations, models
+import uuid
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='RequestLog',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('method', models.CharField(db_index=True, help_text='HTTP method (GET, POST, etc.)', max_length=10)),
+                ('path', models.CharField(db_index=True, help_text='Request path/URL', max_length=2048)),
+                ('full_url', models.TextField(help_text='Complete URL including query parameters')),
+                ('status_code', models.IntegerField(db_index=True, help_text='HTTP response status code')),
+                ('requested_user_id', models.CharField(blank=True, db_index=True, help_text='User ID from request header (X-User-ID)', max_length=255, null=True)),
+                ('ip_address', models.GenericIPAddressField(blank=True, db_index=True, help_text='Client IP address', null=True)),
+                ('user_agent', models.TextField(blank=True, help_text='User agent string from request headers', null=True)),
+                ('request_headers', models.JSONField(blank=True, encoder=django.core.serializers.json.DjangoJSONEncoder, help_text='Request headers as JSON (sensitive headers excluded)', null=True)),
+                ('request_body', models.TextField(blank=True, help_text='Request body content (truncated for large payloads)', null=True)),
+                ('operation_type', models.CharField(blank=True, choices=[('READ', 'Read Operation'), ('WRITE', 'Write Operation'), ('DELETE', 'Delete Operation')], db_index=True, help_text='Operation type: READ (GET, HEAD, OPTIONS), WRITE (POST, PUT, PATCH), DELETE', max_length=10, null=True)),
+                ('endpoint_category', models.CharField(blank=True, db_index=True, help_text='Endpoint category extracted from path (e.g., /api/users -> users)', max_length=100, null=True)),
+                ('is_api_request', models.BooleanField(db_index=True, default=False, help_text='Whether this is an API request (starts with /api/)')),
+                ('response_time_ms', models.FloatField(blank=True, db_index=True, help_text='Response time in milliseconds', null=True)),
+                ('query_count', models.IntegerField(blank=True, help_text='Number of database queries executed', null=True)),
+                ('exception', models.TextField(blank=True, help_text='Exception traceback if request failed', null=True)),
+                ('content_length', models.IntegerField(blank=True, help_text='Response content length in bytes', null=True)),
+                ('timestamp', models.DateTimeField(auto_now_add=True, db_index=True)),
+            ],
+            options={
+                'verbose_name': 'Request Log',
+                'verbose_name_plural': 'Request Logs',
+                'db_table': 'request_log',
+                'ordering': ['-timestamp'],
+            },
+        ),
+        migrations.AddIndex(
+            model_name='requestlog',
+            index=models.Index(fields=['-timestamp', 'status_code'], name='idx_timestamp_status'),
+        ),
+        migrations.AddIndex(
+            model_name='requestlog',
+            index=models.Index(fields=['requested_user_id', '-timestamp'], name='idx_user_timestamp'),
+        ),
+        migrations.AddIndex(
+            model_name='requestlog',
+            index=models.Index(fields=['path', '-timestamp'], name='idx_path_timestamp'),
+        ),
+        migrations.AddIndex(
+            model_name='requestlog',
+            index=models.Index(fields=['operation_type', '-timestamp'], name='idx_operation_timestamp'),
+        ),
+        migrations.AddIndex(
+            model_name='requestlog',
+            index=models.Index(fields=['endpoint_category', '-timestamp'], name='idx_category_timestamp'),
+        ),
+        migrations.AddIndex(
+            model_name='requestlog',
+            index=models.Index(fields=['is_api_request', 'status_code', '-timestamp'], name='idx_api_status_timestamp'),
+        ),
+        migrations.AddIndex(
+            model_name='requestlog',
+            index=models.Index(fields=['method', 'status_code', '-timestamp'], name='idx_method_status_timestamp'),
+        ),
+        migrations.AddIndex(
+            model_name='requestlog',
+            index=models.Index(fields=['response_time_ms', '-timestamp'], name='idx_response_time'),
+        ),
+        migrations.AddIndex(
+            model_name='requestlog',
+            index=models.Index(fields=['query_count', '-timestamp'], name='idx_query_count'),
+        ),
+        migrations.AddIndex(
+            model_name='requestlog',
+            index=models.Index(condition=models.Q(('status_code__gte', 400)), fields=['status_code', '-timestamp'], name='idx_errors_only'),
+        ),
+        migrations.AddConstraint(
+            model_name='requestlog',
+            constraint=models.CheckConstraint(check=models.Q(('status_code__gte', 100), ('status_code__lt', 600)), name='valid_status_code'),
+        ),
+        migrations.AddConstraint(
+            model_name='requestlog',
+            constraint=models.CheckConstraint(check=models.Q(('response_time_ms__gte', 0)), name='positive_response_time'),
+        ),
+    ]

trafficmonitor/models.py

@@ -0,0 +1,206 @@
+import uuid
+from django.conf import settings
+from django.db import models
+from django.core.serializers.json import DjangoJSONEncoder
+from django.utils import timezone
+from datetime import timedelta
+
+
+class RequestLogManager(models.Manager):
+    """Custom manager for RequestLog with optimized queries"""
+    
+    def get_recent_logs(self, days: int = 7):
+        """Get logs from the last N days"""
+        cutoff_date = timezone.now() - timedelta(days=days)
+        return self.filter(timestamp__gte=cutoff_date)
+    
+    def get_error_logs(self, days: int = 1):
+        """Get error logs (4xx, 5xx) from the last N days"""
+        cutoff_date = timezone.now() - timedelta(days=days)
+        return self.filter(
+            timestamp__gte=cutoff_date,
+            status_code__gte=400
+        )
+    
+    def cleanup_old_logs(self, retention_days: int = 90):
+        """Delete logs older than retention period"""
+        cutoff_date = timezone.now() - timedelta(days=retention_days)
+        deleted_count, _ = self.filter(timestamp__lt=cutoff_date).delete()
+        return deleted_count
+
+
+class RequestLog(models.Model):
+    """
+    Enterprise-grade model for HTTP request logging.
+    Optimized for high-volume traffic with partitioning support.
+    """
+    
+    # Operation Types
+    OPERATION_READ = 'READ'
+    OPERATION_WRITE = 'WRITE'
+    OPERATION_DELETE = 'DELETE'
+    
+    OPERATION_CHOICES = [
+        (OPERATION_READ, 'Read Operation'),
+        (OPERATION_WRITE, 'Write Operation'),
+        (OPERATION_DELETE, 'Delete Operation'),
+    ]
+    
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    # Basic Request Info
+    method = models.CharField(max_length=10, db_index=True, help_text="HTTP method (GET, POST, etc.)")
+    path = models.CharField(max_length=2048, db_index=True, help_text="Request path/URL")
+    full_url = models.TextField(help_text="Complete URL including query parameters")
+
+    # Response Info
+    status_code = models.IntegerField(db_index=True, help_text="HTTP response status code")
+
+    # User & IP Tracking (Enterprise: Header-based user ID)
+    requested_user_id = models.CharField(
+        max_length=255,
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="User ID from request header (X-User-ID)"
+    )
+    ip_address = models.GenericIPAddressField(
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="Client IP address"
+    )
+    user_agent = models.TextField(
+        null=True,
+        blank=True,
+        help_text="User agent string from request headers"
+    )
+
+    # Request Metadata
+    request_headers = models.JSONField(
+        null=True,
+        blank=True,
+        encoder=DjangoJSONEncoder,
+        help_text="Request headers as JSON (sensitive headers excluded)"
+    )
+    request_body = models.TextField(
+        null=True,
+        blank=True,
+        help_text="Request body content (truncated for large payloads)"
+    )
+
+    # Operation Classification
+    operation_type = models.CharField(
+        max_length=10,
+        choices=OPERATION_CHOICES,
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="Operation type: READ (GET, HEAD, OPTIONS), WRITE (POST, PUT, PATCH), DELETE"
+    )
+    
+    endpoint_category = models.CharField(
+        max_length=100,
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="Endpoint category extracted from path (e.g., /api/users -> users)"
+    )
+    
+    is_api_request = models.BooleanField(
+        default=False,
+        db_index=True,
+        help_text="Whether this is an API request (starts with /api/)"
+    )
+
+    # Performance Metrics
+    response_time_ms = models.FloatField(
+        null=True,
+        blank=True,
+        db_index=True,
+        help_text="Response time in milliseconds"
+    )
+    query_count = models.IntegerField(
+        null=True,
+        blank=True,
+        help_text="Number of database queries executed"
+    )
+
+    # Error Tracking
+    exception = models.TextField(
+        null=True,
+        blank=True,
+        help_text="Exception traceback if request failed"
+    )
+    content_length = models.IntegerField(
+        null=True,
+        blank=True,
+        help_text="Response content length in bytes"
+    )
+
+    # Timestamps
+    timestamp = models.DateTimeField(auto_now_add=True, db_index=True)
+    
+    # Custom manager
+    objects = RequestLogManager()
+
+    class Meta:
+        db_table = "request_log"
+        verbose_name = "Request Log"
+        verbose_name_plural = "Request Logs"
+        ordering = ["-timestamp"]
+        
+        # Optimized indexes for enterprise queries
+        indexes = [
+            # Primary query patterns
+            models.Index(fields=["-timestamp", "status_code"], name="idx_timestamp_status"),
+            models.Index(fields=["requested_user_id", "-timestamp"], name="idx_user_timestamp"),
+            models.Index(fields=["path", "-timestamp"], name="idx_path_timestamp"),
+            models.Index(fields=["operation_type", "-timestamp"], name="idx_operation_timestamp"),
+            models.Index(fields=["endpoint_category", "-timestamp"], name="idx_category_timestamp"),
+            
+            # Analytics queries
+            models.Index(fields=["is_api_request", "status_code", "-timestamp"], name="idx_api_status_timestamp"),
+            models.Index(fields=["method", "status_code", "-timestamp"], name="idx_method_status_timestamp"),
+            
+            # Performance monitoring
+            models.Index(fields=["response_time_ms", "-timestamp"], name="idx_response_time"),
+            models.Index(fields=["query_count", "-timestamp"], name="idx_query_count"),
+            
+            # Error tracking
+            models.Index(fields=["status_code", "-timestamp"], condition=models.Q(status_code__gte=400), name="idx_errors_only"),
+        ]
+        
+        # Database constraints
+        constraints = [
+            models.CheckConstraint(
+                check=models.Q(status_code__gte=100) & models.Q(status_code__lt=600),
+                name="valid_status_code"
+            ),
+            models.CheckConstraint(
+                check=models.Q(response_time_ms__gte=0),
+                name="positive_response_time"
+            ),
+        ]
+
+    def __str__(self):
+        user_str = self.requested_user_id or "Anonymous"
+        op_type = f"[{self.operation_type}]" if self.operation_type else ""
+        return f"{self.method} {self.path} [{self.status_code}] {op_type} - {user_str} at {self.timestamp}"
+    
+    @staticmethod
+    def get_operation_type(method):
+        """Determine operation type from HTTP method"""
+        if method in ['GET', 'HEAD', 'OPTIONS']:
+            return RequestLog.OPERATION_READ
+        elif method == 'DELETE':
+            return RequestLog.OPERATION_DELETE
+        elif method in ['POST', 'PUT', 'PATCH']:
+            return RequestLog.OPERATION_WRITE
+        return None
+    
+    @staticmethod
+    def extract_endpoint_category(path):
+        """Extract category from path (e.g., /api/users/123 -> users)"""
+        parts = [p for p in path.split('/') if p and p != 'api']
+        return parts[0] if parts else None