feat(profiling): Add request profiling middleware

This commit introduces `ProfileRequestMiddleware` to provide performance
insights for API requests, migrating and generalizing functionality
from AWX's `TimingMiddleware` and `AWXProfiler`. This makes the
functionality available to any consumer of `django-ansible-base`.

The middleware always adds an `X-API-Time` header to the response,
indicating the total time taken to process the request. To help locate
profiling data, it also adds an `X-API-Node` header with the cluster
host ID if one is not already present in the response.

When the `ANSIBLE_BASE_CPROFILE_REQUESTS` setting is enabled, the
middleware will also perform a cProfile analysis for each request.
The resulting `.prof` file is saved to a temporary directory on the
node that served the request, and its path is returned in the
`X-API-CProfile-File` response header.

For the most accurate and reliable timing, it is recommended to add
this middleware to the top of the `MIDDLEWARE` list in your settings.

The core profiling logic is encapsulated in the `DABProfiler` class,
which can be imported and used directly for profiling non-HTTP contexts,
such as background tasks.

This commit also includes a `README.md` file with documentation for
the new middleware and profiler, including usage examples and tests in
the test_app.

Author: kdelee

ansible_base/lib/middleware/profiling/README.md

@@ -0,0 +1,88 @@
+# Request Profiling
+
+The `ProfileRequestMiddleware` and `DABProfiler` class provide a way to profile requests and other code in your Django application. This functionality is a generalization of the profiling tools found in AWX and can be used by any `django-ansible-base` consumer.
+
+## `ProfileRequestMiddleware`
+
+This middleware provides performance insights for API requests. To use it, add it to your `MIDDLEWARE` list in your Django settings. For the most accurate and reliable timing, it is recommended to add this middleware to the top of the `MIDDLEWARE` list.
+
+```python
+# settings.py
+MIDDLEWARE = [
+    'ansible_base.lib.middleware.profiling.profile_request.ProfileRequestMiddleware',
+    ...
+]
+```
+
+The middleware always adds the following headers to the response:
+
+*   `X-API-Time`: The total time taken to process the request, in seconds.
+*   `X-API-Node`: The cluster host ID of the node that served the request. This header is only added if it is not already present in the response.
+
+### cProfile Support
+
+When the `ANSIBLE_BASE_CPROFILE_REQUESTS` setting is enabled, the middleware will also perform a cProfile analysis for each request. The resulting `.prof` file is saved to a temporary directory on the node that served the request, and its path is returned in the `X-API-CProfile-File` response header.
+
+To enable cProfile support, set the following in your Django settings:
+
+```python
+# settings.py
+ANSIBLE_BASE_CPROFILE_REQUESTS = True
+```
+
+## `DABProfiler`
+
+The core profiling logic is encapsulated in the `DABProfiler` class. This class can be imported and used directly for profiling non-HTTP contexts, such as background tasks or gRPC services.
+
+The profiler's cProfile functionality is controlled by the `ANSIBLE_BASE_CPROFILE_REQUESTS` setting.
+
+- When the setting is `True`, `profiler.stop()` returns a tuple of `(elapsed_time, cprofile_filename)`.
+- When the setting is `False`, `profiler.stop()` returns `(elapsed_time, None)`.
+
+### Example Usage
+
+```python
+from ansible_base.lib.middleware.profiling.profile_request import DABProfiler
+
+def my_background_task():
+    profiler = DABProfiler()
+    profiler.start()
+
+    # Your code here
+
+    elapsed, cprofile_filename = profiler.stop()
+
+    if cprofile_filename:
+        print(f"cProfile data saved to: {cprofile_filename}")
+
+    print(f"Task took {elapsed:.3f}s to complete.")
+```
+
+## Visualizing Profile Data
+
+The `.prof` files generated by the cProfile support can be analyzed with a variety of tools.
+
+### SnakeViz
+
+[SnakeViz](https://jiffyclub.github.io/snakeviz/) is a browser-based graphical viewer for the output of Python profilers.
+
+You can install it with pip:
+```bash
+pip install snakeviz
+```
+
+To visualize a profile file, run:
+```bash
+snakeviz /path/to/your/profile.prof
+```
+
+### pstats
+
+The standard library `pstats` module can also be used to read and manipulate profile data.
+
+```python
+import pstats
+
+p = pstats.Stats('/path/to/your/profile.prof')
+p.sort_stats('cumulative').print_stats(10)
+```

ansible_base/lib/middleware/profiling/profile_request.py

@@ -0,0 +1,82 @@
+import cProfile
+import logging
+import os
+import tempfile
+import threading
+import time
+import uuid
+from typing import Optional, Union
+
+from django.utils.translation import gettext_lazy as _
+
+from ansible_base.lib.utils.settings import get_function_from_setting, get_setting
+
+logger = logging.getLogger(__name__)
+
+
+class DABProfiler:
+    def __init__(self, *args, **kwargs):
+        self.cprofiling = bool(get_setting('ANSIBLE_BASE_CPROFILE_REQUESTS', False))
+        self.prof = None
+        self.start_time = None
+
+    def start(self):
+        self.start_time = time.time()
+        if self.cprofiling:
+            self.prof = cProfile.Profile()
+            self.prof.enable()
+
+    def stop(self, profile_id: Optional[Union[str, uuid.UUID]] = None):
+        if self.start_time is None:
+            logger.debug("Attempting to stop profiling without having started...")
+            return None, None
+
+        elapsed = time.time() - self.start_time
+
+        if not profile_id:
+            profile_id = uuid.uuid4()
+
+        cprofile_filename = None
+
+        if self.cprofiling and self.prof:
+            self.prof.disable()
+            temp_dir = tempfile.gettempdir()
+            filename = f"cprofile-{profile_id}.prof"
+            cprofile_filename = os.path.join(temp_dir, filename)
+            self.prof.dump_stats(cprofile_filename)
+
+        return elapsed, cprofile_filename
+
+
+class ProfileRequestMiddleware(threading.local):
+    def __init__(self, get_response=None):
+        self.get_response = get_response
+        self.profiler = DABProfiler()
+
+    def __call__(self, request):
+        # Logic before the view (formerly process_request)
+        self.profiler.start()
+        request_id = request.headers.get('X-Request-ID')
+
+        # Call the next middleware or the view
+        response = self.get_response(request)
+
+        # Logic after the view (formerly process_response)
+        if getattr(self.profiler, 'start_time', None) is None:
+            return response
+
+        elapsed, cprofile_filename = self.profiler.stop(profile_id=request_id)
+
+        if elapsed is not None:
+            response['X-API-Time'] = f'{elapsed:.3f}s'
+        if 'X-API-Node' not in response:
+            response['X-API-Node'] = get_setting('CLUSTER_HOST_ID', _('Unknown'))
+
+        if cprofile_filename:
+            response['X-API-CProfile-File'] = cprofile_filename
+            logger.debug(
+                f'request: {request}, cprofile_file: {response["X-API-CProfile-File"]}',
+                extra=dict(python_objects=dict(request=request, response=response, X_API_CPROFILE_FILE=response["X-API-CProfile-File"])),
+            )
+
+        return response

test_app/tests/lib/middleware/test_profiling_middleware.py

@@ -0,0 +1,67 @@
+
+import os
+import tempfile
+from unittest.mock import patch
+
+from django.http import HttpResponse
+from django.test import TestCase, override_settings
+from django.urls import path
+
+from ansible_base.lib.middleware.profiling.profile_request import ProfileRequestMiddleware
+
+# A simple view for testing middleware
+def simple_view(request):
+    return HttpResponse("OK")
+
+# Define URL patterns for the test
+urlpatterns = [
+    path('test/', simple_view),
+]
+
+@override_settings(ROOT_URLCONF=__name__)
+class ProfileRequestMiddlewareTest(TestCase):
+    @override_settings(CLUSTER_HOST_ID='test-node')
+    def test_profile_request_middleware_headers(self):
+        """
+        Test that the ProfileRequestMiddleware adds sensible headers.
+        """
+        middleware = ProfileRequestMiddleware(simple_view)
+        response = middleware(self.client.get('/test/').wsgi_request)
+        
+        # Test X-API-Time
+        self.assertIn('X-API-Time', response)
+        self.assertTrue(response['X-API-Time'].endswith('s'))
+        try:
+            float(response['X-API-Time'][:-1])
+        except ValueError:
+            self.fail("X-API-Time value is not a valid float")
+
+        # Test X-API-Node
+        self.assertIn('X-API-Node', response)
+        self.assertEqual(response['X-API-Node'], 'test-node')
+
+    @override_settings(ANSIBLE_BASE_CPROFILE_REQUESTS=True)
+    def test_profile_request_middleware_cprofile_enabled(self):
+        """
+        Test that the ProfileRequestMiddleware adds the X-API-CProfile-File
+        header and creates a profile file when enabled.
+        """
+        with tempfile.TemporaryDirectory() as tmpdir:
+            with patch('tempfile.gettempdir', return_value=tmpdir):
+                middleware = ProfileRequestMiddleware(simple_view)
+                response = middleware(self.client.get('/test/').wsgi_request)
+                self.assertIn('X-API-CProfile-File', response)
+                profile_file = response['X-API-CProfile-File']
+                self.assertTrue(profile_file.endswith('.prof'))
+                self.assertTrue(os.path.exists(profile_file))
+
+    def test_profile_request_middleware_cprofile_disabled(self):
+        """
+        Test that the ProfileRequestMiddleware does not add the
+        X-API-CProfile-File header when disabled.
+        """
+        middleware = ProfileRequestMiddleware(simple_view)
+        response = middleware(self.client.get('/test/').wsgi_request)
+        self.assertNotIn('X-API-CProfile-File', response)
+
+