Troubleshooting

Below are a few tips for troubleshooting if you're not seeing the traffic you want. If you get stuck, don't hesitate to talk to us! We're more than happy to help.

The Akita client is not capturing traffic

This section describes what to do if you have started the Akita CLI but no metrics or models are appearing in the Akita Console.

Check the client status

If nothing is showing up, one reason could be that the Akita client isn't seeing the traffic it's expecting to see. In the Akita Console, navigate to the "Service Diagnostics" link in the sidebar, and select the "Traffic" tab.

25182518

Each time an Akita Client starts, the client registers with the backend and monitors packet capture health over the course of one minute after initialization. Clients that fail to capture traffic within the first minute will appear with a warning status on this page.

19621962

Each row expands to show warning messages (if applicable) along with packet capture statistics.

19381938

Here are a few things to look for:

  • The Raw TCP packets count is zero. This means that the client did not see any traffic. If you are using the --filter flag or have specified an interface to listen on, make sure they are correct. To make sure you're not filtering too much, try removing these flags to capture traffic on all ports and interfaces.
  • The Unparsable packets count is greater than zero. This often means the Akita Client is trying to parse encrypted traffic. If the HTTP Request/Response count is zero, then all your traffic is likely TLS traffic. Talk to us about what to do.

Check for log messages from the Akita client

The Akita CLI will show an error if the collection of API traffic fails or results in an empty trace. Possible causes include:

  • Non-root users do not have the permissions to capture network traffic. You will see the message You don't have permission to capture on that device if that is the case. Try running as root, or with sudo.
  • The API traffic you are attempting to capture runs over HTTPS, instead of HTTP. In this case the API will give the error No inbound HTTP calls captured, as well as report the number of packets captured with Captured %d TCP packets total; %d unparsed TCP segments. This indicates that some network traffic was detected, but could not be successfully parsed.
  • The TCP port number you gave was incorrect, so the traffic was not included in the trace. This case will also report an error No inbound HTTP calls captured, but additionally show the explanatory message Did not capture any TCP packets matching the filter or Did not capture any TCP packets during the trace,

See the Diagnostics section in the apidump command for more information.

Test that Akita saw all your endpoints

Once you run Akita, here’s how you can test that your setup worked. First, use apidump to capture traffic to your service and store it in a local trace.

# 1. Start capturing traffic:
akita apidump --filter "port ${YOUR_PORT}" --out path/to/local/dir

# 2. Exercise your service's API.
# 3. Hit Ctrl+C to stop capturing traffic.
# 1. Start capturing traffic:
akita apidump --filter "port ${YOUR_PORT}" --out path/to/local/dir

# 2. Exercise your service's API.
# 3. Hit Ctrl+C to stop capturing traffic.
# 0. Find your Akita API key, secret, the name of the docker container
#    your service is in, and the port it listens on.  Use these values
#    in the next step.
#
#    Also set the HAR_OUTPUT_DIR environment variable (or replace it in
#    the --volume flag) to specify a directory to store the output.

# 1. Start capturing traffic:
docker run --rm -it \
  --env AKITA_API_KEY_ID=${KEY_ID} \
  --env AKITA_API_KEY_SECRET=${KEY_SECRET} \
  --net="container:${CONTAINER_NAME}" \
  --volume ${HAR_OUTPUT_DIR}:/har \
  akitasoftware/cli:<<current_cli_version>> apidump \
  --filter "port ${YOUR_PORT}" \
  --out /har

# 2. Exercise your service's API.
# 3. Hit Ctrl+C to stop capturing traffic.

📘

Getting HAR Files From Docker

If you run apidump in Docker, then you'll need to mount a volume in order to access the HAR files outside of Docker.

The Docker command above includes the flag --volume ${HAR_OUTPUT_DIR}:/har, which ensures that any files written to /har in the container are accessible at the directory you supply with ${HAR_OUTPUT_DIR} outside the container. Combined with the --out /har flag, this ensures that the HAR files will be accessible from the local file system.

Traces are formatted as HAR files, which use a JSON encoding to represent traffic. If you install the jq utility, you can use the following command to list the endpoints in the HAR files.

# Echo unique raw endpoints observed:
for har in path/to/local/dir/*.har; do
  cat ${har} | jq '.log.entries | .[] | .request.url' | sort | uniq
done

You can also print the contents of each request, rather than just the endpoint. Additional information can often be found in the request headers, like the host and port receiving the request.

# Echo requests observed:
for har in path/to/local/dir/*.har; do
  cat ${har} | jq '.log.entries | .[] | .request'
done

What If I don't have server traffic?

If you want to generate an API model by accessing an AJAX website, check out OpenAPI Spec Generator Chrome Extension.

Other troubleshooting questions


Did this page help you?