Integration SQS Extension

Integration: Amazon SQS Extension

Track Amazon SQS operations in your test diagrams using the Kronikol.Extensions.SQS NuGet package. This extension intercepts SQS HTTP traffic via the AWS SDK's HttpClientFactory pipeline and logs operations for diagram generation.

Using a shared library or abstraction layer? If your code doesn't use the SQS SDK directly — e.g. it goes through MassTransit, a shared messaging library, or a custom abstraction — see the MassTransit Extension or Tracking Custom Dependencies for alternative approaches including MessageTracker and TrackingProxy<T>.

Installation

dotnet add package Kronikol.Extensions.SQS

Quick Start

using Amazon.SQS;
using Kronikol.Extensions.SQS;

var config = new AmazonSQSConfig
{
    RegionEndpoint = Amazon.RegionEndpoint.EUWest1
}
.WithTestTracking(new SqsTrackingMessageHandlerOptions
{
    ServiceName = "SQS",
    CallerName = "OrdersApi",
    Verbosity = SqsTrackingVerbosity.Detailed,
    CurrentTestInfoFetcher = () => (TestContext.CurrentTestName, TestContext.CurrentTestId)
});

var client = new AmazonSQSClient(config);

How It Works

The extension uses the same DelegatingHandler pattern as the S3 and DynamoDB extensions. WithTestTracking() injects a SqsTrackingMessageHandler via AmazonSQSConfig.HttpClientFactory, intercepting all HTTP requests made by the SQS SDK.

The handler:

1. Reads and classifies each request using SqsOperationClassifier
2. Reconstructs the request body so downstream processing is unaffected
3. Logs request/response pairs via RequestResponseLogger

Protocol Support

SQS supports two protocols:

Protocol	Detection	Example
JSON (modern)	X-Amz-Target: AmazonSQS.{Operation} header	AmazonSQS.SendMessage
Query (legacy)	Action={Operation} parameter in query string or form body	Action=ReceiveMessage

Both protocols are fully supported by the classifier.

Supported Operations

Operation	Enum Value
SendMessage	SqsOperation.SendMessage
SendMessageBatch	SqsOperation.SendMessageBatch
ReceiveMessage	SqsOperation.ReceiveMessage
DeleteMessage	SqsOperation.DeleteMessage
DeleteMessageBatch	SqsOperation.DeleteMessageBatch
ChangeMessageVisibility	SqsOperation.ChangeMessageVisibility
ChangeMessageVisibilityBatch	SqsOperation.ChangeMessageVisibilityBatch
CreateQueue	SqsOperation.CreateQueue
DeleteQueue	SqsOperation.DeleteQueue
GetQueueUrl	SqsOperation.GetQueueUrl
GetQueueAttributes	SqsOperation.GetQueueAttributes
SetQueueAttributes	SqsOperation.SetQueueAttributes
PurgeQueue	SqsOperation.PurgeQueue
ListQueues	SqsOperation.ListQueues

Unrecognised operations are classified as SqsOperation.Other.

Queue Name Extraction

The classifier extracts queue names from (in priority order):

1. URL path: /account-id/queue-name (e.g. https://sqs.us-east-1.amazonaws.com/123456789012/my-queue)
2. Body QueueUrl field: JSON body containing "QueueUrl": "https://.../{accountId}/{queueName}"
3. Body QueueName field: JSON body containing "QueueName": "my-queue" (used by CreateQueue)

FIFO queue names (e.g. orders.fifo) are preserved with the .fifo suffix.

Verbosity Levels

SqsTrackingVerbosity.Summarised

Minimal output for clean diagrams:

• Method label: Operation name (e.g. SendMessage)
• URI: sqs:///orders-queue
• Content: Omitted (both request and response)
• Headers: Omitted
• Other operations: Skipped entirely

SqsTrackingVerbosity.Detailed

Balanced output for debugging:

• Method label: Operation name (e.g. SendMessage)
• URI: sqs:///orders-queue
• Content: Included (request body and response body)
• Headers: Included (with default exclusions)

SqsTrackingVerbosity.Raw

Full HTTP-level output:

• Method: POST (actual HTTP method)
• URI: Original AWS endpoint URL
• Content: Full request/response bodies
• Headers: All headers (with default exclusions)
• Other operations: Included

Configuration Options

new SqsTrackingMessageHandlerOptions
{
    // Display name for this SQS instance in diagrams
    ServiceName = "SQS",

    // Name of the calling service in diagrams
    CallerName = "OrdersApi",

    // Verbosity level (default: Detailed)
    Verbosity = SqsTrackingVerbosity.Detailed,

    // Required: provides test context for log correlation
    CurrentTestInfoFetcher = () => (testName, testId),

    // Headers excluded from logging (defaults below)
    ExcludedHeaders = new HashSet<string>
    {
        "Authorization", "x-amz-date", "x-amz-security-token",
        "x-amz-content-sha256", "User-Agent", "amz-sdk-invocation-id",
        "amz-sdk-request"
    }
}

SqsTrackingMessageHandlerOptions

Property	Type	Default	Description
ServiceName	string	"SQS"	Display name in diagrams for the SQS service
CallerName	string	"Caller"	Calling service name in diagrams
Verbosity	SqsTrackingVerbosity	Detailed	Verbosity level (Raw, Detailed, Summarised)
CurrentTestInfoFetcher	Func<(string Name, string Id)>?	null	Required: provides test context for log correlation
CurrentStepTypeFetcher	Func<string?>?	null	Optional — returns the current BDD step type (Given/When/Then)
HttpContextAccessor	IHttpContextAccessor?	null	Optional — enables dual-resolution of test identity from HTTP headers. Auto-resolved by DI extensions (v2.26.3+). See HTTP Tracking Setup#Dual-Resolution Test Identity (v2.23.0+)
ExcludedHeaders	HashSet<string>	See above	Headers excluded from logging
SetupVerbosity	SqsTrackingVerbosity?	null	Verbosity override for the Setup phase. See Phase-Aware Tracking
ActionVerbosity	SqsTrackingVerbosity?	null	Verbosity override for the Action phase. See Phase-Aware Tracking
TrackDuringSetup	bool	true	When false, tracking is suppressed during Setup. See Phase-Aware Tracking
TrackDuringAction	bool	true	When false, tracking is suppressed during Action. See Phase-Aware Tracking

v2.23.0+ Dual-Resolution: SqsTrackingMessageHandler accepts an optional IHttpContextAccessor? httpContextAccessor constructor parameter for resolving test identity from HTTP request headers when running inside the SUT's request pipeline. v2.26.3+: Set HttpContextAccessor on SqsTrackingMessageHandlerOptions instead — the tracker reads it automatically. See HTTP Tracking Setup#Dual-Resolution Test Identity (v2.23.0+) for details.

ITrackingComponent

SqsTrackingMessageHandler implements ITrackingComponent and auto-registers with TrackingComponentRegistry on construction. This provides:

• ComponentName: "SqsTrackingMessageHandler ({ServiceName})"
• WasInvoked: true after first request
• InvocationCount: Total requests processed

URI Scheme

Classified requests use the sqs:/// URI scheme with the queue name in the path:

sqs:///orders-queue
sqs:///orders.fifo
sqs:///           (when queue name unavailable, e.g. ListQueues)

The path-based format (three slashes) preserves queue name casing, unlike host-based URIs which lowercase per RFC 3986.

See Also

• Integration: Amazon S3 Extension
• Integration: Amazon DynamoDB Extension
• Integration: Azure Service Bus Extension