Description

Capture and store a sequence of requests/responses to a service by observing
network traffic.

Examples

Capture all traffic and send it to Akita, under the "my-api" project.

akita apidump --project my-api

Capture traffic on port 80. Do not send the traffic to Akita, but save it in a directory called mytracedir.

akita apidump --filter "port 80" --out mytracedir

Run my_tests.sh as ${USER} and capture traffic on port 80. Send the captured traffic to Akita, under the "my-api" project. Akita Agent will automatically terminate once the script finishes.

akita apidump --project my-api --filter "port 80" -c ./my_tests.sh -u ${USER}

Required Flags

--project name or --out directory

Exactly one of these must be given.

The --project name flag names a project with which to associate the captured traffic. The traffic is sent to Akita.

The --out directory flag names a local directory in which to store the captured traffic. The traffic is not sent to Akita, but is written as a collection of HAR files in the directory.

Optional Flags

--filter string

Used to match packets going to and coming from your API service.

For example, to match packets to or from port 80, you would set --filter="port 80".

The syntax follows BPF syntax. See Packet Filters for Customizing Capture

This filter is applied uniformly across all network interfaces, as set by --interfaces flag.

--interfaces iface1,iface2,...

List of network interfaces to listen on (e.g. "lo" or "eth0").

You may specify a comma separated string (e.g. --interfaces lo,eth0) or multiple separate flags (e.g. --interfaces lo --interfaces eth0).

If not set, defaults to all interfaces on the host.

--rate-limit number

Set the maximum number of HTTP request/response pairs to collect per minute. If the number of samples exceeds this amount, the CLI will randomly sample events, and send only the specified number to the Akita cloud.

--tags key1=value1,key2=value2,...

Adds tags to the dump.

You may specify a comma-separated list of "key=value" pairs (e.g. --tags a=b,c=d) or multiple separate flags (e.g. --tags a=b --tags c=d)

--command, -c string

A command that generates requests and responses for Akita to observe. Akita will execute the command (similar to bash -c) and automatically terminate when the command finishes, without needing to receive a SIGINT.

By default, the command runs as the current user. As a safety precaution, if the current user is root, you must use the -u flag to explicitly indicate that you want to run as root.

--user, -u string

Username of the user to use when running the command specified in -c

--path-exclusions regex1,regex2,...

Removes HTTP paths matching regular expressions.

For example, to filter out requests fetching files with png or jpg extensions, you can specify --path-exclusions '.*\.png' --path-exclusions '.*\.jpg'

--host-exclusions regex1,regex2,...

Removes HTTP requests whose host URL matches any one of the given regular expressions.

--path-allow regex1,regex2,...

Only capture HTTP requests whose whose URL path matches any one of the given regular expressions.

--host-allow regex1,regex2,...

Only capture HTTP requests whose whose URL host matches any one of the given regular expressions.

--proxy location (version 0.23.1 and later)

Send traffic to the Akita Cloud via a web proxy. The location may be a hostname or IP address, optionally followed by a colon and a port number. A proxy specified this way is assumed to be HTTP. To use a HTTPS or SOCKS proxy, use a full url of the form https://my-proxy:port or socks5://my-proxy:port.

Diagnostic output (version 0.12.1 and later)

If the packet capture fails to see any HTTP requests or responses, the CLI will emit one of the following warning messages:

Did not capture any TCP packets matching the filter: There were TCP packets observed, but not matching the filter that you specified. This may mean that you used an incorrect port number, or other mistake in the --filter argument.

Did not capture any TCP packets during the trace: No TCP packets were observed at all. This could occur if you specify an --interface argument other than the one that has API traffic, or if the test did not generate any network traffic.

Captured MMM TCP packets total; NNN unparsed TCP segments: The capture contains TCP streams matching the filter, but they could not be recognized as HTTP. A common reason is that they were encrypted HTTPS instead, and must be captured using a proxy or browser instead. Or, it could be that the traffic is another protocol not yet supported.

To see more details about the packet capture process, and accumulated counters, run akita with the --debug flag.