Skip to main content

Recording Workflow

Capture real-world arguments from running services and replay them inside FluxLoop experiments.

1. Prerequisites​

  • FluxLoop project initialized (configs/ + .env)
  • Application code uses fluxloop.record_call_args(...) at the points you want to capture
  • Startup code calls fluxloop.load_env(...) and fluxloop.configure(...) to read recording environment variables (see record command)

2. Enable Recording​

fluxloop record enable

This toggles .env and configs/simulation.yaml to point at recordings/args_recording.jsonl (or your custom path). The CLI prints the resolved absolute path.

3. Restart / Run Your Service​

Ensure the service reloads configuration so the SDK sees FLUXLOOP_RECORD_ARGS=true.

Optional sanity check in code:

from pathlib import Path
fluxloop.load_env(Path(__file__).resolve().parents[2] / ".env")
config = fluxloop.get_config()
print("Recording?", config.record_args, config.recording_file)

4. Exercise Real Traffic​

  • Interact with your application (web UI, API calls, etc.)
  • Each call to fluxloop.record_call_args appends a JSONL entry with the kwargs
  • Sensitive keys are automatically masked (token/key/secret…)

5. Verify Output​

tail -f recordings/args_recording.jsonl

You should see _version, target, kwargs, and timestamp fields. If the file is empty, confirm the service imported .env before configure.

6. Disable Recording​

fluxloop record disable

Records stop appending, but the last file path remains for re-use. Keep the file under version control ignore rules.

7. Configure Replay for Experiments​

Edit configs/simulation.yaml to enable replay_args:

runner:
  target: "app.main:support_server.respond"
  stream_output_path: "message.delta"

replay_args:
  enabled: true
  recording_file: recordings/args_recording.jsonl
  override_param_path: "item.content.0.text"   # optional override of the user message

During experiments the CLI will:

  1. Load recorded kwargs
  2. Inject the runtime input at override_param_path
  3. Restore callable placeholders (collector callbacks)
  4. Execute your real code with the recorded structure

8. Run Experiment​

fluxloop generate inputs --limit 10   # optional refresher
fluxloop run experiment

Each generated input is replayed against the recorded argument skeleton, producing reproducible artifacts.

Tips​

  • Keep separate recording files per scenario (recordings/login.jsonl, recordings/support.jsonl, …)
  • Use versioned naming (e.g., args_2024-11-02.jsonl) for audit trails
  • If recordings are large, prune or sample before committing
  • Coordinate with CI/CD: disable recording in automated environments (FLUXLOOP_RECORD_ARGS=false)