Splunk HEC
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.<id>.type
required string
Specifies the source type.
- Must be set to splunk_hec
Acknowledgement Configuration
Controls how Splunk HEC acknowledgement channels are managed.
sources.<id>.acknowledgements
optional object
Top-level acknowledgement configuration for the Splunk HEC source.
sources.<id>.acknowledgements.enabled
optional bool
Enables end-to-end acknowledgements.
- Required for Splunk HEC indexed acknowledgement support
- Allows clients to query delivery status
sources.<id>.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
sources.<id>.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
sources.<id>.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
sources.<id>.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
sources.<id>.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
Network Binding
sources.<id>.address
optional string
The socket address on which the Splunk HEC server listens.
- Must include a port
- Binds to all interfaces by default
Default
HTTP Keepalive Configuration
Controls connection lifecycle behavior for HEC clients.
sources.<id>.keepalive
optional object
Configures HTTP keepalive behavior.
sources.<id>.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
sources.<id>.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
Token Handling
sources.<id>.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
TLS Configuration
Secures the Splunk HEC endpoint.
sources.<id>.tls
optional object
Defines TLS behavior for incoming connections.
sources.<id>.tls.enabled
optional bool
Enables TLS encryption.
- Requires a server certificate
sources.<id>.tls.crt_file
optional string
Path to the server certificate file.
- PEM, DER, or PKCS#12 formats supported
- Required when TLS is enabled
sources.<id>.tls.key_file
optional string
Path to the private key file.
- PEM or DER format
- Required unless using PKCS#12
sources.<id>.tls.key_pass
optional string
Passphrase for encrypted private keys.
sources.<id>.tls.ca_file
optional string
Additional CA certificates.
- Used for client certificate validation
sources.<id>.tls.verify_certificate
optional bool
Enables certificate chain verification.
- Ensures certificates are trusted and valid
- Strongly recommended for production
sources.<id>.tls.verify_hostname
optional bool
Enables hostname verification.
- Ensures certificate identity matches the expected host
sources.<id>.tls.alpn_protocols
optional array[string]
List of supported ALPN protocols, in priority order.
Authorization Tokens
sources.<id>.token
optional string deprecated
Single authorization token.
- Deprecated in favor of valid_tokens
sources.<id>.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