Metadata-Version: 2.4
Name: LoadStrike
Version: 1.0.31601
Summary: Python SDK for in-process load execution, traffic correlation, and reporting.
Author: LoadStrike
License-Expression: MIT
Project-URL: Homepage, https://loadstrike.com
Project-URL: Documentation, https://loadstrike.com/documentation
Keywords: load-testing,traffic-correlation,performance-testing,reporting
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.9.2
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=48.0.1
Provides-Extra: test
Requires-Dist: coverage[toml]>=7.6.0; python_version >= "3.10" and extra == "test"
Requires-Dist: pytest>=9.0.3; python_version >= "3.10" and extra == "test"
Requires-Dist: pytest-xdist>=3.6.1; python_version >= "3.10" and extra == "test"

# 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

```bash
pip install loadstrike
```

## Quick Start

```python
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 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