Splunk HEC

Sends each record to a Splunk HTTP Event Collector (HEC).

Example

Reads the token from the worker-host variable SPLUNK_HEC_TOKEN. The URL is the collector's base address; the destination adds the endpoint path itself.

{
  "id": "splunk-out",
  "type": "splunkHec",
  "url": "https://splunk.example.com:8088",
  "token": "SPLUNK_HEC_TOKEN",
  "index": "smeltr_events",
  "sourcetype": "_json"
}

Before you start

  • Create a HEC token in Splunk and allow it to write to the target indexes.
  • Allow workers to reach the collector's port.
  • Put the token alone, without the Splunk prefix, in a credential.

Settings

It also takes the settings every destination takes.

url string required

The collector's base address. The destination adds the endpoint path itself, so an address naming /services/collector is refused.

Examples
https://splunk.example.com:8088https://http-inputs-acme.splunkcloud.com

token credential required

The credential holding the HEC token, without the Splunk prefix.

Examples
SPLUNK_HEC_TOKEN{"secret": "splunk-hec-token","version": 1}

endpoint string default event

Which HEC endpoint it sends to. See Event and raw endpoints.

event
Sends each record as the event of its own envelope.
raw
Sends each record as a line of text.

format string default json

What each event holds.

json
Writes the record as JSON.
text
Writes one field's text, from field.
bytes
Writes each source record's bytes as read, before pipeline processing, once per record: __source.bytes unless field names another bytes field. Only with endpoint raw.

field string default _raw for text, __source.bytes for bytes

The field each text or bytes record writes. Only with format text or bytes.

Example
message

index string default the token's default index

On the event endpoint, the index for a record with no __destination.index. On the raw endpoint, the index for every record: a record whose __destination.index names another is refused, so send it to the event endpoint.

Examples
mainfirewall

sourcetype string default none

On the event endpoint, the sourcetype for a record with no top-level sourcetype. On the raw endpoint, the sourcetype for every record.

Examples
_jsonpan:trafficaccess_combined

source string default none

On the event endpoint, the source for a record with no top-level source. On the raw endpoint, the source for every record.

Examples
smeltredge-gateway

host string default none

On the event endpoint, the host for a record with no top-level host. On the raw endpoint, the host for every record.

Examples
edge-110.0.3.7

acknowledgement string default indexer

When it counts a batch delivered. It must match the token's indexer acknowledgement setting.

indexer
Counts a batch delivered once Splunk reports it indexed.
receipt
Counts a batch delivered once Splunk accepts the request.

identity identity default none

The connection identity it connects under, for a private CA or a client certificate.

Examples
splunk-clientsplunk-ca

Advanced

inFlight integer default 4

How many requests it sends at once to start with. 1 to 64.

Examples
8116

maxRequestBytes size default 1 MiB

The most one request carries. A record larger than this still goes as a single record. 4 KiB to 100 MiB.

Examples
4 MiB512 KiB16 MiB

bufferBytes size default 64 MiB, or one request if that is larger

How much undelivered output it may hold. 4 MiB to 1 GiB, and at least one request.

Examples
256 MiB64 MiB1 GiB

stallAfterSecs integer default 30

Seconds one batch may take to deliver, its acknowledgement included, before it counts as stalled. 1 to 120.

Examples
60120

zoneUrls map default none

An address per zone. A worker in a listed zone sends there instead of url.

Examples
us-east-1a = https://splunk-a.example.com:8088us-east-1a = https://splunk-a.example.com:8088us-east-1b = https://splunk-b.example.com:8088

Fields it reads

FieldTypeHolds
__destination.indexstrThe index an Elasticsearch or Splunk HEC destination files the record under. Null means the destination's default index. A Splunk HEC destination on the raw endpoint refuses a record naming an index other than its own.

How it works

Event and raw endpoints

endpointWhat Splunk receives
event (default)Each record is the event of its own HEC envelope. A record's top-level _time, host, source and sourcetype file the event; the destination's settings fill in any it lacks. _time is Unix seconds or a datetime. __destination.index picks the index.
rawEach record is sent as one line of text. Every line gets the destination's index, host, source and sourcetype.

Acknowledgement

acknowledgementWhen a batch counts as delivered
indexer (default)Once Splunk reports the events indexed. Turn on indexer acknowledgement for the token. A record resent after a failure can arrive more than once.
receiptOnce Splunk accepts the request. Smeltr does not send it again. Turn indexer acknowledgement off for the token.

If the token's acknowledgement setting does not match, the destination reports it and delivers nothing until one of them changes. If Splunk refuses one event in a request, only that event is refused. Choose what happens to it →

Verify

Send a record with a unique marker through the source, then search the index for it in Splunk. Check the event's time, host, source and sourcetype.

Troubleshooting

The URL is refused
Give the base address, such as https://splunk.example.com:8088, not one ending in /services/collector.

See also