LoadStrike
Customer Portal Request Demo

Documentation / Agents And Controller

Agents And Controller

Configure coordinator and agent nodes for local and distributed cluster execution with deterministic scenario targeting.

Why Use Cluster Mode

Cluster mode distributes workload across agent nodes and merges all node statistics into one final report. Use it when single-node capacity is not enough or when you want topology-aligned load generation.

Controller Role (Coordinator)

Coordinator plans scenario assignments, optionally executes coordinator-target scenarios, waits for agent results, aggregates node stats, and produces final reports.

Agent Role

Agent waits for coordinator run command, executes assigned scenarios only, and returns node stats to coordinator. In distributed mode, agent runs with reports and console metrics disabled by design.

Execution Paths

Local dev cluster path runs coordinator plus in-process child agents when NodeType is Coordinator and EnableLocalDevCluster is true. Distributed path uses NATS when NatsServerUrl is set. Python now routes both paths directly through LoadStrikeRunner.Run() / RunDetailed() rather than requiring a separate orchestration entry point.

Assignment And Targeting Rules

If AgentTargetScenarios is set then every agent runs the same explicit targets. Otherwise scenarios are distributed by scenario weight in round-robin. CoordinatorTargetScenarios controls scenarios that coordinator executes itself, and those coordinator-only targets are excluded from agent assignments.

Configuration Inputs

You can configure cluster settings via fluent API, JSON config keys under LoadStrike, or CLI args such as --NodeType, --ClusterId, --AgentGroup, --AgentsCount, --NatsServerUrl, --AgentTargetScenarios, and --CoordinatorTargetScenarios. NodeType parsing is strict and supports Single/SingleNode/Coordinator/Agent (or 0/1/2).

Timeout And Failure Behavior

ClusterCommandTimeout controls how long coordinator waits for distributed agent results. Missing agent responses are reported as cluster warnings and reflected in final run diagnostics.

Feature Usage Samples

How to use snippets for Agents And Controller.

Switch between C#, Java, Python, TypeScript, and JavaScript to see the native SDK shape for this sample.

Licensing note: every runnable sample requires a valid runner key via WithRunnerKey("...") or config key LoadStrike:RunnerKey.

Coordinator + Agent Configuration

LoadStrikeRunner
    .RegisterScenarios(httpScenario, kafkaScenario)
    .WithNodeType(LoadStrikeNodeType.Coordinator)
    .WithClusterId("orders-cluster")
    .WithAgentsCount(2)
    .WithCoordinatorTargetScenarios("http-source")
    .WithAgentTargetScenarios("kafka-consumer")
    .WithRunnerKey("rkr_your_remote_runner_key")
    .Run();

Cluster Config (appsettings.json)

NodeType

Chooses whether the process acts as a coordinator or an agent.

ClusterId

Must match across coordinator and agents so they participate in the same distributed run.

AgentGroup

Lets the coordinator target a specific pool of agents.

AgentsCount

Tells the coordinator how many agents it expects to participate.

NatsServerUrl

Specifies the NATS endpoint used for coordinator-agent communication.

Targeting options

Use TargetScenarios, AgentTargetScenarios, and CoordinatorTargetScenarios to split the workload across roles.

EnableLocalDevCluster

Runs a local coordinator with in-process child agents for development and smaller test setups.

{
  "LoadStrike": {
    "NodeType": "Coordinator",
    "ClusterId": "orders-cluster",
    "AgentGroup": "perf-agents",
    "AgentsCount": 3,
    "RunnerKey": "rkr_your_remote_runner_key",
    "NatsServerUrl": "nats://localhost:4222",
    "TargetScenarios": "http-source,kafka-consumer",
    "AgentTargetScenarios": "kafka-consumer",
    "CoordinatorTargetScenarios": "http-source",
    "ClusterCommandTimeoutMs": 120000,
    "EnableLocalDevCluster": false
  }
}

Diagram

Cluster orchestration visual
Coordinator and agents execute distributed workloads and merge node statistics into one run report.