LoadStrike 1.0.32301

LoadStrike SDK for .NET

LoadStrike is a developer-first load testing SDK for .NET applications, services, and automated test projects. Use it to model transaction flows in C#, execute them in-process, and capture structured run results from the same solution that owns the code under test.

What This SDK Is For

• Author scenario-based load tests in C#.
• Generate safe starter scenarios from captured HAR, OpenTelemetry trace JSON, browser recordings, or message pairs with Trace-to-test Autopilot.
• Model HTTP and event-driven transactions as multi-step workflows.
• Apply load simulations, thresholds, and custom metrics during execution.
• Split a single load profile across weighted scenario mixes.
• Generate local reports and, on Enterprise, publish 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 other supported sinks described below.

For cross-platform endpoints, gRPC requires a matching ProduceAsync or ConsumeAsync 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; when the matching delegate is present, it takes precedence over NativeClient.

Requirements

• .NET 8 or later

Install

dotnet add package LoadStrike

Quick Start

using System;
using System.Threading.Tasks;
using LoadStrike;

var scenario = LoadStrikeScenario.Create("orders", async context =>
{
    var step = await LoadStrikeStep.Run<string>(
        "publish-order",
        context,
        () => Task.FromResult(LoadStrikeResponse.Ok<string>(statusCode: "200")));

    return step.AsReply();
})
.WithDeclaredSteps("publish-order")
.WithLoadSimulations(
    LoadStrikeSimulation.Inject(10, TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(20))
);

var result = LoadStrikeRunner.RegisterScenarios(scenario)
    .UseLoadEngineV2()
    .WithMaxInFlight(5000)
    .WithRunnerKey("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 .UseLoadEngineV2() 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 .WithMaxInFlight(...) 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.

Call .WithDeclaredSteps(...) on a scenario when its named steps should have separate bounded V2 distributions, including zero-count series in distributed results. The declarations are signed into the distributed run plan; an agent with different declarations is rejected before load starts. Runtime step names that were not declared are retained in the scenario's typed <other> distribution instead of creating unbounded report series.

Generated HTML reports are self-contained offline files with responsive SVG charts. 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.

Records are buffered without delaying scenario callbacks and normally flush in compressed chunks every five seconds, bounded by 50,000 observations or 8 MiB. Portal delivery applies the same 50,000-observation and 8 MiB per-batch cap even when another sink supports larger batches. 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 with matching run arguments to select a bounded policy of zero through 100 retries. Recovered callbacks add no delivery warning or sink error; only failure that remains after the retry budget or reporting deadline is recorded. Custom sinks may receive the same delivery more than once and should handle repeats safely. Shutdown remains best effort, so 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.

Prometheus Remote Write, CloudWatch, Dynatrace, and New Relic sinks publish their provider-specific metric protocols. They apply the shared metric input limits, reject normalized key collisions before network I/O, and redact credentials from validation and delivery diagnostics.

ElasticsearchReportingSink and OpenSearchReportingSink post one JSON document per reporting call. IndexName defaults to loadstrike-runs. The public EndpointPath default of / signals automatic routing: unless the application explicitly supplies that option, the sink URL-escapes the index name and derives /{IndexName}/_doc. An explicitly supplied EndpointPath, including /, is the compatibility override and takes precedence.

When direct index routing is selected, IndexName 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 EndpointPath makes IndexName dormant, so the unused name is not validated.

KafkaReportingSink requires a nonblank Topic. When PublishAsync is omitted, set BootstrapServers and the SDK publishes through its Kafka producer; an explicit PublishAsync delegate takes precedence. StatsD, DogStatsD, and Netdata-compatible sinks similarly use SendLineAsync when supplied, otherwise they send UTF-8 UDP datagrams to Host and Port. A completed UDP send means only that the local UDP stack accepted the datagram; UDP provides no receiver acknowledgement and does not confirm delivery.

var kafka = new KafkaReportingSink(new KafkaReportingSinkOptions
{
    BootstrapServers = "kafka.example.com:9092",
    Topic = "loadstrike-reporting"
});

var statsd = new StatsDReportingSink(new StatsDReportingSinkOptions
{
    Host = "127.0.0.1",
    Port = 8125,
    Prefix = "loadstrike"
});

Expanded infra config can fill missing constructor values from the selected LoadStrike:ReportingSinks:* section. HTTP sinks accept BaseUrl, EndpointPath, TimeoutSeconds, Headers, and StaticTags, plus their credential or provider fields. Kafka accepts BootstrapServers and Topic; StatsD-family sections accept Prefix, Host, Port, and Tags (DogStatsD also accepts StaticTags); JSONL accepts FilePath. Only DogStatsD serializes tag maps; plain StatsD and Netdata do not append tag suffixes. Explicit code values win, dormant sections are ignored, and unknown selected keys report their full path without echoing secrets.

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 the payload to a vendor metric protocol.

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 by implementing ILoadStrikeIterationBatchSink. SaveIterationBatch receives immutable raw-attempt batches, and CompleteIterationObservationStream receives final delivery accounting before SaveRunResult.

Kafka OAuthBearer Client Credentials

For an OAuthBearer Kafka endpoint, provide the identity provider's token endpoint and client credentials. LoadStrike configures Confluent.Kafka's native OIDC client, which acquires and refreshes access tokens; the endpoint URL is never treated as a token.

Sasl = new KafkaSaslOptions
{
    Mechanism = KafkaSaslMechanismType.OAuthBearer,
    OAuthBearerTokenEndpointUrl = "https://identity.example.com/oauth/token",
    AdditionalSettings = new Dictionary<string, string>
    {
        ["ClientId"] = Environment.GetEnvironmentVariable("KAFKA_OAUTH_CLIENT_ID")!,
        ["ClientSecret"] = Environment.GetEnvironmentVariable("KAFKA_OAUTH_CLIENT_SECRET")!,
        ["Scope"] = "kafka.read kafka.write",
        ["GrantType"] = "client_credentials",
        ["Extensions"] = "tenant=orders"
    }
};

ClientId and ClientSecret are required. Scope, GrantType, and comma-separated Extensions are optional; when supplied, GrantType must be client_credentials. Existing native Confluent.Kafka OIDC keys such as sasl.oauthbearer.client.id, sasl.oauthbearer.client.secret, and sasl.oauthbearer.scope remain supported and take precedence over the friendly aliases. Keep credentials in a secret provider or environment variables rather than source control.

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.RegisterTrafficMix(...) or add it to a runner with .AddTrafficMix(...).

Trace-To-Test Autopilot

Use LoadStrikeAutopilot.Generate(...) to infer a starter plan from a captured artifact. Set LoadStrikeAutopilotOptions.RunnerKey so generation can validate the Trace-To-Test Autopilot entitlement. Check result.Readiness and result.ReadinessFailures first; call result.BuildScenario() 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 .WithRunnerKey(...) or through your application configuration before calling Run().

Documentation

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