You can improve the quality and accuracy of Navie AI by making AppMap Data for your project. Learn more about AppMap Data and how to make AppMap data by running your test cases or interacting with your application.
The AppMap process begins with the AppMap recording agent. This “agent” is a language-specific library - agents are available for Java, Python, Ruby and Node.js (Beta). You add the agent as a dependency of your project in the normal manner - via Maven, Gradle, Pip, Bundler, Yarn, etc. Then you configure your application to load the agent when the application runs.
Java | Python | Ruby | Node.js |
---|---|---|---|
-javaagent JVM option |
Django environment |
test and/or development bundle |
npx appmap-node yourapp |
Gradle plugin | Flask environment | ||
Maven plugin | FastAPI environment |
AppMap is designed primarily to record full details of your code, including parameters and return values, as well as I/O (especially SQL and HTTP client requests), it includes log statements, the execution stack, timing information, and exceptions. It captures all of this with minimal configuration. It’s designed primarily for non-production environments.
When you start your app with the AppMap agent enabled, it reads a configuration file called appmap.yml. This file serves several basic purposes. It tells the AppMap agent:
And it also tells other AppMap tools:
Note: In most environments, a default appmap.yml will be auto-generated by the AppMap agent if none exists.
AppMap Data is ordinary JSON files. As you record AppMap Data with test case recording, requests recording, or process recording, these JSON files are generated and written to the filesystem. The default location for AppMap Data is tmp/appmap
, relative to the process working directory. Be sure that you know that the working directory of the application server is! You’ll need to know this to find and open your AppMap Diagrams.
When you use remote recording, the HTTP “stop” command responds with the AppMap in the response payload. It’s up to the client to decide where to write the file. For example, you can start and stop a remote recording using cURL, and write the output of the “stop” command to a file of your choosing.
When you use code block recording, it’s up to you in your code snippet to write the AppMap to a file. Naturally, you can direct the data anywhere you please.
AppMap files conform to the AppMap specification, which is freely available on GitHub.
AppMap provides specialized support for recording test cases. When you run your test cases in a supported framework (there are many - see the language agent reference for details), a separate AppMap Diagram is created for each test case. AppMap Diagrams created from tests cases have some distinct features:
$appmap_dir/$test_framework
succeeded
or failed
) and any test failure message are stored in the AppMap.Recording the test suite of an application is a good way to quickly obtain a lot of data about an application. And because test cases work the same way for each build, recording test cases is also a good way to compare the behavior of application code across versions.
AppMap integrates with popular test frameworks, so you can automatically record an AppMap from each test case that you run.
Some benefits of test case recording include:
For details on test case recording, see:
For web applications, AppMap can be configured to record an AppMap for each HTTP server request handled by the app. This is a great way to collect data interactively. Just start the application with the AppMap language agent enabled, and start interacting with the app - manually, or using QA scripts or an API testing tool like Postman. AppMap Data is generated continuously as the application handles requests.
You can configure your application to record an AppMap of each HTTP server request.
Some characteristics of request recording include:
For details on requests recording, see:
Remote recording is similar to requests recording, in that:
But unlike requests recording, you control the boundaries of the AppMap, each AppMap can contain more than one HTTP server request, and it will also contain non-HTTP activity such as background jobs. To start a remote recording, you send an HTTP command to the AppMap agent running inside your application’s web stack to start recording. From that point on, everything that happens inside the application is recorded, until you send the “stop” command.
Remote recording enables you to create an AppMap while interacting directly with your app through the UI or API.
Some benefits of remote recording include:
For details on remote recording, see:
Some language agents enable you to make an AppMap by adding a simple code snippet to your code. This gives you total control over what’s recorded. The only downside of this is that you need access to the source code - which is not required by other recording methods. Refer to the AppMap Reference Guide for language specific configuration of this recording option.
Process recording is something of a last resort, when other recording methods aren’t available. When you run your application with process recording enabled, everything that happens in the code (as configured by the appmap.yml) is recorded, from process startup to shutdown. Refer to the AppMap Reference Guide for language specific configuration of this recording option.