Websocket Server
WebSocket Server Sink
The WebSocket Server sink exposes a WebSocket server endpoint that allows external clients to connect and receive logs, metrics, or traces streamed directly from worker. Unlike the websocket sink (client mode), this component listens for incoming WebSocket connections and pushes events to connected clients.
It is suitable for:
- Real-time dashboards
- Custom consumers
- Streaming observability data to multiple downstream clients
- Fan-out delivery patterns
Core Sink Configuration
type
Required Defines the sink type.
- Must be set to websocket_server
- Puts worker into WebSocket server mode
inputs
Required List of upstream sources or transforms that send events to this sink.
- Accepts one or more component IDs
- Wildcards (*) are supported
address
Required Socket address that the WebSocket server listens on.
- Must include a port
- Listens on all interfaces or a specific interface
Examples
Acknowledgements
acknowledgements
Optional Controls end-to-end acknowledgement behavior for the sink.
acknowledgements.enabled
Optional Enables end-to-end acknowledgements.
- When enabled, sources that support acknowledgements wait until all connected sinks acknowledge the event
- Sink-level configuration overrides global acknowledgement settings
- Useful when reliability is more important than throughput
Authentication (auth)
Authentication applies to incoming WebSocket connection requests.
⚠️ Authentication headers are not encrypted unless TLS is enabled. Use authentication only with HTTPS / WSS.
auth.strategy
Required (when auth is configured) Authentication method used by the server.
Supported strategies:
- basic – HTTP Basic Authentication
- custom – Custom authentication using VRL
Basic Authentication
auth.username
Required Username for HTTP Basic authentication.
auth.password
Required Password for HTTP Basic authentication.
Behavior
- Client must send Authorization: Basic ... header
- Credentials are base64-encoded
Custom Authentication (VRL)
auth.source
Required A VRL boolean expression executed for each connection request.
- Has access to request metadata
- Must return true to allow the connection
- Returning false rejects the client
Typical use cases
- Header-based token validation
- Query parameter checks
- IP-based access control
Buffer Configuration
buffer
Optional Controls how events are queued before being sent to connected clients.
buffer.type
Optional Type of buffer used.
- memory (default) – Fast, volatile
- disk – Durable, survives restarts
buffer.max_events
Optional Maximum number of events stored in memory.
- Only applies when type = "memory"
- Default: 500
buffer.max_size
Required Maximum memory or disk space allowed for buffering.
- Disk buffers must be at least ~256 MB
buffer.when_full
Optional Behavior when the buffer is full.
- block (default) – Apply backpressure
- drop_newest – Drop incoming events
Encoding
encoding
Required Controls how events are serialized before being sent to WebSocket clients.
The selected codec also determines which signal types 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
Optional Pretty-print JSON output.
- Default: false
- Increases readability but adds overhead
CSV Encoding
encoding.csv.fields
Required Ordered list of fields to include in CSV output.
encoding.csv.delimiter
Optional Field delimiter character.
- Default: ,
encoding.csv.quote_style
Optional Controls when fields are quoted.
- necessary (default)
- always
- never
- non_numeric
CEF Encoding
Used primarily for SIEM integrations.
Required fields include:
- device_vendor
- device_product
- device_version
- device_event_class_id
- name
- severity
- version
- extensions
Protobuf Encoding
encoding.protobuf.desc_file
Required Path to the protobuf descriptor set file.
encoding.protobuf.message_type
Required Protobuf message type name.
encoding.protobuf.use_json_names
Optional Use camelCase JSON field names instead of snake_case.
- Default: false
Timestamp Formatting
encoding.timestamp_format
Optional Controls timestamp representation.
Options:
- rfc3339
- unix
- unix_float
- unix_ms
- unix_us
- unix_ns
Internal Metrics
internal_metrics
Optional Controls extra tags added to metrics generated by this component.
internal_metrics.extra_tags
Optional Defines additional metric tags.
internal_metrics.extra_tags.*.type
Defines how the tag value is derived.
Supported values:
- fixed – Static value
- header – Value from a request header
- query – Value from a query parameter
- ip_address – Client IP address
- url – Full request URL
internal_metrics.extra_tags.*.value
Required (for fixed) Static value assigned to the tag.
internal_metrics.extra_tags.*.with_port
Optional Include port when using ip_address.
- Default: false
Message Buffering (Replay Support)
message_buffering
Optional Enables message replay for clients that connect later.
- Uses a ring buffer
- Oldest messages are dropped when buffer is full
message_buffering.max_events
Optional Maximum number of messages stored for replay.
- Default: 1000
message_buffering.message_id_path
Optional Field path containing the message ID.
- Exposes the ID to clients
- Clients can request replay starting from a given ID
Client ACK Support (Advanced Replay)
message_buffering.client_ack_config
Optional Enables server-side tracking of client acknowledgements.
- Allows replay without query parameters
- Server tracks last acknowledged message per client
client_key
Identifies a client uniquely.
client_key.type
- ip_address (default)
- header
client_key.name
Required when type = "header" Header name used as the client identifier.
client_key.with_port
Include port when using IP-based identification.
message_id_path
Required Path to the message ID field used for ACK tracking.
ack_decoding
Defines how ACK messages from clients are decoded.
Supported codecs:
- bytes
- json
- protobuf
- avro
- gelf
- syslog
- influxdb
- otlp
- native
- native_json
- vrl
Each codec has its own optional lossy, schema, and validation settings.
Subprotocol Handling
subprotocol
Optional Controls Sec-WebSocket-Protocol negotiation.
subprotocol.type
Optional
- specific (default) – Only allow listed subprotocols
- any – Accept any client-requested subprotocol
subprotocol.supported_subprotocols
Optional List of allowed subprotocols when type = "specific".
TLS Configuration
tls.enabled
Optional Enables TLS for incoming connections.
- Required for wss://
tls.ca_file
Additional trusted CA certificates.
tls.crt_file
Server certificate.
tls.key_file
Private key for the certificate.
tls.key_pass
Passphrase for encrypted private keys.
tls.verify_certificate
Enforces client certificate validation.
tls.verify_hostname
Validates hostname against certificate CN/SAN.