--- title: Splunk HEC slug: telemetry-pipeline/splunk-hec docTags: createdAt: 2025-04-21T00:44:57.358Z --- # Splunk HTTP Event Collector (HEC) Source Receive log events using the Splunk HTTP Event Collector (HEC) API. This source allows worker to act as a Splunk HEC-compatible receiver. It exposes multiple HTTP endpoints that fully implement the Splunk HEC ingestion protocol, enabling Splunk clients, forwarders, or applications to send logs directly into worker. ## Supported Endpoints This source exposes the following Splunk HEC endpoints: - /services/collector/event – JSON event ingestion - /services/collector/raw – Raw text ingestion - /services/collector/health – Health check endpoint These endpoints behave consistently with Splunk’s native HEC implementation. ## Ingestion Model - Clients send log events using the Splunk HEC protocol - Events are authenticated using HEC tokens - Payloads are parsed and normalized into worker log events - Acknowledgements are tracked per channel (if enabled) - Events flow through the worker pipeline for processing and routing This makes the source suitable for replacing or fronting Splunk indexers. ## Reliability and Acknowledgements - Supports Splunk-style indexed acknowledgements - Tracks acknowledgement state per HEC channel - Clients can query acknowledgement status using HEC semantics - Designed for high-throughput and large-scale ingestion ## Source Configuration Parameters ## sources.\.type **required** **string** Specifies the source type. - Must be set to splunk\_hec ## Acknowledgement Configuration Controls how Splunk HEC acknowledgement channels are managed. ## sources.\.acknowledgements **optional** **object** Top-level acknowledgement configuration for the Splunk HEC source. ### sources.\.acknowledgements.enabled **optional** **bool** Enables end-to-end acknowledgements. - Required for Splunk HEC indexed acknowledgement support - Allows clients to query delivery status ### sources.\.acknowledgements.ack\_idle\_cleanup **optional** **bool** Controls whether idle acknowledgement channels are automatically removed. - A channel is considered idle if it is not used for: - Sending events - Querying acknowledgement status **Default** :::BlockQuote false ::: ### sources.\.acknowledgements.max\_idle\_time **optional** **uint** Maximum time, in seconds, a channel may remain idle before removal. - Channels may persist longer than this value - Clients should not rely on extended retention **Constraints** - Minimum value: 1 **Default** :::BlockQuote 300 ::: ### sources.\.acknowledgements.max\_number\_of\_ack\_channels **optional** **uint** Maximum number of acknowledgement channels supported. - Limits concurrent Splunk HEC clients - Prevents unbounded memory usage **Constraints** - Minimum value: 1 **Default** :::BlockQuote 1,000,000 ::: ### sources.\.acknowledgements.max\_pending\_acks **optional** **uint** Maximum number of pending acknowledgement statuses across all channels. - Equivalent to Splunk’s max\_number\_of\_acked\_requests\_pending\_query **Constraints** - Minimum value: 1 **Default** :::BlockQuote 10,000,000 ::: ### sources.\.acknowledgements.max\_pending\_acks\_per\_channel **optional** **uint** Maximum number of pending acknowledgements per individual channel. - Equivalent to Splunk’s per-channel acknowledgement limit **Constraints** - Minimum value: 1 **Default** :::BlockQuote 1,000,000 ::: ## Network Binding ## sources.\.address **optional** **string** The socket address on which the Splunk HEC server listens. - Must include a port - Binds to all interfaces by default **Default** :::BlockQuote 0.0.0.0:8088 ::: ## HTTP Keepalive Configuration Controls connection lifecycle behavior for HEC clients. ## sources.\.keepalive **optional** **object** Configures HTTP keepalive behavior. ### sources.\.keepalive.max\_connection\_age\_secs **optional** **uint** Maximum lifetime of an HTTP connection. - After this time, worker sends Connection: close - Applies to HTTP/0.9, HTTP/1.0, and HTTP/1.1 - Can be set to a very large value to disable rotation **Default** :::BlockQuote 300 ::: ### sources.\.keepalive.max\_connection\_age\_jitter\_factor **optional** **float** Adds randomness to the maximum connection lifetime. - Prevents synchronized reconnects - Helps reduce connection storms Example: - 0.1 → ±10% jitter **Default** :::BlockQuote 0.1 ::: ## Token Handling ## sources.\.store\_hec\_token **optional** **bool** Controls whether the incoming Splunk HEC token is preserved. - When enabled: - Token is stored in event metadata - Preferentially reused if forwarding to a Splunk HEC sink **Default** :::BlockQuote false ::: ## TLS Configuration Secures the Splunk HEC endpoint. ## sources.\.tls **optional** **object** Defines TLS behavior for incoming connections. ### sources.\.tls.enabled **optional** **bool** Enables TLS encryption. - Requires a server certificate ### sources.\.tls.crt\_file **optional** **string** Path to the server certificate file. - PEM, DER, or PKCS#12 formats supported - Required when TLS is enabled ### sources.\.tls.key\_file **optional** **string** Path to the private key file. - PEM or DER format - Required unless using PKCS#12 ### sources.\.tls.key\_pass **optional** **string** Passphrase for encrypted private keys. ### sources.\.tls.ca\_file **optional** **string** Additional CA certificates. - Used for client certificate validation ### sources.\.tls.verify\_certificate **optional** **bool** Enables certificate chain verification. - Ensures certificates are trusted and valid - Strongly recommended for production ### sources.\.tls.verify\_hostname **optional** **bool** Enables hostname verification. - Ensures certificate identity matches the expected host ### sources.\.tls.alpn\_protocols **optional** **array\[string]** List of supported ALPN protocols, in priority order. ## Authorization Tokens ## sources.\.token **optional** **string** **deprecated** Single authorization token. - Deprecated in favor of valid\_tokens ## sources.\.valid\_tokens **optional** **array\[string]** List of valid Splunk HEC authorization tokens. - Incoming requests must include one of these tokens - Tokens are provided via the Authorization header - If not set, requests are accepted without authentication ## Reliability Characteristics - At-least-once delivery semantics - Splunk-compatible acknowledgement model - High-throughput HTTP ingestion - Stateless processing - Backpressure-aware batching ## Common Use Cases - Replacing Splunk indexers at the edge - Fronting Splunk with a telemetry pipeline - Token-based multi-tenant ingestion - Log normalization before Splunk - Hybrid Splunk + non-Splunk backends