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, AWS SQS, native WebSocket, 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 other supported sinks described below.

gRPC endpoints require a matching synchronous or asynchronous Produce or Consume delegate. Without one, initialization fails with Native gRPC execution is not available in this SDK version. Provide the endpoint Produce/Consume delegate instead. WebSocket supports native or delegate-backed Produce and Consume; a matching delegate takes precedence over native_client.

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.
• The optional test extra and repository test suite support the same Python 3.9.2 floor.

Install

pip install loadstrike
pip install "loadstrike[kafka]"
pip install "loadstrike[rabbitmq]"
pip install "loadstrike[nats]"
pip install "loadstrike[redis]"
pip install "loadstrike[eventhubs]"
pip install "loadstrike[sqs]"
pip install "loadstrike[websocket]"
pip install "loadstrike[reporting]"
pip install "loadstrike[all-transports]"

Install native WebSocket support with pip install "loadstrike[websocket]". Install provider-protocol reporting dependencies for Prometheus Remote Write and CloudWatch with pip install "loadstrike[reporting]". pip install "loadstrike[websocket,reporting]" enables both. A native WebSocket endpoint without its extra fails with Install with pip install loadstrike[websocket] to use native WebSocket endpoints.

Choose only the extras your test needs. pip install "loadstrike[all-transports]" installs all six broker clients plus native WebSocket support. If a selected broker client is missing, LoadStrike reports the matching command—for example, Install with pip install loadstrike[kafka] to use the Kafka transport.—before starting that endpoint.

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.

HTML charts are responsive SVG graphics embedded in the offline report. They provide exact-value pointer, touch, and keyboard tooltips; outcome legends; zoom, pan, and reset; an accessible expanded view; chart-title search; and compact, comfortable, or spacious grids. Successful and failed latency stay separate, while All appears only when the run has a genuine combined distribution. When temporal history is available, cumulative requests, achieved request rate, bytes, and per-scenario latency include the final partial reporting interval. Correlation charts retain scenario, destination, status, GatherBy selector/value, and all available percentile points without averaging groups.

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 may receive the same delivery more than once and should handle repeats safely. 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.

Prometheus Remote Write sends Snappy-compressed protobuf; Amazon CloudWatch sends SigV4-signed PutMetricData requests; Dynatrace sends its metrics line protocol; New Relic sends Metric API JSON batches. These are metrics-first destinations. GenericWebhook instead sends generic LoadStrike reporting JSON. Prometheus Remote Write and CloudWatch require the reporting extra; Dynatrace and New Relic use the base installation. All four apply the shared metric input limits.

ElasticsearchReportingSink and OpenSearchReportingSink send one JSON document per reporting call. index_name defaults to loadstrike-events and produces /{index_name}/_doc. An explicitly supplied endpoint_path is the compatibility override and takes precedence. api_key creates Elasticsearch Authorization: ApiKey ...; username and password create OpenSearch Basic authorization.

For direct index routing, index_name must be nonblank lowercase text, at most 255 UTF-8 bytes, not . or .., and cannot start with -, _, or +. It rejects \ / * ? " < > |, ASCII space, comma, #, :, control characters, and malformed Unicode. Validation identifies the affected option or full configuration path without echoing the rejected value. An explicit endpoint_path makes index_name dormant, so the unused name is not validated.

Expanded infra config fills only missing values for sinks already selected in code. Use the LoadStrike:ReportingSinks:* sections with PascalCase keys or their documented snake-case aliases: HTTP keys include BaseUrl, EndpointPath, TimeoutSeconds, Headers, and StaticTags; provider keys include BearerToken, CloudWatch credentials/namespace/region, ApiToken, IndexName, ApiKey, Username, Password, LicenseKey, Webhook Url/Secret, Kafka BootstrapServers/Topic, StatsD-family Prefix/Host/Port/Tags, and JSONL FilePath. Explicit constructor values win and dormant sections are ignored. Unknown selected keys retain their full path in the error, while API keys, secrets, tokens, passwords, and sensitive header values are redacted.

GenericWebhook intentionally sends generic LoadStrike JSON, including gzip-compressed observation batches where applicable. Use it only with a receiver that accepts that body; it does not convert data to a vendor metric protocol. When migrating an old generic metrics URL, choose GenericWebhookReportingSink only for that generic contract and choose the matching direct sink when the receiver expects Prometheus, CloudWatch, Dynatrace, or New Relic.

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