--- title: Websocket Server slug: telemetry-pipeline/websocket-server docTags: createdAt: 2025-04-21T01:03:55.567Z --- # 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** :::BlockQuote 0.0.0.0:80 127.0.0.1:9000 ::: ## 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**. :::BlockQuote ⚠️ 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.