Troubleshooting AppMap Remote Recording in Tomcat

This document explains how AppMap's remote recording feature integrates with a Tomcat application and provides a guide to troubleshooting common issues.

How Remote Recording Works with Tomcat

AppMap's remote recording functionality is enabled by a Java agent that instruments your application at runtime. When used with a Tomcat application, the agent injects a javax.servlet.Filter named RemoteRecordingFilter into the application's filter chain. This filter is responsible for intercepting and handling HTTP requests related to remote recording.

Here's a step-by-step breakdown of the process:

1. Java Agent Attachment: The AppMap Java agent is attached to the Tomcat JVM using the -javaagent flag.
2. Instrumentation: The agent instruments the javax.servlet.ServletContext class to inject the RemoteRecordingFilter into the application's filter chain. This is done dynamically at runtime.
3. Request Interception: The RemoteRecordingFilter intercepts all incoming HTTP requests to the application.
4. Request Handling: The filter checks if the request URI matches the AppMap remote recording endpoints (/_appmap/record and /_appmap/record/checkpoint).
   • If the request is for a remote recording endpoint, the filter handles the request by calling the RemoteRecordingManager. The RemoteRecordingManager is responsible for starting, stopping, and managing recording sessions.
   • If the request is not for a remote recording endpoint, the filter passes the request on to the next filter in the chain, and eventually to the application.

This approach allows AppMap to control recording sessions without requiring any changes to the application's source code.

Troubleshooting Common Issues

Here are some common reasons why remote recording might fail to work for a specific application, and how to troubleshoot them:

1. AppMap Agent Not Attached

• Symptom: Remote recording endpoints are not available (e.g., return a 404 error).
• Troubleshooting:
  • Ensure that the -javaagent flag is correctly configured in your Tomcat startup script. The flag should point to the location of the AppMap agent JAR file.
  • Check the Tomcat logs for any errors related to the AppMap agent.

2. Unsupported Servlet Container or Class Loading Issues

• Symptom: The RemoteRecordingFilter is not injected into the filter chain.
• Troubleshooting:
  • Ensure that you are using a supported version of Tomcat and the Servlet API.
  • Check for any class loading issues in your application. If your application uses a complex class loader hierarchy, it's possible that the agent is unable to correctly instrument the ServletContext.

3. URL Conflicts

• Symptom: Requests to the remote recording endpoints are being handled by your application instead of the AppMap agent.
• Troubleshooting:
  • Ensure that your application does not have any servlets or controllers that are mapped to the /_appmap/record or /_appmap/record/checkpoint URLs.

4. Incompatible Custom Request/Response Objects

• Symptom: The RemoteRecordingFilter is unable to process requests due to incompatible request or response objects.
• Troubleshooting:
  • If your application uses custom HttpServletRequest or HttpServletResponse wrappers, they may not be compatible with the AppMap agent. The agent uses reflection to interact with these objects, and may not be able to handle custom implementations.

5. Security Framework Interference

• Symptom: A security framework (e.g., Spring Security) is blocking requests to the remote recording endpoints.
• Troubleshooting:
  • Configure your security framework to allow anonymous access to the /_appmap/record and /_appmap/record/checkpoint URLs.

6. Other Filter Interference

• Symptom: Another filter in the filter chain is interfering with the RemoteRecordingFilter.
• Troubleshooting:
  • Try changing the order of the filters in your web.xml file to ensure that the RemoteRecordingFilter is executed before any other filters that might interfere with it. The RemoteRecordingFilter is designed to have the highest precedence, but this can be overridden by other filters.