--- title: Websocket slug: telemetry-pipeline/websocket docTags: createdAt: 2025-04-21T01:03:50.169Z --- # 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** :::BlockQuote inputs: \- parse\_logs \- enrich\_metrics ::: ### 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** :::BlockQuote uri: ws\://localhost:8080/ingest ::: ## 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** :::BlockQuote acknowledgements: enabled: true ::: ## 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** :::BlockQuote auth: strategy: basic user: admin password: secret ::: ### Bearer Authentication auth.token **Required** Bearer token value passed as-is. **Example** :::BlockQuote auth: strategy: bearer token: eyJhbGciOiJIUzI1NiIs... ::: ### Custom Authorization Header auth.value **Required** Full value of the Authorization header. **Example** :::BlockQuote auth: strategy: custom value: "ApiKey abc123" ::: ### 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.