DIY Akita Agent Integration

Once our agent is in your service or stack, we gather all the data you need and surface it in the Akita app so you can easily see what your system is doing.

If you want to use Akita but don’t have a tech stack in one of the supported categories, it might still be possible to integrate us.

Below you’ll find the requirements, basic instructions, and some troubleshooting tips for manually installing the Akita Agent in your tech stack.

  1. Requirements
  2. Installing the agent
  3. Running the agent
  4. Verify
  5. Diagnostics

Requirements

You’ll need to be in our beta to use Akita.

The system where your app is running must have permission to listen to network traffic.

  • This means that the Akita agent has to run in a location where it can access the same network interface that the application is using to communicate.

🚧

Note

Attaching the Akita Agent to the same network is not enough; the Agent needs access to a network device.

  • The agent must have the CAP_NET_RAW Linux capability. Usually you can get this by running as root; see below for an alternative.

🚧

Note

Some container environments will remove this capability from all containers.

Create a project

Log-in to the Akita App, and go to the Settings page.
Enter a project name and click "Create Project". We suggest naming the project after your app or deployment stack.

22542254

Give your project a name that's easy to remember – you'll need it later, when you start the Akita Agent on the CLI.

Generate API key

On the same Settings page, locate and click the “API Keys” tab. Click the “Set up the Akita client” button. Copy your API key secret into your favorite password manager or somewhere else you can easily access it. Also note your API key, as you will need it later.

780780

Installing the agent

The easiest method to install the agent is to install it using our auto-install script:

bash -c "$(curl -L https://releases.akita.software/scripts/install_akita.sh)"

It is not currently possible to download a specific version with this command. However, you can copy the Akita binary directly onto another system. It has a dependency on the libpcap library.

📘

Tip

Any other method you use to distribute prebuilt binaries should work with the Akita CLI.

Setting up the binary to run without root permissions

If you do not wish to run the Akita CLI as root, you can run the following command to give it the necessary capability:

setcap cap_net_raw+e /usr/local/bin/akita

Running the agent

You can store your API key and API secret in the AKITA_API_KEY_ID and AKITA_API_KEY_SECRET environment variables.

Or, you can create a credentials file of the following format in /root/.akita/credentials.yaml (or, if not running as root, in the home directory of the user):

default:
  api_key_id: apk_xxxxxx
  api_key_secret: xxxxxx

The agent should be run in the background; you might want to write a service description for it so that it can be automatically restarted.

The Akita CLI cannot currently read its configuration from a file.

The Akita CLI cannot write its log output to a file or to syslog. See Choosing an output format for a choice of format.

Because of these limitations, you will probably want to create a wrapper script that contains your desired configuration and command-line settings, and redirects the output to the logging facility in your environment.

It is usually sufficient to run the following command without any further arguments

akita apidump --project <your project name>

This will listen on all available network interfaces.

The agent needs outbound access to api.akita.software port 443. It is not currently possible to configure a proxy.

Verify

After 60 seconds, the agent will output a summary of the traffic it has observed. This will tell you whether packet capture is working, and which ports contain HTTP traffic.

In the Akita web console, check out the incoming data on the Model page. You should see a map of your API being generated as the Akita Agent gathers data.

Then check out the Metrics and Errors page to get real-time information on the health of your app or service.

Agent diagnostics

If you terminate the akita apidump command with SIGINT, the CLI will indicate whether any HTTP traffic has successfully been accessed.

You can use the --debug flag to have Akita emit additional information as it is running.


Did this page help you?