Requests recording can be disabled to force process recording

[kgilpin]

When requests recording is activated, process recording is disabled.

But in the case that the process recording is needed, request recording disables the process recording with no option to re-enabled it.

It would be sufficient for me to disable request recording with a command flag, leaving process recording enabled.

[kgilpin]

Problem: When request recording is activated, it disables process recording without providing an option to re-enable it or keep it enabled. We need a way to allow users to control this behavior.

Analysis:

The current implementation disables process recording whenever a request recording starts. This may not be desirable in all scenarios. Therefore, we need a mechanism to optionally keep process recordings enabled even when request recordings are activated.

By introducing a command-line flag or environment variable (e.g., APPMAP_KEEP_PROCESS_RECORDING), users can decide whether request recordings should disable process recordings or not. The relevant functions and logic across the application need to respect this flag, ensuring that the desired recording behavior is maintained based on user preferences.

Proposed Changes:

• src/recorder.ts:

  • Modify startRequestRecording to check for the new flag or environment variable before disabling process recording.
  • Adjust abandonProcessRecordingIfNotAlwaysActive to respect the new flag.
  • Ensure startProcessRecording and startRequestRecording functions correctly handle the new optional behavior.

• src/hooks/http.ts:

  • Update the logic within handleRequest and handleRemoteRecording functions to ensure they adhere to the new optional behavior.

• src/recorderControl.ts:

  • Implement any additional controls or flags necessary to manage the new behavior.

• src/facade.ts:

  • Include the logic to read and respect the new environment variable.

• test/smoketest.mjs:

  • Update smoke tests to cover scenarios where the new flag or environment variable is set.
  • Ensure tests verify that process recordings continue or stop based on the flag/state.

• src/__tests__/recorder.test.ts:

  • Add unit tests to ensure the functions respect the new flag/environment variable.
  • Verify that the new behavior works as expected in various recording scenarios.

By following these changes, the application will provide users with the flexibility to control whether process recording should be disabled when request recordings are started, ensuring better customization and user satisfaction.

[kgilpin]

Use APPMAP_RECORDER_PROCESS_ALWAYS

[kgilpin]

‌The variable APPMAP_RECORDER_PROCESS_ALWAYS is an environment variable used within the AppMap recorder for Node.js. When this variable is set, it allows multiple recordings to be active simultaneously. Specifically, it differentiates between two types of recordings:

1. Process Recording: Continuous recording of the entire process.
2. Other Recordings: This includes request, test, and remote recordings that can occur concurrently with the process recording.

Here’s how it functions in the code:

const processRecordingShouldAlwaysBeActive = "APPMAP_RECORDER_PROCESS_ALWAYS" in process.env;

Code Snippets Involving APPMAP_RECORDER_PROCESS_ALWAYS

1. Check if Process Recording Should Always Be Active:

   const processRecordingShouldAlwaysBeActive = "APPMAP_RECORDER_PROCESS_ALWAYS" in process.env;

2. Managing Process Recording:

   • Starting Process Recording:

     export function startProcessRecording() {
         if (!processRecording?.running)
             processRecording = new Recording("process", "process", new Date().toISOString());
     }

   • Abandon Process Recording If Not Always Active:

     export function abandonProcessRecordingIfNotAlwaysActive() {
         if (!processRecordingShouldAlwaysBeActive) processRecording?.abandon();
     }

3. Managing Other Types of Recordings:

   • Start Test Recording:

     export function startTestRecording(recorder: string, ...names: string[]): Recording {
         abandonProcessRecordingIfNotAlwaysActive();
         nonProcessRecording?.abandon();
         return (nonProcessRecording = new Recording("tests", recorder, ...names));
     }

   • Start Remote Recording:

     export function startRemoteRecording() {
         info("Remote recording started");
         abandonProcessRecordingIfNotAlwaysActive();
         nonProcessRecording?.abandon();
         nonProcessRecording = new Recording("remote", "remote", new Date().toISOString());
     }

   • Start Request Recording:

     export function startRequestRecording(pathname: string): string {
         abandonProcessRecordingIfNotAlwaysActive();
         const timestamp = new Date().toISOString();
         nonProcessRecording?.abandon();
         nonProcessRecording = new Recording("requests", "requests", [timestamp, pathname].join(" "));
         return timestamp;
     }

Usage Example in Configuration

In a documentation snippet, it might be set like this:

export APPMAP_RECORDER_PROCESS_ALWAYS=true
npx appmap-node your_script.js

This ensures that the process recording remains active while other types of recordings can start and stop without discontinuing the process recording.

[kgilpin]

flowchart TD
    A["Initialize AppMap Recorder (src/recorder.ts: various functions)"] --> B["Check APPMAP_RECORDER_PROCESS_ALWAYS (processRecordingShouldAlwaysBeActive)"]
    B -->|Yes| C["Allow simultaneous recordings"]
    B -->|No| D["Single active recording allowed"]

    C --> E["Process recording always active (startProcessRecording)"]
    C --> F["Allow test, request, and remote recordings (startTestRecording, startRequestRecording, startRemoteRecording)"]

    E --> G["Start process recording (startProcessRecording)"]

    F --> H["Start test, request, or remote recording (startTestRecording, startRequestRecording, startRemoteRecording)"]
    F --> I["End non-process recording when new recording starts (abandonProcessRecordingIfNotAlwaysActive)"]

    D --> H
    D --> I

This chart maps out the sequence of operations based on the state of the APPMAP_RECORDER_PROCESS_ALWAYS environment variable and annotates each step with relevant function names or modules associated with those operations.

Here are the key functions/modules:

• src/recorder.ts: Various functions related to recorder management.
• processRecordingShouldAlwaysBeActive: Variable in src/recorder.ts.
• startProcessRecording: Function in src/recorder.ts responsible for starting process recordings.
• startTestRecording, startRequestRecording, startRemoteRecording: Functions in src/recorder.ts responsible for starting different types of recordings.
• abandonProcessRecordingIfNotAlwaysActive: Function in src/recorder.ts to handle non-process recordings.

[kgilpin]

@petecheslock @zermelo-wisen ^^ useful for adding documentation of this flag