Skip to main content
RELAMPO
Documentation
ENES

distributed run

Distributed execution lets you run one Relampo test across multiple nodes using GitHub Actions while keeping the workflow from your local machine.

Purpose​

Use relampo distributed run when you need to:

  • scale execution across multiple nodes
  • keep local control of YAML and data files
  • receive an aggregated result summary after completion
  • export local reports (json, html, csv, txt)

Before you start​

Required tools:

  • git
  • gh
  • relampo

You must also authenticate with GitHub.

Setup command:

relampo distributed setup

Or with a specific repository:

relampo distributed setup --repo owner/perf-tests
  1. Run setup to validate environment.
  2. Upload YAML and auxiliary files with files upload.
  3. Execute distributed run with run.
  4. Use files update when files change.
  5. Use files remove when files are no longer needed.

Upload files to the distributed repository​

Before running distributed tests, upload the scenario and required data files (such as CSV files).

--files must be a bracketed list:

relampo distributed files upload \
  --repo owner/perf-tests \
  --files "[/Users/me/test.yaml,/Users/me/users.csv]"
Windows tip

On Windows, replace \ with PowerShell backtick (`) or CMD caret (^). You can also run this command in a single line.

Run a distributed test​

Recommended entry command:

relampo distributed run /Users/me/test.yaml \
  --repo owner/perf-tests \
  --nodes 2 \
  --vus 10 \
  --duration 2m \
  --json /Users/me/Downloads/distributed-summary.json \
  --html /Users/me/Downloads/distributed-summary.html \
  --csv /Users/me/Downloads/distributed-summary.csv \
  --text /Users/me/Downloads/distributed-summary.txt
Windows tip

On Windows, replace \ with PowerShell backtick (`) or CMD caret (^). You can also run this command in a single line.

Main flags:

  • --repo
  • --nodes
  • --vus
  • --duration
  • --json, --html, --csv, --text

What Relampo does during execution​

When you trigger a distributed run, Relampo:

  • validates local YAML
  • validates GitHub tooling and auth
  • resolves or prepares the target repository
  • uploads the scenario
  • creates or updates the distributed workflow
  • commits/pushes only when changes exist

What you will see at the end​

Relampo shows:

  • repository preparation/update
  • workflow trigger
  • GitHub Actions URL
  • wait status
  • aggregated result table
  • summary line
  • per-node metrics

If local outputs are configured, Relampo also writes files in json, html, csv, and txt.

Where reports are saved​

  • If you pass an absolute path, the report is saved there.
  • If you pass only a filename, it is saved in the current directory.

Examples:

--html /Users/me/Downloads/report.html
--html report.html

Minimal example​

relampo distributed run /Users/me/test.yaml \
  --repo owner/perf-tests \
  --nodes 2 \
  --vus 10 \
  --duration 2m
Windows tip

On Windows, replace \ with PowerShell backtick (`) or CMD caret (^). You can also run this command in a single line.

Common errors​

  • gh not installed: Relampo cannot use GitHub CLI.
  • Not authenticated: run gh auth login and verify with gh auth status -h github.com.
  • Repository not accessible: verify owner/repo, permissions, and visibility.
  • Missing artifacts: check the GitHub Actions run and verify jobs published valid artifacts.