Splunk HEC Source

Overview

Splunk HEC Source is a push-based source that exposes a Splunk-compatible HTTP Event Collector (HEC) endpoint on the praxis-collector. Splunk Universal/Heavy Forwarders, syslog-to-HEC bridges, and any other HEC-compatible client can post events to the collector exactly as if it were a Splunk indexer.

Use it when you want to drop the praxis-collector in front of an existing Splunk forwarder fleet without reconfiguring the forwarders themselves — they keep posting to HEC and Praxis routes the events through your pipeline.

Supported types: Logs

Supported platforms: Linux, Windows, macOS

Minimum collector version: 0.3.0

Authentication

Token validation is delegated to the praxis-collector splunktokenauth extension and configured through pipeline credentials.

Credential type	When to use
Splunk Token (splunktoken)	All cases. The extension validates the inbound Authorization: Splunk <token> header against the configured token allowlist using a constant-time compare.

The collector and the extension are wired together automatically — when you bind a splunktoken credential to the source in the Praxis UI, the generated collector YAML includes a matching splunktokenauth/<instance> extension and the receiver references it via auth.authenticator. There is no access_tokens field on the receiver itself; tokens live on the extension config.

No backward compat note. Earlier collector versions accepted a bearertokenauth cred with scheme: Splunk overridden — that path is removed. Use splunktoken for all new and migrated pipelines.

Basic configuration

Parameter	Type	Required	Default	Description
endpoint	string (host:port)	Yes	0.0.0.0:8088	Listen address for the HEC server. The default matches Splunk's stock HEC port.
path	string	No	/services/collector	Base HEC path. Both <path> and <path>/event accept events; <path>/health returns receiver health.

advanced

Parameter	Type	Default	Description
max_request_body_size	integer (bytes)	52428800 (50 MiB)	Bodies larger than this return HTTP 400. Matches Splunk's HEC default.
tls.cert_file / tls.key_file	string	none	Server certificate and key for HTTPS. Required for TLS.
tls.ca_file	string	none	Optional CA bundle for client cert verification (mTLS).

Accepted payload formats

The receiver accepts the standard Splunk HEC JSON shapes:

• Single event — one JSON object with at least an event field.
• Concatenated stream — multiple JSON objects back-to-back, separated by whitespace or newlines (Splunk does NOT use a JSON array).

{ "time": 1714400000.5,
  "host": "web-1",
  "source": "/var/log/access.log",
  "sourcetype": "access_combined",
  "index": "main",
  "event": "GET /healthz 200",
  "fields": { "app": "shop", "status": 200 }
}

Output mapping

HEC field	OTel destination
event (string or nested JSON)	LogRecord.Body (string body for string events; JSON-stringified body for object events)
time (epoch seconds, integer or float)	LogRecord.Timestamp
host	Resource.Attributes["host"]
source	Resource.Attributes["source"]
sourcetype	Resource.Attributes["sourcetype"]
index	Resource.Attributes["index"]
fields.*	LogRecord.Attributes (typed: string / int / float / bool, with JSON-encoded fallback for nested values)

Response shape

Responses follow Splunk's HEC contract:

Outcome	HTTP	Body
Success	200	{"text":"Success","code":0}
Missing/invalid token	401	{"text":"Token is required","code":2}
Method not POST	405	{"text":"Method Not Allowed","code":6}
Empty / unparseable body	400	{"text":"...","code":5|6|7}
Downstream pipeline overloaded	503	{"text":"Server is busy","code":9}
Health probe (<path>/health)	200	{"text":"HEC is healthy","code":17}

Indexer acknowledgment (the ?channel= flow) is not supported in v1.

Example configuration

{
  "endpoint": "0.0.0.0:8088",
  "path": "/services/collector",

  "advanced": {
    "max_request_body_size": 52428800,
    "tls": {
      "cert_file": "/etc/praxis/hec.crt",
      "key_file": "/etc/praxis/hec.key"
    }
  }
}

Then attach a Splunk Token credential — its token value becomes one of the accepted HEC tokens. To accept multiple tokens, attach multiple splunktoken credentials; the generated extension carries them all in the validation allowlist.

Operational notes

• TLS is strongly recommended. HEC tokens travel in the Authorization header; without TLS they are exposed in transit. Configure advanced.tls for production.
• Existing Splunk forwarders. Point your forwarder's outputs.conf httpEventCollector stanza at the praxis-collector's <endpoint><path> URL and supply the same token you've configured on the splunktoken credential.
• Backpressure. When the downstream pipeline is full, the receiver returns HTTP 503 with code 9 — Splunk forwarders treat this as a transient error and retry per their own backoff policy.

Metrics

The HEC source emits the standard collector_source_* family (records received/dropped, errors, parse errors), and the underlying HTTP server emits the upstream otelcol_http_server_* request-level metrics (latency, status code, request size). All metrics carry the pipeline_name, pipeline_id, instance_uid, node_type, and node_name labels.