WebSocket Endpoint
Use the WebSocket endpoint when a workflow uses WebSocket messages and the run should still report the tracked transaction outcome. Available on Pro and Enterprise plans.
Matching docs
Search across docs titles, summaries, groups, and section headings.
Use Up and Down Arrow to move through results, then press Enter to open the active page.
No indexed docs matched that search. Try a broader term or open the docs hub.
What this page helps you do
What this page helps you do
Use the WebSocket endpoint when a workflow uses WebSocket messages and the run should still report the tracked transaction outcome. Available on Pro and Enterprise plans.
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.
Use this page when
Use this page when WebSocket Endpoint is the source or destination side of the transaction and you need the documented endpoint fields before wiring the scenario.
Visual guide
Guide
Exact SDK Support
C#, Java, Python, TypeScript, JavaScript, and Go support native or delegate-backed WebSocket Produce and Consume. Python native endpoints require `pip install loadstrike[websocket]`; TypeScript and JavaScript native endpoints run on Node.js. A matching Produce or Consume delegate takes precedence over NativeClient.
Native Client Behavior
NativeClient can own connection setup, headers, subprotocol negotiation, text or binary sends, inbound message handling, expected-message matching, reconnect policy, cancellation, and close handling. Native Consume must use JSON tracking because WebSocket data frames do not carry message headers.
Java Compatibility Limits
Java accepts fragmented inbound frames up to a maximum of 1 MiB for the fully reassembled text or binary message. Its deprecated TrackPingPong, TrackCloseCodes, and TrackMessageLatency compatibility fields have no effect on protocol handling or metrics.
Connection Shape
Set Url, optional Subprotocols, ConnectTimeout, and CloseTimeout so the endpoint definition remains self-describing. Url must use ws:// or wss://.
Tracking Extraction
TrackingField and optional GatherByField use the same header or JSON selector rules as HTTP, broker, and delegate endpoints. Keep the tracked value stable in message headers or body fields.
Plan Gate
The WebSocket endpoint is available on Pro and above.
Endpoint definition samples
Use these samples to see how WebSocket 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.
WebSocket Endpoint
using LoadStrike;
using LoadStrike.CrossPlatform;
using LoadStrike.CrossPlatform.WebSockets;
// NativeClient is available for C# Produce and Consume endpoints.
var endpoint = new WebSocketEndpointDefinition
{
Name = "orders-websocket",
Mode = TrafficEndpointMode.Produce,
TrackingField = TrackingFieldSelector.Parse("header:x-tracking-id"),
Url = "wss://realtime.example.com/orders",
Subprotocols = ["orders.v1"],
MessageHeaders = new Dictionary<string, string>
{
["x-tracking-id"] = "ord-1001"
},
NativeClient = new WebSocketNativeClientOptions
{
Messages =
[
WebSocketMessageSpec.Text("{\"type\":\"subscribe\",\"orderId\":\"ord-1001\"}")
],
ExpectedMessages =
[
new WebSocketExpectedMessage
{
ContainsText = "ord-1001",
Timeout = TimeSpan.FromSeconds(10)
}
]
}
};
_ = endpoint;package main
import loadstrike "loadstrike.com/sdk/go"
// NativeClient works for Produce and Consume.
var webSocketEndpoint = &loadstrike.EndpointSpec{
Kind: "WebSocket",
Name: "orders-websocket",
Mode: "Consume",
TrackingField: "json:$.trackingId",
WebSocket: &loadstrike.WebSocketEndpointOptions{
URL: "wss://realtime.example.com/orders",
Subprotocols: []string{"orders.v1"},
NativeClient: &loadstrike.WebSocketNativeClientOptions{
Messages: []loadstrike.WebSocketMessageSpec{
loadstrike.TextWebSocketMessage(`{"type":"subscribe","trackingId":"ord-1001"}`),
},
ExpectedMessages: []loadstrike.WebSocketExpectedMessage{
{MatchText: "ord-1001", TimeoutSeconds: 10},
},
},
},
}import java.time.Duration;
import com.loadstrike.runtime.LoadStrikeCorrelation.TrackingFieldSelector;
import com.loadstrike.runtime.LoadStrikeTransports;
import com.loadstrike.runtime.WebSocketEndpointDefinition;
import com.loadstrike.runtime.WebSocketEndpointDefinition.ExpectedMessage;
import com.loadstrike.runtime.WebSocketEndpointDefinition.MessageSpec;
import com.loadstrike.runtime.WebSocketEndpointDefinition.NativeClientOptions;
// Java supports native WebSocket Produce and Consume.
var endpoint = new WebSocketEndpointDefinition();
endpoint.name = "orders-websocket";
endpoint.mode = LoadStrikeTransports.TrafficEndpointMode.Consume;
endpoint.trackingField = TrackingFieldSelector.parse("json:$.trackingId");
endpoint.url = "wss://realtime.example.com/orders";
endpoint.subprotocols = java.util.List.of("orders.v1");
var nativeClient = new NativeClientOptions();
nativeClient.messages.add(
MessageSpec.Text(
"{\"type\":\"subscribe\",\"trackingId\":\"ord-1001\"}"));
nativeClient.expectedMessages.add(
new ExpectedMessage(
"ord-1001", null, Duration.ofSeconds(10)));
endpoint.nativeClient = nativeClient;from loadstrike_sdk import (
WebSocketEndpointDefinition,
WebSocketExpectedMessage,
WebSocketMessageSpec,
WebSocketNativeClientOptions,
)
# Install with: pip install "loadstrike[websocket]"
endpoint = WebSocketEndpointDefinition(
name="orders-websocket",
mode="Consume",
tracking_field="json:$.trackingId",
url="wss://realtime.example.com/orders",
subprotocols=["orders.v1"],
native_client=WebSocketNativeClientOptions(
messages=[
WebSocketMessageSpec.Text(
'{"type":"subscribe","trackingId":"ord-1001"}'
)
],
expected_messages=[
WebSocketExpectedMessage(contains_text="ord-1001", timeout_seconds=10)
],
),
)import {
WebSocketEndpointDefinition,
WebSocketExpectedMessage,
WebSocketMessageSpec,
WebSocketNativeClientOptions
} from "@loadstrike/loadstrike-sdk";
// NativeClient works for Produce and Consume on Node.js.
const endpoint = new WebSocketEndpointDefinition({
Name: "orders-websocket",
Mode: "Consume",
TrackingField: "json:$.trackingId",
Url: "wss://realtime.example.com/orders",
Subprotocols: ["orders.v1"],
NativeClient: new WebSocketNativeClientOptions({
Messages: [WebSocketMessageSpec.Text('{"type":"subscribe","trackingId":"ord-1001"}')],
ExpectedMessages: [new WebSocketExpectedMessage({
ContainsText: "ord-1001",
TimeoutSeconds: 10
})]
})
});
void endpoint;const {
WebSocketEndpointDefinition,
WebSocketExpectedMessage,
WebSocketMessageSpec,
WebSocketNativeClientOptions
} = require("@loadstrike/loadstrike-sdk");
// NativeClient works for Produce and Consume on Node.js.
const endpoint = new WebSocketEndpointDefinition({
Name: "orders-websocket",
Mode: "Consume",
TrackingField: "json:$.trackingId",
Url: "wss://realtime.example.com/orders",
Subprotocols: ["orders.v1"],
NativeClient: new WebSocketNativeClientOptions({
Messages: [WebSocketMessageSpec.Text('{"type":"subscribe","trackingId":"ord-1001"}')],
ExpectedMessages: [new WebSocketExpectedMessage({
ContainsText: "ord-1001",
TimeoutSeconds: 10
})]
})
});
void endpoint;WebSocket endpoint fields and parameters
Required endpoint identifier. It appears in correlation tables, sink exports, and troubleshooting messages, so choose a stable descriptive name.
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.
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.
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.
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.
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.
Controls how often a consumer-style endpoint polls for new messages. The value must stay greater than zero whenever you set it explicitly.
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.
Optional object or body value sent by producer-style endpoints. This is the payload your scenario is actually placing on the wire.
Optional type hint used when JSON selectors need typed parsing. Leave it unset when dynamic JSON parsing is enough.
Optional serializer settings for System.Text.Json or Newtonsoft.Json. Use them only when the payload shape or naming strategy requires custom parsing behavior.
Optional explicit content type for custom payload handling. This is most helpful for delegate-style transports or non-default HTTP body shapes.
Required absolute ws:// or wss:// URL used by native or delegate-backed WebSocket Produce and Consume.
Optional WebSocket subprotocol names used during connection setup.
Maximum connection setup time. It must be greater than zero when configured.
Maximum shutdown time. It must be greater than zero when configured.
Supports native WebSocket Produce and Consume in C#, Java, Python, TypeScript, JavaScript, and Go. It owns connection, message, matching, reconnect, and close behavior unless a matching mode delegate is supplied. Python native use requires the websocket extra. Java limits each fully reassembled inbound text or binary message to 1 MiB.
Supported in C#, Java, Python, TypeScript, JavaScript, and Go; Go fields are Produce and Consume. Provide the delegate for the selected mode when an application client, authentication flow, or custom codec owns the WebSocket work; it takes precedence over NativeClient.
Deprecated TrackPingPong, TrackCloseCodes, and TrackMessageLatency remain readable for compatibility but have no effect and add no metrics.
Optional free-form dictionary for connection hints, tenant routing, or diagnostics.