🚧

Experimental

This is a new feature and we haven't ironed out all the kinks yet! Proceed with appropriate caution.

You can capture API traces from an Express.js application via Akita-provided middleware and the Akita Agent running in "daemon" mode.

In this guide, we'll explain

1. How to run the Akita Agent in daemon mode
2. How to configure the Akita Express.js middleware
3. How to start and stop staging and production API traffic collection

📘

When to use the Express.js Middleware

This method is applicable for production and staging environments where you cannot capture packet traces, or want to capture only some of the time. It cannot be used to collect traces during unit or integration tests. If you are running a server locally during development, check out our other methods.

How the Daemon works

The akita-express-middleware package provides Express.js middleware that sends each request and response to the Akita Agent, 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.

❗️

The communication between the Akita Express.js middleware and the daemon is unencrypted and unauthenticated, so plan to run them within the same trust boundary.

Create a project in the Akita web console

Log in to the Akita web console with your username and password. Click the "New Project" button and give your project a descriptive name. We'll use akibox-express as our example project 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 projects.

Run the Akita Agent in daemon mode

The Akita Agent's daemon command starts an HTTP server, which is used by the middleware for receiving control messages and sending data. One daemon process can be used by many different middleware instances, and different projects. However, traffic between the middleware and the daemon is unencrypted, so the Akita CLI daemon should be run in a trusted part of the environment.

First ensure that you are logged in with a valid Akita key. Either use akita login or set the environment variables AKITA_API_KEY_ID and AKITA_API_KEY_SECRET.

akita login

Pick a descriptive name for the daemon to identify itself; if you do not specify one, the default name is the hostname on which the Akita Agent is run. Specify this name with the --name command line flag.

akita daemon --name example-daemon --port 50080

The daemon runs on port 50080 by default. You can choose a different port with the --port command line flag.

You can stop the daemon by interrupting it with Ctrl+C or the kill -INT <process id> command.

One the daemon is running, you can open your project in the web console, click the "Diagnostics" page, 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.

Install and configure the Akita middleware for Express.js

In your Express.js project directory, use NPM to add the middleware as a dependency:

npm install akita-express-middware

Inside the main file of your application (usually app.js), import the package and install it in the application, like this:

import akitaMW from `akita-express-middleware`;

...

app.use(akitaMW({
    "clientName" : "<your client name here>",
    "serviceName" : "akibox-express",
    "daemonHost"  : "<daemon host>:50080",
}));

You should pick a descriptive name for the middleware instance, such as the name of the application.

Specify the project name that you created in the Akita web console. Also configure the middleware with the host on which the daemon is running, and the port number on which the daemon's HTTP server is running.

Start your server as you normally would. No API traces will be collected until you enable them in the Akita web console, in the next step.

❗️

The middleware is not configured with its own API key; any traffic sent to the daemon will be captured and uploaded with the API key specified for the daemon. There is currently no access control on the middleware-to-daemon communication, so any middleware with the correct port number can send traffic to the daemon as part of the capture.

Also, please note that communication between the middleware and the daemon is unencrypted HTTP.

Optional: Configuring an alternate logger

You may specify a log for the middleware to use for its informational and error output. Any object which supports "info", "warn", and "error" methods will work. Log objects created with Winston or Bunyan will work. if you do not specify a logger, console.log will be used.

app.use(akitaMW({
    "clientName" : "<your client name here>",
    "serviceName" : "akibox-express",
    "daemonHost"  : "<daemon host>:50080",
    "logger"      : log,
}));

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:

$ akita daemon -name example-daemon
[INFO] Activating trace powder-blue-panda-338 (lrn_6EjLU2sINbfKRwmqeqQM8s)

$ node dist/app.js
akitaMW info: 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.

See your API model!

Once the trace starts, Akita will automatically create models from it. There will be about a three-minute delay before the first model is ready in the "API model" tab.

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.