LoadStrike SDK for Python

LoadStrike is a developer-first load testing SDK for Python services, jobs, and automated test suites. Use it to describe real workflows in Python, execute them in-process, and collect structured reports from the same codebase that owns the system under test.

What This SDK Is For

• Author scenario-based load tests in Python.
• Generate safe starter scenarios from captured HAR, OpenTelemetry trace JSON, browser recordings, or message pairs with Trace-to-test Autopilot.
• Model transaction flows across HTTP and event-driven systems.
• Apply load simulations, thresholds, and custom metrics during execution.
• Split a single load profile across weighted scenario mixes.
• Generate local reports and, on Enterprise, forward results to supported reporting sinks.

Built-in transport coverage includes HTTP, Kafka, RabbitMQ, NATS, Redis Streams, Azure Event Hubs, Push Diffusion, and delegate-based custom streams. Local report output supports HTML, Markdown, TXT, and CSV, and Enterprise can publish to InfluxDB, TimescaleDB, Grafana Loki, Datadog, Splunk HEC, OpenTelemetry Collector, and the expanded built-in sink family.

For Kafka OAuthBearer authentication, set oauth_bearer_token_endpoint_url and provide ClientId and ClientSecret in additional_settings. The native Python runtime exchanges those credentials for an access token and caches it until shortly before expiry; optional Scope, Audience, and GrantType values are included in the token request.

Requirements

• Python 3.9.2 or later. Python 3.9.0 and 3.9.1 cannot resolve the maintained cryptography dependency line; upgrade those installations before updating LoadStrike.
• Python 3.10 or later is required only for the optional test extra and the repository test suite. Python 3.9.2 remains supported for SDK consumers without that development-only extra.

Install

pip install loadstrike

Quick Start

from loadstrike_sdk import (
    LoadStrikeResponse,
    LoadStrikeRunner,
    LoadStrikeScenario,
    LoadStrikeSimulation,
    LoadStrikeStep,
)


def run_orders(context):
    return LoadStrikeStep.run(
        "publish-order",
        context,
        lambda: LoadStrikeResponse.ok("200"),
    ).as_reply()


scenario = (
    LoadStrikeScenario.create("orders", run_orders)
    .with_load_simulations(LoadStrikeSimulation.inject(10, 1, 20))
)

result = (
    LoadStrikeRunner.register_scenarios(scenario)
    .use_load_engine_v2()
    .with_max_in_flight(5000)
    .with_runner_key("rkl_your_runner_key")
    .run()
)

run() returns the detailed run result, including generated report files, scenario statistics, metrics, and sink status.

Load Engine V2

Call .use_load_engine_v2() explicitly for the versioned smooth-pacing and bounded-work contract. V2 runs registered scenarios concurrently, keeps final results in registration order, spreads fixed-rate arrivals across their interval, and uses one process-wide in-flight ceiling shared by scenarios and colocated logical agents. The default is 10,000; call .with_max_in_flight(...) after the V2 opt-in to override it with a value from 1 through 1,000,000.

The requested rate is offered scenario invocations per interval. Compare it with achieved starts, delivery percentage, scheduler lag, and transport throughput. If the generator is late or at capacity, the arrival is dropped and disclosed as a generator warning rather than counted as an application failure. One scenario invocation may contain several requests, Kafka records, or browser operations, so size Playwright workloads by browser capacity and report Kafka records and bytes per second separately.

V2 supports LoadStrikeTrafficMix with one deterministic global rank space across its weighted lanes and agent shards. Cross-platform tracking is not yet supported by the Python V2 profile and is rejected before traffic instead of running with partial accounting.

Non-correlated V2 scenarios can run through the local-development cluster or a remote NATS cluster. Give every agent a stable identity with .with_agent_id("agent-a"), and configure the coordinator with the same exact participant set using .with_agents_count(2).with_expected_agent_ids("agent-a", "agent-b"). Remote execution waits for that compatible set before starting; a missing result owner is reported as incomplete rather than silently producing a partial aggregate. Existing V1 cluster behavior is unchanged.

HTML reports include a Generator Delivery tab whenever scheduler delivery data, raw observation delivery statistics, generator or reporting warnings, or incomplete reporting are available. Results without reporting-completeness status show N/A rather than reporting loss. Application failures remain separate from generator and reporting warnings.

Raw Iteration Reporting

Observation-capable reporting sinks receive one compact record for every scenario attempt, including retry attempts and nested steps. Retries share a logical iteration ID while keeping distinct attempt indexes and final-attempt markers. Warm-up and load phases, simulation and shard identity, timestamps, observed and reported latency, outcome, status code, and response size are included; reply messages, payloads, bodies, and headers are not.

If a fail-mode runtime policy callback fails after an attempt begins, the stream receives one final failed observation with status runtime_policy_error before the run terminates. The observation does not include the callback error text.

Records are buffered without delaying scenario callbacks and normally flush in compressed chunks every five seconds. The defaults and portal-compatible common shape are 50,000 observations or 8 MiB; runs without a portal sink may select the documented larger limits. Buffer pressure, a single record that cannot fit a batch, and per-sink queue pressure drop reporting observations with explicit warnings; they do not turn a successful system-under-test response into an application failure. Metric-only destinations disclose that they cannot retain arbitrary strings or nested steps.

Every reporting-sink callback—including initialization, start, realtime statistics and metrics, final statistics and metrics, raw batches, completion markers, stop, and dispose—is attempted once and then retried up to three times by default, after 250 ms, 500 ms, and 1 second. Set SinkRetryCount and SinkRetryBackoffMs in LoadStrike configuration, or use the matching snake-case runner options, to select a bounded policy of zero through 100 retries. A recovered callback adds no final sink error or delivery-failed warning. Only an exhausted raw-observation delivery counts as sink observation loss; other exhausted callbacks are reported against that sink without failing the workload. Custom sinks have at-least-once delivery semantics and should deduplicate replay by stable batch or observation identity. Stop and dispose remain best-effort cleanup, and an exhausted stop callback does not prevent dispose. Sanitized nested exception details stay in the local run log rather than generator warnings, portable results, portal payloads, or HTML reports.

InfluxDB stores each attempt and nested step as a separate point, while TimescaleDB stores each as a separate row. Expanded HTTP event sinks transmit canonical gzip JSON batches. StatsD, DogStatsD, and Netdata-compatible sinks emit native per-attempt measurements plus stream-delivery counts instead of serializing a complete observation batch into one metric payload.

Portal reporting calculates cumulative p50, p75, p95, and p99 from all final load-phase outcomes received for each scenario and run. Separate successful and failed percentiles remain available for diagnosis. The SDK does not send SDK-calculated percentile fields as the authoritative portal or observation-capable sink result.

Custom reporting sinks opt in with save_iteration_batch or SaveIterationBatch and may implement the matching stream-completion callback. Existing aggregate lifecycle callbacks remain source compatible.

Built-in observability sinks also publish one correlation.outcome.final event for every gathered or ungrouped correlation row, including the tracking and event IDs, source and destination, status, latency, success state, and GatherBy field/value. The aggregate run.result.final event remains available separately.

Traffic Mixes

Use LoadStrikeTrafficMix on Pro and Enterprise plans when one total load profile should be distributed across multiple scenario lanes. For example, a 1000 requests-per-second profile with scenario weights of 60, 30, and 10 sends roughly 600 requests per second to the first scenario, 300 to the second, and 100 to the third.

Each lane is still a normal scenario with its own named steps, thresholds, reports, and portal results. Register the mix with LoadStrikeRunner.register_traffic_mix(...) or add it to a runner with .add_traffic_mix(...).

Trace-To-Test Autopilot

Use LoadStrikeAutopilot.generate(...) to infer a starter plan from a captured artifact. Set RunnerKey on the Autopilot options so generation can validate the Trace-To-Test Autopilot entitlement. Check result.Readiness and result.ReadinessFailures first; call result.build_scenario() only when it is LoadStrikeAutopilotReadiness.Ready, then execute the scenario through the normal runner with a valid RunnerKey.

Use SecretBindings to map redaction locations such as header:Authorization or body:$.client_secret to environment variables, TrackingSelector when the selector cannot be inferred, and EndpointBindings, AllowedReplayHosts, or BaseUrlRewrite when a replay target must be bound. Secret values are resolved when the generated scenario runs; they are not written into the generated plan. Any gate satisfied by user setup is omitted from ReadinessFailures.

Runner Keys

Runnable workloads require a RunnerKey. Supply it with .with_runner_key(...) or through your application configuration before calling run().

Documentation

• Product documentation: https://loadstrike.com/documentation