Websocket
WebSocket Sink
The WebSocket sink delivers logs, metrics, or traces to a remote WebSocket listener using a persistent, bidirectional connection. It is suitable for real-time streaming of observability data to custom services, dashboards, or intermediate processors.
Core Sink Configuration
type
Required Defines the sink type.
- Must be set to websocket.
- Tells worker to open a WebSocket client connection and stream events.
inputs
Required List of upstream sources or transforms that send events to this sink.
- Accepts one or more component IDs.
- Wildcards (*) are supported.
Example
uri
Required The WebSocket endpoint to connect to.
- Must include protocol (ws:// or wss://)
- Can include host, port, path, query parameters
- wss:// requires TLS to be enabled
Example
Acknowledgements
acknowledgements
Optional Controls end-to-end delivery acknowledgements.
This determines whether worker waits for downstream confirmation before acknowledging events at the source.
acknowledgements.enabled
Optional Enables or disables end-to-end acknowledgements.
- When true, worker waits until all connected sinks acknowledge an event
- Takes precedence over global acknowledgement settings
- Only effective if upstream sources support acknowledgements
Default behavior
- Disabled unless explicitly enabled
Example
Authentication (auth)
The WebSocket sink supports HTTP-style authentication headers during the WebSocket handshake.
auth.strategy
Required (when auth is used) Defines the authentication method.
Supported values:
- aws – AWS SigV4 signing
- basic – HTTP Basic Authentication
- bearer – Bearer token (OAuth2, JWT, etc.)
- custom – Custom Authorization header value
Basic Authentication
auth.user
Required Username for basic authentication.
auth.password
Required Password for basic authentication.
Example
Bearer Authentication
auth.token
Required Bearer token value passed as-is.
Example
Custom Authorization Header
auth.value
Required Full value of the Authorization header.
Example
AWS Authentication (strategy = "aws")
Used when connecting to AWS-backed WebSocket endpoints requiring SigV4.
auth.service
AWS service name used for signing (e.g. execute-api).
auth.auth.access_key_id
AWS access key ID.
auth.auth.secret_access_key
AWS secret access key.
auth.auth.session_token
Optional temporary session token.
auth.auth.region
AWS region used for STS requests.
auth.auth.assume_role
IAM role ARN to assume.
auth.auth.session_name
Optional session identifier.
auth.auth.credentials_file
Path to AWS credentials file.
auth.auth.profile
Credentials profile name.
auth.auth.external_id
External ID for role assumption.
IMDS Configuration (AWS)
auth.auth.imds
Controls AWS IMDS authentication behavior.
- connect_timeout_seconds
- read_timeout_seconds
- max_attempts
Used when credentials are fetched dynamically from EC2 metadata.
Buffer Configuration
buffer
Optional Controls how events are queued before being sent.
buffer.type
Optional Buffer storage type.
- memory (default) – Fast, volatile
- disk – Durable, slower
buffer.max_events
Optional Maximum number of events in memory buffer.
- Only applies to memory buffers
- Default: 500
buffer.max_size
Required Maximum memory or disk space the buffer can consume.
- Disk buffers must be ≥ ~256MB
buffer.when_full
Optional Behavior when the buffer is full.
- block (default) – Apply backpressure
- drop_newest – Drop incoming events
Encoding
encoding
Required Defines how events are serialized before sending.
The selected codec determines which input types (logs, metrics, traces) are supported.
encoding.codec
Required Serialization format.
Supported codecs include:
- json
- text
- raw_message
- csv
- avro
- cef
- gelf
- protobuf
- otlp
- native
- native_json
- logfmt
JSON Encoding
encoding.json.pretty
Pretty-print JSON output.
- Default: false
CSV Encoding
encoding.csv.fields
Ordered list of fields to encode.
encoding.csv.delimiter
Field delimiter (default: ,).
encoding.csv.quote_style
Controls quoting behavior (necessary, always, never, non_numeric).
CEF Encoding
Includes:
- device_vendor
- device_product
- device_version
- device_event_class_id
- name
- severity
- extensions
Used mainly for SIEM integrations.
Protobuf Encoding
encoding.protobuf.desc_file
Path to descriptor set file generated by protoc.
encoding.protobuf.message_type
Protobuf message type to serialize.
encoding.protobuf.use_json_names
Use camelCase field names instead of snake_case.
Timestamp Formatting
encoding.timestamp_format
Controls timestamp representation.
Options:
- rfc3339
- unix
- unix_ms
- unix_us
- unix_ns
- unix_float
WebSocket Keepalive
ping_interval
Optional Interval (seconds) between WebSocket ping frames.
- Helps detect dead connections
ping_timeout
Optional Time to wait for a pong response.
- If exceeded, connection is re-established
- Ignored if ping_interval is not set
TLS Configuration
tls.enabled
Optional Enables TLS encryption.
- Required for wss:// URIs
tls.ca_file
Additional CA certificates.
tls.crt_file
Client/server identity certificate.
tls.key_file
Private key for the certificate.
tls.key_pass
Passphrase for encrypted private keys.
tls.server_name
SNI hostname used during TLS handshake.
tls.verify_certificate
Enables certificate chain validation.
tls.verify_hostname
Validates hostname against certificate SAN/CN.