Command line interface (CLI)

Overview

The AppMap CLI @appland/appmap provides utility commands for working with AppMaps.

Installation

The AppMap Client CLI is written in Node.JS, so you install and manage this CLI using yarn or npm:

$ yarn add --dev @appland/appmap

Usage

Run @appland/appmap with npx or yarn run:

$ npx @appland/appmap --help

or

$ yarn run appmap --help

Inspect

Search AppMaps for references to a code object (package, function, class, query, route, etc) and print available event info.

$ npx @appland/appmap inspect --help
  appmap inspect <code-object>

  Positionals:

    code-object  identifies the code-object to inspect                  [required]

  Options:
        --version      Show version number                               [boolean]
    -v, --verbose      Run with verbose logging                          [boolean]
        --help         Show help                                         [boolean]
        --appmap-dir   directory to recursively inspect for AppMaps
                                                          [default: "tmp/appmap"]
    -i, --interactive  interact with the output via CLI                  [boolean]

You can use this command to search and display events and associated data from across all the AppMaps in a directory (recursively explored).

The code-object argument is a required argument, composed of a type and identifier. The inspect command will find all events that match this code object across all the AppMaps. Whether an event matches the code-object argument is defined as follows:

code-object type match criteria
function The event is a call to the specified function
class The event is a call to any function on the specified class
package The event is a call to any function on any class in the specified package
database The event is a SQL query
table The event is a SQL query which includes the specified table
query The event is a SQL query which, when normalized, matches the specified query
route The event is an HTTP server request which matches the specified route method and normalized path.

Examples of supported search syntax:

  • function:my/package/My::Class#instance_method
  • function:my/package/My::Class.static_method
  • class:my/package/My::Class
  • package:my/package
  • table:table_name
  • database:
  • route:REQUEST_METHOD /route/:id (HTTP request method followed by normalized path)
  • query:SELECT * FROM tables WHERE some_column = ? (normalized SQL)

Interactive mode

With the --interactive option, the results are presented in table form, and you can refine and drill into the data using the command line.

$ npx @appland/appmap inspect --interactive

Without the --interactive option, all matching results are printed as JSON. This mode is suitable for searching AppMaps and printing results that can be piped into other scripts (e.g. using jq) for further processing.

Interactive mode arguments

(h)ome

The home screen is displayed at the beginning of interactive mode. The (h)ome command will generally return you to the home screen, when you are in other parts of the app.

The home screen presents the following data:

Field index Field name Description
1 Events A list of AppMaps and event indices that match the initial search term and filters.
2 Return values Enumeration of all the different values returned by the matching object (most applicable when searching for a function).
3 HTTP server requests Distinct routes in which the code object is found. Each listed result is a unique request method, normalized path, and status code.
4 SQL queries Unique normalized SQL which is a descendant (or self) of the matching code object.
5 SQL tables Unique tables which are found in the SQL queries, as defined in field 4.
6 Callers Unique functions which are the parent of each matching code object.
7 Ancestors Unique HTTP server requests and labeled functions which appear as an ancestor of a matching code object.
8 Descendants Unique labeled functions which appear as a descendant of a matching code object.
9 Package trigrams Unique combinations of caller → code-object → calee, converted to package names.
10 Class trigrams Unique combinations of caller → code-object → calee, converted to class names.
11 Function trigrams Unique combinations of caller → code-object → calee, as functions, SQL, or HTTP client requests.

On the home screen, a field is displayed if there are only a small number of distinct values. Otherwise, the number of distinct values is shown, and you can use the (p)rint command to see the full details.

(p)rint

Prints the full details of a numbered field. Unlike the (h)ome view, which will summarize fields with many values, the (p)rint command will always print out all the distinct values of a field (even if there are thousands of them…).

(f)ilter

Applies a filter to the result set. You can use this command to reduce the number of search matches that are displayed, both on the (h)ome screen and in the (p)rint views.

When you choose the (f)ilter command, you’re first prompted to select which field you want to choose the filter value from. For example, you may see a table that includes (2) Return values (3) HTTP server requests (6) Callers. On choosing one of these fields, you are then prompted to select a value. The values will be the same as if you chose to (p)rint the selected field. Each field value is numbered; enter the number of the field value to activate it as a filter.

The result set is then recomputed, matching only events that match BOTH the main code-object argument that you initially provided to the search command, AND the filter.

For example, if you searched for table:users and then filtered by request:GET /user 200, the search would match every query that accesses the users table within an HTTP GET request to /user that returns status code 200.

If you apply another filter, then BOTH filter conditions must match each result.

(u)ndo filter

Un-apply the most recently applied filter.

(r)eset filters

Remove all filters.

(q)uit

Quit the interactive program.

OpenApi

Review the AppMap developer docs to learn more about Auto-Generating OpenAPI documentation

$ npx @appland/appmap openapi --help
  appmap openapi

  Generate OpenAPI from AppMaps in a directory

  Options:
        --version           Show version number                          [boolean]
    -v, --verbose           Run with verbose logging                     [boolean]
        --help              Show help                                    [boolean]
        --appmap-dir        directory to recursively inspect for AppMaps
                                                          [default: "tmp/appmap"]
    -o, --output-file       output file name
        --openapi-template  template YAML; generated content will be placed in the
                            paths and components sections
        --openapi-title     info/title field of the OpenAPI document
        --openapi-version   info/version field of the OpenAPI document

Use this command to generate OpenAPI documentation from all AppMaps in a directory (recursively explored).

openapi ships with a default yml template but you can use a custom template if you specify its file with the optional --openapi-template parameter.

The --openapi-title and --openapi-version parameters override the values of the info/title and info/version properties in the generated document.

Prune

Use this command to remove events from an AppMap, to make it have better performance, and to make it easier to understand.

Pruning works by finding the most repetitive calls in the map and then removing events associated with those calls. Non-application events such as HTTP requests and SQL queries will always be retained.

Usage

The prune command expects either a --size argument or a --filter argument. It will not work if neither are provided. Using the --size argument allows you to automatically shrink the AppMap file to a specified file size, while the --filter option allows you to specify what events to remove.

Arguments

You must provide either a --size argument or a --filter argument. You can find more information about the prune command by using the --help argument:

$ npx @appland/appmap prune --help
appmap prune <file>

Make an appmap file smaller by removing events

Positionals:
  file  AppMap to prune                                               [required]

Options:
      --version      Show version number                               [boolean]
  -v, --verbose      Run with verbose logging                          [boolean]
      --help         Show help                                         [boolean]
  -o, --output-dir   Specifies the output directory      [string] [default: "."]
      --format       How to format the output
                                     [choices: "json", "text"] [default: "text"]
  -s, --size         Prune input file to this size    [string] [default: "15mb"]
  -d, --directory    Working directory for the command                  [string]
      --filter       Filter to use to prune the map                     [string]
      --output-data  Whether to output all AppMap data or just output what was
                     removed                                           [boolean]
Prune to a specific file size

The simplest way to use the prune command is to provide a target size for the map. The prune command will automatically remove functions until the desired size is reached. Using the prune command in this way does not give you control over what gets removed, but often times the removed functions are relatively uninteresting (getters, setters, etc.).

Prune specific events

The most powerful way to use the prune command is to pass it specific instructions about which events to remove. This is done by using the --filter option. Here are the steps for using this technique:

  1. Open an AppMap in the code editor.
  2. Use the filtering available in the AppMap to hide certain events. AppMap Filtering
  3. Open the command pallette using CTRL+SHIFT+P or COMMAND+SHIFT+P on macOS, type AppMap: Copy Current AppMap State to Clipboard, then hit Enter.
  4. Use the copied state as the --filter argument to the prune command. The prune command will remove whatever was filtered in the AppMap in your code editor.
npx @appland/appmap prune <APPMAP_FILE> --filter eyJjdXJyZW50VmlldyI6InZpZXdTZXF1ZW5jZSIsImZpbHRlcnMi

GitHub repository

https://github.com/getappmap/appmap-js/tree/main/packages/cli


Was this page helpful? thumb_up Yes thumb_down No
Thank you for your feedback!