Splunk HEC

Overview

Splunk HEC exports logs from a Praxis collector to Splunk using the HTTP Event Collector (HEC) API. It maps OpenTelemetry log records to HEC events and supports per-event index, source, sourcetype, and host metadata through resource attributes.

Supported types: Logs

Minimum collector version: 0.3.0 (splunktoken credential type required; collectors < 0.3.0 only support the deprecated bearertokenauth-with-scheme-override path.)

Note: HEC indexer acknowledgment is not supported in the current version. Retry and backpressure queue provide at-least-once style delivery; duplicates are possible if Splunk accepts a batch but the response is lost before the collector records success.

Authentication

Authentication is not embedded in the destination JSON; it is configured with pipeline credentials and attached to the destination node.

Credential type	When to use
Splunk Token (splunktoken)	All Splunk HEC tokens. The praxis-collector splunktokenauth extension stamps Authorization: Splunk <token> on every outbound request — the canonical HEC scheme.

Breaking change in collector 0.3.0. Earlier versions accepted a Bearer token credential with Auth scheme overridden to Splunk, plus an OAuth2 path. Both are removed. Operators upgrading from older collectors must rebind existing Splunk HEC destinations to a splunktoken credential — Praxis does not auto-migrate the binding.

Basic configuration

Parameter	Type	Default	Required	Description
endpoint	string	none	Yes	HEC base URL (scheme http or https plus host, and port if needed). The exporter posts to the collector path under this base. Examples: https://hec.example.com:8088, https://http-inputs-<tenant>.splunkcloud.com:443.

Event routing

Optional routing object maps resource attributes to Splunk metadata. When a given resource attribute is missing on a record, the corresponding default (if any) applies.

Parameter	Type	Default	Description
default_index	string	none	Index used when the index routing attribute is not set.
default_source	string	none	HEC source when the source routing attribute is not set.
default_sourcetype	string	none	HEC sourcetype when the sourcetype routing attribute is not set.
allowed_indexes	string[]	none	Indexes allowed for the index label on routing metrics. Events still go to the index selected by attributes; indexes outside this list are labeled _other in metrics only (to cap cardinality). If this list is empty, all per-index labels roll up to _other.
index_resource_attribute	string	com.splunk.index	Resource attribute that overrides the default index per event.
source_resource_attribute	string	com.splunk.source	Resource attribute for HEC source.
sourcetype_resource_attribute	string	com.splunk.sourcetype	Resource attribute for HEC sourcetype.
host_resource_attribute	string	host.name	Resource attribute for HEC host.

Advanced configuration

Parameter	Type	Default	Description
compression	string	gzip	Request body compression: gzip or none.
timeout	int	10	Per-request timeout in seconds (minimum 1).
max_content_length_logs	int	2097152	Maximum serialized HEC request body in bytes (2 MiB default). Large batches are split.
max_event_size	int	5242880	Maximum size of a single HEC event in bytes; larger events are dropped and counted.
startup_health_check	bool	true	On pipeline start, probe the HEC health URL; fail fast if the endpoint is unreachable or returns unauthorized.
health_path	string	/services/collector/health	Path for the health probe (used when startup_health_check is enabled).
splunk_app_name	string	Praxis Collector	Value sent in Splunk app identification headers.
splunk_app_version	string	none	Optional app version for the same headers.
retry_on_failure	bool	true	Enable automatic retries on send failures.
backpressure_queue	bool	true	Enable a sending queue (with optional disk backing) to absorb load.

TLS (advanced.tls)

Parameter	Type	Default	Description
insecure_skip_verify	bool	false	Skip TLS server certificate verification (not recommended in production).
ca_file	string	none	Custom CA bundle for verifying the server.
cert_file / key_file	string	none	Client certificate and key for mTLS.

Retry settings

When retry_on_failure is enabled, retry_on_failure_settings (under advanced) can include:

Parameter	Type	Default	Description
initial_interval	int	5	Initial backoff in seconds after a failure.
max_interval	int	30	Maximum backoff in seconds between attempts.
max_time_elapsed	int	300	Maximum time in seconds spent retrying a batch.

Backpressure queue settings

When backpressure_queue is enabled, backpressure_queue_settings (under advanced) can include:

Parameter	Type	Default	Description
queue_size	int	5000	Queue depth.
number_of_consumers	int	40	Parallel send workers.
enable_disk_backed_queue	bool	true	Persist queue data to disk for survival across restarts.

Example configuration

{
  "endpoint": "https://http-inputs-example.splunkcloud.com:443", // required

  "routing": {
    "default_index": "main",
    "default_sourcetype": "httpevent",
    "allowed_indexes": ["main", "security"],
    // "index_resource_attribute": "com.splunk.index",   // default
    // "source_resource_attribute": "com.splunk.source",  // default
    // "sourcetype_resource_attribute": "com.splunk.sourcetype",
    // "host_resource_attribute": "host.name",            // default
  },

  "advanced": {
    "compression": "gzip",
    "timeout": 10,
    "max_content_length_logs": 2097152,
    "max_event_size": 5242880,
    "startup_health_check": true,
    "health_path": "/services/collector/health",
    "splunk_app_name": "Praxis Collector",

    "tls": {
      "insecure_skip_verify": false,
    },

    "retry_on_failure": true,
    "retry_on_failure_settings": {
      "initial_interval": 5,
      "max_interval": 30,
      "max_time_elapsed": 300,
    },

    "backpressure_queue": true,
    "backpressure_queue_settings": {
      "queue_size": 5000,
      "number_of_consumers": 40,
      "enable_disk_backed_queue": true,
    },
  },
}

Attach a Splunk Token credential in the Praxis UI: paste the HEC token into the Token field. The praxis-collector handles the Authorization: Splunk <token> scheme automatically via the splunktokenauth extension.

Metrics

In addition to standard OpenTelemetry collector exporter and Praxis destination metrics (request latency, payload size, batch size, dropped records, retries, send duration, persistent queue where applicable), Splunk HEC exposes the following.

Metric name	Description
exporter_splunkhec_hec_errors	HEC errors bucketed by response/code (e.g. oversized events). Labels include hec_code and a bounded endpoint label.
exporter_splunkhec_auth_failures	Authentication failures, with auth_kind and status_code.
exporter_splunkhec_index_routed	Events counted per metric index label, bounded by allowed_indexes (unknown indexes use _other).
exporter_splunkhec_startup_health_check	Outcomes of the startup health probe, labeled by result.