LoadStrike
Run Quick Start

Documentation / AWS SQS Endpoint

AWS SQS Endpoint

Use the AWS SQS endpoint when LoadStrike needs to publish to or consume from an SQS queue and correlate work that completes asynchronously.

What this page helps you do

What this page helps you do

Use the AWS SQS endpoint when LoadStrike needs to publish to or consume from an SQS queue and correlate work that completes asynchronously.

Who this is for

Teams defining the transport-specific source or destination side of a correlated transaction.

Prerequisites

  • A stable tracking field shared between the producer side and the consumer or completion side

By the end

A transport definition that matches the transaction you need to measure.

Run the quick start Understand transactions

Use this page when

Use this page when AWS SQS Endpoint is the source or destination side of the transaction and you need the documented endpoint fields before wiring the scenario.

Visual guide

AWS SQS endpoint flow showing produce mode, queue polling, message attributes, and correlation output.
AWS SQS endpoint fields connect source and destination traffic through the queue URL, region, message attributes, and body selectors.

Guide

Queue And Region

Configure QueueUrl and Region first. ServiceUrl is optional and is normally only used for local AWS-compatible environments such as LocalStack.

Produce And Consume

Produce mode sends the configured payload to the queue. Consume mode polls the same queue for messages that carry the tracking ID in a header-like message attribute or JSON body field.

Polling Behavior

WaitTimeSeconds controls SQS long polling, MaxNumberOfMessages controls the batch size, and VisibilityTimeoutSeconds can override queue visibility for the messages read by the run. DeleteAfterConsume defaults to true so consumed messages are removed after the run observes them.

Tracking Extraction

TrackingField and optional GatherByField use the same header or JSON selector syntax as other endpoints. SQS message attributes are treated like headers, and the message body is available for JSON selectors.

Endpoint definition samples

Use these samples to see how AWS SQS Endpoint is represented as a source or destination endpoint before you attach it to a correlated scenario.

If you run these examples locally, add a valid runner key before execution starts. Set it with WithRunnerKey("...") or the config key LoadStrike:RunnerKey.

AWS SQS Endpoint

using LoadStrike;

var tracking = new CrossPlatformTrackingConfiguration
{
    Source = new SqsEndpointDefinition
    {
        Name = "sqs-in",
        Mode = TrafficEndpointMode.Produce,
        TrackingField = TrackingFieldSelector.Parse("header:X-Correlation-Id"),
        QueueUrl = "https://sqs.us-east-1.amazonaws.com/123456789012/orders-started",
        Region = "us-east-1",
        MessageHeaders = { ["X-Correlation-Id"] = "ord-1001" },
        MessagePayload = new { orderId = "ord-1001", amount = 49.95m }
    },
    Destination = new SqsEndpointDefinition
    {
        Name = "sqs-out",
        Mode = TrafficEndpointMode.Consume,
        TrackingField = TrackingFieldSelector.Parse("header:X-Correlation-Id"),
        QueueUrl = "https://sqs.us-east-1.amazonaws.com/123456789012/orders-completed",
        Region = "us-east-1",
        WaitTimeSeconds = 5,
        MaxNumberOfMessages = 5
    }
};

var scenario = CrossPlatformScenarioConfigurator
    .Configure(LoadStrikeScenario.Empty("orders-sqs"), tracking)
    .WithLoadSimulations(LoadStrikeSimulation.Inject(10, TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(20)));

LoadStrikeRunner.RegisterScenarios(scenario)
    .WithRunnerKey("rkl_your_local_runner_key")
    .Run();

AWS SQS endpoint fields and parameters

Name

Required endpoint identifier. It appears in correlation tables, sink exports, and troubleshooting messages, so choose a stable descriptive name.

Mode

Choose Produce when LoadStrike should create traffic, or Consume when it should listen for downstream traffic. Run mode validation checks that the selected mode matches the source or destination role.

TrackingField

Selector that extracts the correlation id from a header or JSON body. It is normally required, but can be omitted when UseLoadStrikeTraceIdHeader is true so LoadStrike uses header:loadstrike-trace-id for generated source traffic. Selector prefixes such as header: and json: are parsed case-insensitively, but the header name or JSON path segments after the prefix must match exact casing. The extracted value is matched case-sensitively by default unless TrackingFieldValueCaseSensitive is turned off on the tracking configuration.

GatherByField

Optional destination-only selector used for grouped correlation reports. It follows the same selector-casing rules as TrackingField. Group values are grouped case-sensitively by default unless GatherByFieldValueCaseSensitive is turned off on the tracking configuration.

AutoGenerateTrackingIdWhenMissing

Defaults to true. When the source payload does not already contain the tracked id, LoadStrike can inject one so the generated traffic still produces a correlation key.

UseLoadStrikeTraceIdHeader

Defaults to false. When true and TrackingField is omitted, produced source messages receive a loadstrike-trace-id header with a GUID value. Consume-mode source endpoints and CorrelateExistingTraffic runs do not inject this header; they only observe it if the existing traffic already contains it.

PollInterval

Controls how often a consumer-style endpoint polls for new messages. The value must stay greater than zero whenever you set it explicitly.

MessageHeaders

Optional headers that are written with produced traffic and also influence tracking extraction when the selector targets headers. Header names are preserved exactly as you set them, and header selectors later match using that same exact casing.

MessagePayload

Optional object or body value sent by producer-style endpoints. This is the payload your scenario is actually placing on the wire.

MessagePayloadType

Optional type hint used when JSON selectors need typed parsing. Leave it unset when dynamic JSON parsing is enough.

JsonSettings / JsonConvertSettings

Optional serializer settings for System.Text.Json or Newtonsoft.Json. Use them only when the payload shape or naming strategy requires custom parsing behavior.

ContentType

Optional explicit content type for custom payload handling. This is most helpful for delegate-style transports or non-default HTTP body shapes.

QueueUrl

Required SQS queue URL used for produce or consume mode.

Region

Required AWS region for the queue.

ServiceUrl

Optional custom SQS-compatible service URL, commonly used for local development with LocalStack.

AccessKeyId / SecretAccessKey / SessionToken

Optional explicit AWS credentials. If AccessKeyId is set, SecretAccessKey must also be set. Leave these unset to use the normal AWS credential chain for the SDK runtime.

WaitTimeSeconds

SQS long-poll duration. It must stay between 0 and 20 seconds.

MaxNumberOfMessages

Maximum SQS messages read per poll. It must stay between 1 and 10.

VisibilityTimeoutSeconds

Optional visibility timeout override for messages read by the run. When configured, it must be zero or greater.

DeleteAfterConsume

Defaults to true. Keep it enabled when the test queue should be cleared as messages are observed.

{ "trackingId": "trk-1", "status": "completed" }
Related

Related category and article pages

Use these links to move from the reference page into the broader workload, integration, or article context.

Examples

Browse related docs and example entry points.