Install Atatus Python APM agent in Django server

Supported Versions

Django 1.11 and above.

Installation steps

Install the Atatus python agent:

Option 1: Install the agent using pip.

copy
```
pip install atatus
```
Option 2: Add atatus to your project's requirements.txt file, and install the agent using pip.

copy
```
# requirements.txt
atatus
```
copy
```
pip install -r requirements.txt
```
Add atatus.contrib.django to INSTALLED_APPS in your settings.py:

copy
```
# settings.py

INSTALLED_APPS = [
   # ...
   'atatus.contrib.django',
]
```

Add license key and app name in your settings.py:

copy

# settings.py

ATATUS = {
   'APP_NAME': 'Django App',
   'LICENSE_KEY': 'lic_apm_xxxxxxx',
   # 'DEBUG': True  # Please uncomment this line if you are running in development/debug mode. Otherwise, we do not send data.
}

Restart your Django server

Installation steps for Django 5+ with ASGI

Here’s a step-by-step guide on setting up Django 5 with ASGI using custom middleware for Atatus tracing:

Step 1: Install Required Dependencies

Ensure that Atatus are installed in your environment. Run the following command to install these dependencies if you haven't already:

pip install atatus

Step 2: Integrate ASGI Tracing Middleware in `asgi.py`

Django 5 is ASGI-compatible, so the ASGITracingMiddleware will wrap the ASGI application to capture and trace async requests.

Open your project’s asgi.py file.

Update it to include the ASGITracingMiddleware:

import os
from django.core.asgi import get_asgi_application
from atatus.contrib.asgi import ASGITracingMiddleware

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "<your_django_app_config>.settings")

application = ASGITracingMiddleware(get_asgi_application())

This wraps your ASGI application with Atatus tracing, allowing for async request tracking.

Step 3: Configure `CustomTracingMiddleware`

This custom middleware extends Atatus's TracingMiddleware to add specific transaction naming logic based on the request's path and view name.

Create or open the middleware.py file in your Django application.

Add the following code to middleware.py:

import atatus
from atatus.contrib.django.middleware import TracingMiddleware
from django.http import HttpRequest
from django.urls import resolve

class CustomTracingMiddleware(TracingMiddleware):
    def process_request(self, request: HttpRequest):
        # Check if there's an active Atatus transaction
        if atatus.get_transaction_id():
            # Format the transaction name based on the request method and path
            transaction_name = "{} {}".format(request.method.upper(), request.path.lower())
            route_name = ""

            # Attempt to resolve the route name from the request
            try:
                if request.resolver_match:
                    route_name = request.resolver_match.view_name
                else:
                    match = resolve(request.path)
                    if match:
                        route_name = match.view_name
            except Exception:
                pass

            # Set transaction name to route name or formatted transaction name
            txn_name = route_name if route_name else transaction_name
            atatus.set_transaction_name(txn_name) #type: ignore

        return None

Add CustomTracingMiddleware to your middleware configuration in your settings.py file:

MIDDLEWARE = [
    '<your_middleware_module>.middleware.CustomTracingMiddleware',  # Ensure this path matches your app structure
    # other middleware components...
]

Make sure CustomTracingMiddleware is included in the order that best fits your middleware needs.

Step 4: Configure Atatus

Add atatus.contrib.django to INSTALLED_APPS in your settings.py:

copy
```
# settings.py

INSTALLED_APPS = [
   # ...
   'atatus.contrib.django',
]
```

Add license key and app name in your settings.py:

copy

# settings.py

ATATUS = {
   'APP_NAME': 'Django App',
   'LICENSE_KEY': 'lic_apm_xxxxxxx',
   # 'DEBUG': True  # Please uncomment this line if you are running in development/debug mode. Otherwise, we do not send data.
}

Replace 'LICENSE_KEY' with your actual license key. You can adjust the configuration options based on your tracing needs.

Step 5: Restart your Django server

After configuring the middleware and ASGI setup, restart your Django server to apply the changes. This will ensure that your custom middleware and ASGI tracing are active.

Once the server restarts, test by making requests to your application, and verify in Atatus that transactions and traces are being recorded.