learn
Deprecated command
We no longer actively support this command. We recommend you use
apidump
instead and integrate Akita with your active traffic.
Description
Generate API specifications from network traffic.
Examples
akita learn --filter "port 80" --service my-service
Capture requests/responses going to or coming from port 80 and convert them into an API spec.
akita learn --filter "port 80" -c ./my_tests.sh -u ${USER}
Run my_tests.sh
as ${USER}
and capture requests/responses going to or coming from port 80. Akita will automatically terminate once the script finishes.
Optional Flags
--out location
--out location
The location to store the spec. Can be an AkitaURI or a local file.
If not specified, defaults to a trace on Akita Cloud. Note that you must supply --service
in this case.
When specifying an AkitaURI, the format is "akita://{SERVICE}:spec:{NAME}", where "SERVICE" is the name of your service and "NAME" is the name of the spec on Akita Cloud where the collected data is stored.
--service string
--service string
Your Akita service. Only needed if --out
is not an AkitaURI.
--filter string
--filter string
Used to match packets going to and coming from your API service.
For example, to match packets destined/originated from port 80, you would set --filter="port 80"
.
The syntax follows BPF syntax (man 7 pcap-filter).
This filter is applied uniformly across all network interfaces, as set by --interfaces
flag.
--interfaces []string
--interfaces []string
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
--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.
--sample-rate number
--sample-rate number
A number between [0.0, 1.0] to control sampling. Deprecated, use --rate-limit
instead.
--tags []string
--tags []string
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
--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
--user, -u string
Username of the user to use when running the command specified in -c
--path-exclusions []string
--path-exclusions []string
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 []string
--host-exclusions []string
Removes HTTP requests whose host URL matches any one of the given regular expressions.
--path-allow []string
--path-allow []string
Only capture HTTP requests whose whose URL path matches any one of the given regular expressions.
--host-allow []string
--host-allow []string
Only capture HTTP requests whose whose URL host matches any one of the given regular expressions.
--path-parameters []path-prefix
--path-parameters []path-prefix
A path prefix is composed of components separated by "/". There are 3 types of components:
- A concrete path value
- A path parameter of the form
{parameter_name}
- A placeholder
^
to indicate that the component must retain the value in the trace verbatim and NOT get generalized. It behaves like a wildcard when matching path prefixes to paths.
Paths in the trace that match this path prefix are updated to use path parameters and respect placeholders that are specified.
If a path matches multiple prefixes, Akita selects the longest matching prefix.
Example 1: Simple prefix match
--path-parameters="/v1/{my_param}"
Akita inferred endpoint | Post-processed endpoint |
---|---|
/v1/foo | /v1/{my_param} |
/v1/x/y | /v1/{my_param}/y |
/v1/{arg2}/z | /v1/{my_param}/z |
Example 2: Longest prefix match
--path-parameters="/v1/{my_param},/v1/{my_param}/123/{other_param}"
Akita inferred endpoint | Post-processed endpoint |
---|---|
/v1/foo | /v1/{my_param} |
/v1/x/123/abc | /v1/{my_param}/123/{other_param} |
/v1/x/456/def | /v1/{my_param}/456/def |
Example 3: Akita inferred path retained
--path-parameters="/v1/foo/{param}/bar"
Akita inferred endpoint | Post-processed endpoint |
---|---|
/v1/foo/x | /v1/foo/x |
/v1/foo/baz/bar | /v1/foo/{param}/bar |
/v1/xyz/baz/bar | /v1/xyz/baz/bar |
/v1/{arg2}/x/bar | /v1/{arg2}/x/bar |
In this example, the endpoint /v1/{arg2}/x/bar will remain if the trace contains requests that match that endpoint with concrete path arguments in the second position that are not "foo", e.g. /v1/123/x/bar. To force the removal of the path parameter, use the placeholder ("^") component.
Example 4: Placeholder component
--path-parameters="/v1/^/{param}/bar"
Akita inferred endpoint | Post-processed endpoint |
---|---|
/v1/foo/x | /v1/foo/x |
/v1/foo/baz/bar | /v1/foo/{param}/bar |
/v1/xyz/baz/bar | /v1/xyz/{param}/bar |
/v1/{arg2}/x/bar | /v1/123/{param}/bar |
GitHub Integration Flags
The following flags are needed to enable GitHub integration.
--github-branch string
--github-branch string
Name of github branch that this spec belongs to.
--github-commit string
--github-commit string
SHA of github commit that this spec belongs to.
--github-pr int
--github-pr int
GitHub PR number that this spec belongs to.
--github-repo string
--github-repo string
GitHub repo name of the form <repo_owner>/<repo_name> that this spec belongs to.
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.
Updated over 1 year ago