You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/appmap-docs.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,7 +18,7 @@ By using AppMap data, Navie is the first AI code architect with the context to u
18
18
19
19
Over 90,000 software developers are using the [AppMap extension for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap) and the [AppMap plugin for JetBrains](https://plugins.jetbrains.com/plugin/16701-appmap).
You can also use Navie to review your code. This is a great way to get an overview of your codebase, identify potential issues, and improve the quality of your code.
71
+
Navie uses the same types of data to perform code review as it does for answering questions, including code snippets, sequence diagrams, traces, and other I/O data.
72
+
73
+
To start a code review, click the `Review Your Code` button in the Navie sidebar. This will generate a list of suggested improvements for your codebase, including:
74
+
75
+
76
+
77
+
- Potential bugs
78
+
- SQL query optimizations
79
+
- HTTP request optimizations
80
+
- Security vulnerabilities
81
+
- Performance improvements
82
+
- Code design improvements and anti-patterns
83
+
84
+
... and more. Because Navie uses AppMap Data, it can provide more accurate and relevant suggestions than other code review tools.
85
+
68
86
## Improve Navie AI Responses with AppMap Data
69
87
70
88
Generate AppMap Data and you will greatly improve the quality of your Navie AI responses. With AppMap Data for your project, you can now ask much deeper architectural questions about your application. This is possible because of the additional context from AppMap Data and the higher accuracy and relevance of the code snippets which are relevant to your question.
@@ -369,10 +376,18 @@ Next, open `Help` > `Show Log...` will open the IDE log file.
369
376
370
377
## Support
371
378
372
-
For help with your offline install of AppMap Navie, please open a new support request by emailing [support@appmap.io](mailto:support@appmap.io)
379
+
If you encounter startup issues with the VS Code extension, first check our [troubleshooting guide](/docs/troubleshooting/vscode) for solutions to common problems like:
380
+
- Linux GLIBC version compatibility requirements
381
+
- Windows temporary directory permissions
382
+
- Extension startup failures
373
383
374
-
Include the following information in your support request.
384
+
If you're still experiencing issues with your offline installation of AppMap Navie, please open a new support request by emailing [support@appmap.io](mailto:support@appmap.io)
375
385
386
+
Include the following information in your support request:
387
+
- Any error messages from the VS Code Output panel (AppMap: Services channel)
388
+
- Your operating system version and details:
389
+
- For Linux: output of `ldd --version`
390
+
- For Windows: OS build number and whether VS Code is running as administrator
376
391
- Company Name
377
392
- Code editor name and version (e.g. VS Code or JetBrains)
@@ -99,6 +103,167 @@ The installer changes your project's build process (yarn.lock for
99
103
JavaScript, Gemfile for Ruby, etc) to run AppMap when the tests run
100
104
and when developing locally. It will not be added to your production system.
101
105
106
+
## `index`
107
+
108
+
Use this command to compute fingerprints and update index files for all AppMap Data in a directory. Indexing also builds the query database (`query.db`) that the [`query`](#query) command reads.
109
+
110
+
### Usage
111
+
112
+
Run the command in your project directory. It will locate AppMap Data using the `appmap_dir:` setting in `appmap.yml` (or the `--appmap-dir` option), index every AppMap it finds, and exit:
113
+
114
+
```console
115
+
$ appmap index
116
+
```
117
+
{: .example-code}
118
+
119
+
The query database is stored outside of your project, at `~/.appmap/data/<sha>/query.db`, where `<sha>` is derived from the resolved path of the AppMap directory. Each AppMap directory therefore gets its own query database. You can override this location with the `--query-db` option.
120
+
121
+
Re-run `appmap index` after recording new AppMap Data to bring the index and query database up to date. Alternatively, use the `--watch` option to keep the indexer running continuously; it will index new and changed AppMap files as they appear:
122
+
123
+
```console
124
+
$ appmap index --watch
125
+
```
126
+
{: .example-code}
127
+
128
+
The `--port` option (which implies `--watch`) additionally starts a JSON-RPC server on the given port. This mode is used by the AppMap code editor extensions and Navie, and is not usually invoked directly.
129
+
130
+
### Arguments
131
+
132
+
```
133
+
appmap index
134
+
135
+
Compute fingerprints and update index files for all appmaps in a directory
136
+
137
+
Options:
138
+
--version Show version number [boolean]
139
+
-v, --verbose Run with verbose logging [boolean]
140
+
--help Show help [boolean]
141
+
-d, --directory program working directory [string]
142
+
--appmap-dir directory to recursively inspect for AppMaps
143
+
-w, --watch watch the directory for changes to appmaps [boolean]
144
+
-p, --port port to listen on for JSON-RPC requests [number]
145
+
--query-db path to query.db (overrides default
146
+
~/.appmap/data/<sha>/query.db) [string]
147
+
--log-navie Log Navie events to stderr [boolean] [default: false]
148
+
```
149
+
150
+
## `query`
151
+
152
+
Use this command to search and analyze indexed AppMap Data. `query` provides a family of subcommands ("verbs") that answer questions about recorded application behavior: which routes were exercised, which requests failed, which functions and SQL queries are slowest, how behavior differs between branches, and more.
153
+
154
+
`query` reads from the query database built by the [`index`](#index) command, so run `appmap index` first. If the query database is missing, `query` will exit with an error prompting you to build it.
155
+
156
+
### Query verbs
157
+
158
+
| Verb | Description |
159
+
|------|-------------|
160
+
|`endpoints`| Per-route summary table. A good first command for orienting yourself in a set of recordings. |
|`tree <appmap>`| Render the call tree of one recording. |
163
+
|`related <appmap>`| Rank recordings that are similar to the given recording. |
164
+
|`hotspots`| Rank functions or SQL queries by cumulative elapsed time. |
165
+
|`compare <branch-a> <branch-b>`| Per-route latency delta between two branches. |
166
+
|`mcp`| Run an MCP (Model Context Protocol) server on stdio that exposes the query verbs as tools, for use by AI assistants. |
167
+
|`ui`| Launch a local web UI for browsing the query database (dashboard, endpoints, hotspots, traces). |
168
+
169
+
Run any verb with `--help` for its full set of options:
170
+
171
+
```console
172
+
$ appmap query find --help
173
+
```
174
+
{: .example-code}
175
+
176
+
### Common options
177
+
178
+
Most verbs accept `--appmap-dir` (directory containing the AppMap Data) and `--query-db` (explicit path to the query database), as well as `--json` to emit machine-readable output instead of a formatted table. The `find` verb supports a rich set of filters, including `--route`, `--class`, `--method`, `--status`, `--duration`, `--branch`, `--commit`, `--since`, `--until`, and `--table`.
179
+
180
+
### Examples
181
+
182
+
Summarize all recorded routes:
183
+
184
+
```console
185
+
$ appmap query endpoints
186
+
```
187
+
{: .example-code}
188
+
189
+
Find failed requests:
190
+
191
+
```console
192
+
$ appmap query find requests --status ">=500"
193
+
```
194
+
{: .example-code}
195
+
196
+
Find SQL queries that touch the `users` table, as JSON:
197
+
198
+
```console
199
+
$ appmap query find queries --table users --json
200
+
```
201
+
{: .example-code}
202
+
203
+
Rank the slowest functions and SQL queries:
204
+
205
+
```console
206
+
$ appmap query hotspots
207
+
```
208
+
{: .example-code}
209
+
210
+
## `rpc`
211
+
212
+
Use this command to run the AppMap JSON-RPC server. The server exposes AppMap Data and Navie AI methods over JSON-RPC, and is the integration point used by the AppMap code editor extensions. You can also run it directly to integrate AppMap and Navie into your own tools and scripts.
213
+
214
+
### Usage
215
+
216
+
```console
217
+
$ appmap rpc
218
+
```
219
+
{: .example-code}
220
+
221
+
By default the server listens on a port chosen by the operating system (`--port 0`); the selected port number is printed to stdout on startup. Pass an explicit `--port` to use a fixed port.
222
+
223
+
The server provides JSON-RPC methods for:
224
+
225
+
- Searching AppMap Data and retrieving AppMap statistics, metadata, data, and sequence diagrams.
226
+
- Asking Navie AI questions about your application (`explain`), including managing conversation threads, message attachments, and pinned items.
227
+
- Getting and setting configuration, and listing and selecting Navie AI models.
228
+
229
+
To invoke a single RPC method from the command line without keeping a server running, use the companion `rpc-client` command:
Use this command to shrink AppMap files by truncating captured value strings — parameters, return values, receivers, log messages, and exceptions.
634
+
635
+
Unlike [`prune`](#prune), which removes events from an AppMap, `trim` keeps every event. Only the captured `value` strings are shortened; the call structure, code objects, SQL, and all other properties are untouched. A trimmed AppMap is therefore behaviorally identical to the original, but much smaller — which makes `trim` well suited to preparing AppMap Data for long-term storage, such as committing a baseline to a repository.
636
+
637
+
### Usage
638
+
639
+
Pass one or more AppMap files to trim. By default, each file is overwritten in place; use `--output-dir` to write the trimmed files to a different directory instead. The command reports the size reduction for each file:
640
+
641
+
```console
642
+
$ appmap trim tmp/appmap/minitest/*.appmap.json
643
+
trim tmp/appmap/minitest/Valid_login_redirect_after_login.appmap.json: 1548288 -> 216430 bytes (14%)
644
+
```
645
+
{: .example-code}
646
+
647
+
The `--max-length` option controls how aggressively values are truncated. Plain strings are capped at this length (default: 120 characters), while structured values (objects, arrays, hashes) are budgeted per field, so their overall shape remains readable.
648
+
649
+
### Arguments
650
+
651
+
```
652
+
appmap trim <files..>
653
+
654
+
Shrink AppMaps by truncating captured parameter, return, receiver, and message
655
+
values
656
+
657
+
Positionals:
658
+
files AppMap file(s) to trim [string]
659
+
660
+
Options:
661
+
--version Show version number [boolean]
662
+
-v, --verbose Run with verbose logging [boolean]
663
+
--help Show help [boolean]
664
+
--max-length Maximum length of a captured value string (structured
665
+
values are budgeted per field) [number] [default: 120]
666
+
-o, --output-dir Write trimmed AppMaps here (default: overwrite each file in
667
+
place) [string]
668
+
-d, --directory Working directory for the command [string]
669
+
```
670
+
466
671
## `archive`
467
672
468
673
Use this command to build a compressed archive of AppMap Data from a directory containing AppMap Data. Running this command without additional options will result in a "full" archive created at `.appmap/archive/full/{git revision}.tar`. Example: `.appmap/archive/full/028e610386f2fc132c93e613f57011825a8ae6e0.tar`
0 commit comments