AppMap is a powerful tool that helps developers understand and debug their code by recording its runtime behavior. This guide details the four primary methods for recording AppMap data: test recording, request recording, remote recording, and process recording. Understanding these methods will enable you to choose the most effective approach for your specific needs.
What it entails: Test recording is the most common and often recommended method for generating AppMaps. It integrates with your existing testing frameworks (like JUnit or TestNG for Java) to automatically create an AppMap for each test case that is executed. The AppMap agent is enabled when you run your tests, and it captures the code execution, including method calls, parameters, return values, and interactions with external services like databases and web services.
When to use it:
- Comprehensive Code Coverage: When you have a robust test suite that covers a significant portion of your application's functionality. This is the best way to get a broad and detailed overview of your application's behavior in a controlled environment.
- Continuous Integration (CI): Test recording is ideal for CI/CD pipelines. By generating AppMaps as part of your build process, you can track changes in application behavior over time and catch regressions.
- Comparing Behavior: Since tests are consistent, you can easily compare AppMaps generated from the same test case across different code versions to identify the impact of changes.
- Onboarding and Legacy Code: It provides an excellent way for developers to understand an existing codebase by visualizing the execution flow of established tests.
When not to use it:
- Lack of Tests: If your project has poor test coverage, this method will not provide a complete picture of your application.
- Manual or Exploratory Testing: Test recording is not suitable for scenarios where you need to explore the application manually to reproduce a specific bug or user interaction that is not covered by existing tests.
What it entails: Request recording automatically creates an AppMap for each HTTP server request that your application handles. When enabled, the AppMap agent monitors incoming web requests and records the entire execution path for each one, from the controller down to the database and back. This method is particularly useful for web applications and APIs.
When to use it:
- Interactive Testing: When you are manually testing your application through its web interface or API endpoints (using tools like Postman or cURL) and want to capture the behavior of specific interactions.
- API Documentation: Request recording can be used to generate OpenAPI documentation automatically based on the observed API requests and responses.
- Debugging Specific Endpoints: If you are working on a specific feature or trying to debug an issue with a particular API endpoint, request recording allows you to isolate and analyze that specific interaction.
When not to use it:
- Non-Web Applications: This method is not applicable to applications that do not handle HTTP requests, such as command-line tools or background workers.
- Complex User Flows: For user interactions that involve a sequence of multiple HTTP requests, remote recording is often a better choice as it can capture the entire flow in a single AppMap.
- CI/CD Automation: While possible to script, test recording is generally a more robust and repeatable solution for automated CI/CD environments.
What it entails: Remote recording gives you manual control over the start and stop of the recording process. You start your application with the AppMap agent attached, and then use a separate command or a browser extension to initiate and terminate the recording. This allows you to capture a specific user flow or a series of interactions within a single AppMap.
When to use it:
- Reproducing Bugs: When you need to manually reproduce a complex bug that involves a specific sequence of user actions.
- Feature Demonstrations: To create a visual representation of a new feature's functionality to share with other developers or stakeholders.
- Investigating Complex User Flows: For capturing and understanding user journeys that span multiple pages, API calls, and background processes.
- Applications Without Extensive Tests: If your application lacks a comprehensive test suite, remote recording provides a way to generate AppMaps for parts of the application that are not covered by tests.
When not to use it:
- Automated Environments: Due to its manual nature, remote recording is not well-suited for automated environments like CI/CD pipelines.
- Short, Isolated Interactions: For single HTTP requests or simple interactions, request recording is often a more straightforward and efficient choice.
What it entails:
Process recording captures the entire execution of a Java process from start to finish. You enable this by setting a system property (appmap.recording.auto=true) when you launch your application. The AppMap agent will record everything that happens in the configured packages until the process exits, at which point it will save the recording to a timestamped file.
When to use it:
- "Last Resort" Recording: When other recording methods are not suitable or have failed to capture the desired behavior.
- Startup and Shutdown Processes: To analyze the initialization and shutdown sequences of your application, which are often missed by other recording methods.
- Batch Jobs and Background Processes: For non-interactive applications or to capture the behavior of background jobs that are not triggered by user interactions.
When not to use it:
- Large and Long-Running Applications: Recording an entire long-running process can result in very large and unwieldy AppMap files that are difficult to analyze.
- Specific User Interactions: Process recording is not ideal for isolating and analyzing specific user interactions within a larger application flow. Remote recording or request recording are better suited for this purpose.
- Development and Debugging: For day-to-day development and debugging, the other recording methods offer more targeted and manageable ways to generate AppMaps.