Metadata-Version: 2.4
Name: LoadStrike
Version: 1.0.30401
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
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=42.0.0
Provides-Extra: test
Requires-Dist: coverage[toml]>=7.6.0; extra == "test"
Requires-Dist: pytest>=8.3.0; extra == "test"
Requires-Dist: pytest-xdist>=3.6.1; 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 or later

## 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 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.

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.

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
