Skip to main content

Recording Mode

Recording mode captures actual function arguments during runtime so you can replay them in experiments with generated input variations.

When to Use Recording​

Use recording mode when:

  • Your agent function has complex signatures (WebSocket handlers, callbacks)
  • You want to replay real production scenarios
  • Testing requires specific argument combinations
  • Base inputs alone don't capture the full context

Enabling Recording​

From VSCode​

In the Experiments view, expand Recording (Advanced) and click Enable Recording.

From Terminal​

fluxloop record enable

This automatically:

  • Sets FLUXLOOP_RECORD_ARGS=true in .env
  • Enables replay_args.enabled in configs/simulation.yaml

Capturing Arguments​

  1. Ensure recording is enabled (check Experiments view → Recording (Advanced))

  2. Run your application as you normally would

  3. FluxLoop SDK captures arguments to recordings/args_recording.jsonl

Each line in the recording file contains:

{
  "function": "handle_request",
  "args": [],
  "kwargs": {"user_id": "123", "message": "Hello"},
  "timestamp": "2025-11-11T10:30:00Z"
}

Configuring Replay​

Edit configs/simulation.yaml to use recordings:

replay_args:
  enabled: true
  recording_file: "recordings/args_recording.jsonl"
  override_param_path: "kwargs.message"  # Where to inject generated inputs

override_param_path​

Specifies which field in the recorded arguments should be replaced with generated input variations:

  • "kwargs.message" – Replace kwargs["message"]
  • "args.0" – Replace first positional argument
  • "data.content" – Replace nested field kwargs["data"]["content"]

Running Experiments with Replay​

Once configured, run experiments normally:

FluxLoop: Run Experiment

FluxLoop will:

  1. Load recordings from recordings/args_recording.jsonl
  2. For each recording, create variations by replacing override_param_path with generated inputs
  3. Execute your agent function with the modified arguments
  4. Collect traces and results

Viewing Recording Status​

From Experiments View​

The Recording (Advanced) section shows:

  • Recording files from recordings/ directory
  • Click any file to open and inspect

From Terminal​

fluxloop record status

Disabling Recording​

From VSCode​

In the Experiments view, expand Recording (Advanced) and click Disable Recording.

From Terminal​

fluxloop record disable

This:

  • Sets FLUXLOOP_RECORD_ARGS=false in .env
  • Optionally disables replay_args in simulation config

Environment Considerations​

Recording and replay use the same Python environment as experiments.

Ensure Packages Are Available​

  1. Check environment:

    FluxLoop: Show Environment Info

  2. Ensure SDK is installed:

    source .venv/bin/activate
    pip install fluxloop

  3. Verify with Doctor:

    FluxLoop: Run Doctor

Using Different Environments​

If you recorded arguments in one environment but want to replay in another:

  1. Ensure both environments have compatible SDK versions
  2. Recording file paths are relative to project root
  3. Check that override_param_path matches your agent's signature in both environments

Example Workflow​

  1. Enable recording: In Experiments view → Recording (Advanced) → Enable Recording

  2. Run your app and capture arguments:

    python app/main.py
    # Interact with your agent to generate diverse argument patterns

  3. Check recordings:

    cat recordings/args_recording.jsonl

  4. Configure replay in configs/simulation.yaml:

    replay_args:
      enabled: true
      recording_file: "recordings/args_recording.jsonl"
      override_param_path: "kwargs.prompt"

  5. Generate inputs:

    FluxLoop: Generate Inputs

  6. Run experiment:

    FluxLoop: Run Experiment

  7. Disable recording when done: In Experiments view → Recording (Advanced) → Disable Recording

Troubleshooting​

Arguments Not Being Recorded​

  1. Verify .env contains FLUXLOOP_RECORD_ARGS=true
  2. Check that FluxLoop SDK is imported in your code
  3. Ensure the target function is decorated with @fluxloop.trace()
  4. Review application logs for SDK initialization messages

Replay Fails During Experiment​

  1. Check override_param_path matches your function signature

  2. Verify recording file exists:

    ls recordings/args_recording.jsonl

  3. Inspect recording format:

    head -1 recordings/args_recording.jsonl | python -m json.tool

  4. Run with verbose logging:

    fluxloop run experiment --verbose

Wrong Arguments Replayed​

  1. Ensure override_param_path points to the correct field
  2. Check that recordings match your current agent signature
  3. Clear old recordings if agent signature changed: 
    rm recordings/args_recording.jsonl
    fluxloop record enable
    # Re-record with updated signature

Next Steps​