Django on Heroku

❗️

Alpha

This is a new feature and we haven't ironed out all the kinks yet! Please get in touch with us at [email protected] or on our Slack if you have questions or comments.

You can capture API traces from an Django application running in Heroku, via Akita-provided middleware and the Akita CLI running in "daemon" mode. We will walk you through the steps that will help you see what's actually being used in your API, and look for breaking changes.

In this guide, we'll explain:

📘

When to use the Django Middleware

This guide is applicable for capturing API traces from Heroku production and staging environments, or applications run locally using heroku local.

The Django middleware can also be used in non-Heroku environments, if you have a location where the Akita CLI can be run in daemon mode. (Guide coming soon.)

How the Daemon works

The akita-django package provides Django middleware that sends each request and response to the Akita CLI, which is operating in "daemon" mode as a long-running process. The CLI obfuscates any identifying information from this trace and sends it, via HTTPS, to Akita Cloud, where an API model can be built from it.

The Akita Cloud controls when the daemon and middleware are actively capturing API traffic; you will start a trace from the Akita web console. In a Heroku environment, the daemon will be run as a separate process in same Heroku dyno.

How to create a service in the Akita web console

Log in to the Akita web console with your username and password. Click the "New Service" button and give your service a descriptive name.

If you have not created an API key, do so now; this can be done through the "Settings" tab in the UI. The API keys are not tied to particular services.

Add the Akita Django middleware to your application

Add the middleware to dependencies

Add akita-django to your requirements.txt file to mark it as a dependency that Heroku should build and install. The Python package includes the Django middleware, as well as a wrapper around Django.test.Client for use in tests.

Configure Django to to use the middleware

Add akita_django.middleware.AkitaMiddleware to the MIDDLEWARE list in your Django configuration. It should go early in the stack to see the unmodified version of requests, and the fully-processed version of responses.

Then, add the service name you created as a new configuration option called AKITA_SERVICE_NAME. You should also set AKITA_MIDDLEWARE_NAME to a descriptive name for the middleware to use in communications; the default is the hostname on which the middleware is running.

MIDDLEWARE = [
    'akita_django.middleware.AkitaMiddleware',
    ...
]

AKITA_SERVICE_NAME = "django-demo"
AKITA_MIDDLEWARE_NAME = "django-heroku-staging"

You may optionally set AKITA_DAEMON_HOST to specify an alternate location for the middleware to send its traffic, but this is not necessary in Heroku. You make also specify AKITA_MAX_QUEUE_LEN to control the amount of buffering used to hold request not yet sent to the daemon.

Enable the daemon in Heroku

The Akita CLI is packaged as a Heroku buildpack that starts the CLI in daemon mode in the background.

First, configure the Heroku environment with the API key that you created earlier. You may also give the daemon an informative name so that you can recognize it on the Akita web console. (By default the name is heroku, with the Dyno name is appended.)

$ heroku config:set AKITA_API_KEY_ID=<your key ID>
$ heroku config:set AKITA_API_KEY_SECRET=<your secret>
$ heroku config:set AKITA_DAEMON_NAME=<daemon name>

Then, add the Akita buildpack:

$ heroku buildpack:add --index 1 https://github.com/akitasoftware/heroku-buildpack-akita.git

The daemon listens on port 50080 by default. You can choose a different port with the AKITA_DAEMON_PORT configuration setting. But, this port is not visible outside of the Heroku dyno.

🚧

The Akita CLI buildpack will only work on Ubuntu-based Heroku runtimes; if you use a container runtime, then you must install the Akita CLI inside that container, and start it yourself.

Run your modified app in Heroku

You can try out the modified app locally with heroku local, or deploy it by pushing your changes to Heroku.

If running locally, you must start the Akita CLI in daemon mode. Ensure the AKITA_API_KEY_ID and AKITA_API_KEY_SECRET environment variables are set, and run

$ akita daemon --name <daemon name>

One the daemon is running, you can open your service in the web console, select the "Daemons" tab, and see an indication that the daemon is successfully talking to the Akita Cloud.

Daemon processes that have sent a heartbeat within the past minute are listed as "healthy"; those who have not communicated are shown as "unhealthy", or removed from the list entirely after 1 hour. Verify that the daemon name you chose is present.

Because the daemon and the middleware are started simultaneously, you will usually move directly to UI shown the next step.

Control trace collection via the Akita Web Console

Once the daemon receives a message from the middleware, indicating that it is ready to collect a trace, the Akita web console page will change. As shown below, it lists the active traces (currently none) and any daemons that are both active, and have communicated with middleware configured with a matching serviceName.

Click the "Start" button to begin a trace. You can select the duration of the trace (as a whole number of hours), but we suggest you start with just one hour on your first attempt. A trace name will be automatically generated. One the trace has started, the UI page will show its start and end time:

It may take up to a minute for the trace to start, and the page to refresh with the active trace name.

Both the daemon and middleware will issue "info" messages that they have begun collecting the trace:

$ heroku logs
akita: [INFO] Activating trace powder-blue-panda-338 (lrn_6EjLU2sINbfKRwmqeqQM8s)
akita_middleware: Activating trace powder-blue-panda-338 (lrn_6EjLU2sINbfKRwmqeqQM8s)

You may stop the trace at any time by pressing the "Stop" button. This operation may also take up to a minute to complete.

Create an API model from the captured trace

Once the trace is completed, you will see it in the Akita web console under the "previous traces" section of the Daemons tab:

The trace will also be visible in the "traces" tab. To create an API model from this trace, you must currently use the Akita CLI. An example command for the most recent trace is given in the web interface.

akita apispec --traces akita://<service name>:trace:<trace name> \
   --out akita://<service name>:spec

The output of the command will give you the URL for your API model, or you can find it by name in the "API specs" tab of the UI. See the apispec command reference for more detail on this CLI command.

[INFO] Generating API specification...
[INFO] Creating a new spec: akita://akibox-express:spec:lava-raptor-03a88a9c
[INFO] Your API spec ID is: api_2b9uS3JHHjijmbDVv3iDxD
[INFO] Success! 🎉

🔎 View your spec at: http://app.akita.software/service/svc_4WkSmud8KrwA3C2vWwJee2/spec/api_2b9uS3JHHjijmbDVv3iDxD

The API spec will show each endpoint that was present in the trace. On this page you can filter by criteria such as authentication type, method, or response code. Within each endpoint you can see the request and response types, and timing measurements obtained from the trace.

Optional: Compare against another trace

One of the main use cases Akita is working to support is automatically catching breaking changes. Today, you can diff across API models to get a summary of differences you might want to pay attention to, as well as the ability to explore all differences.

Diffing API models involves:

  1. Generating another model (from a second trace or another source)
  2. Comparing the two models.
    For more information on diffing, see Diff API Models.

First, you will need to obtain a second model for diffing. You have a few options:

  1. If you have captured a trace from a test environment, you could compare it with the model generated from staging, to see if there are gaps in testing.
  2. If your API is rapidly evolving, then we suggest taking two traces separated by a few days (or whatever your release schedule is.)
  3. You can use an existing OpenAPI spec, which you can upload using the "Upload" button.

Once your second model of choice is available, click the "Diff" button in the API Spec tab.

Select the older API model as the "base" and the most recent one as "current". Then press "show diff":

The result will be a report showing which endpoints have potentially-breaking changes. The format of this page is rapidly evolving, so your result may look quite different than the page below!

Next steps

Congratulations! You've captured an API trace from your production or staging environment, converted it to an API model, and looked at the difference between two models. This can alert you to features of your API that you might not be aware of, or highlight changes in the API that may cause problems for you or your users.

Please talk to us via email or the Akita Slack and let us know how we can improve the experience or help you meet your goals for API observability.


Did this page help you?