HTTP Event Collector walkthrough

This topic introduces you to the way HTTP Event Collector works, and guides you through a simple exercise wherein you'll transmit some data and then search for it after it's been indexed by Splunk Enterprise or Splunk Cloud.

A different way to get data into Splunk Enterprise and Splunk Cloud

Getting data into Splunk Enterprise or Splunk Cloud using HTTP Event Collector is different from the other data input methods:

  1. Enable the feature. Doing so opens up the HEC port (8088 by default, though you can change that) and causes Splunk Enterprise or Splunk Cloud to start listening on it for incoming requests.

    Note: Managed Splunk Cloud customers can turn on HTTP Event Collector by filing a request ticket with Splunk Support.

  2. Generate an HTTP Event Collector authentication token ("HEC token"). HEC tokens are sent in the headers of incoming data packets (or as query strings) to authenticate them with Splunk Enterprise or Splunk Cloud. You generate a new token on your Splunk Enterprise or Splunk Cloud instance, and then give it to the sender of the data.

    Note: Managed Splunk Cloud customers can create a HEC token by filing a request ticket with Splunk Support.

  3. Send the data, using either HTTP Authentication (place the token in the authorization header of each HTTP request), Basic authentication (include a colon-separated user/password pair after -u"<user>":"<password>"—inserting the token as the <password>), or as a query string (append ?token= to the hostname and endpoint URL, followed by the token). or as a query string (append ?token= to the hostname and endpoint URL, followed by the token). If there is a problem, Splunk Enterprise or Splunk Cloud doesn't accept the data, and sends back a 401 (Unauthorized) status code to the sender.

If a request includes a valid, active token, Splunk Enterprise or Splunk Cloud accepts the request, sends back a 200 (OK) status code to the sender, and indexes the request's event data.

Note: Problems that you can encounter when sending data include: an invalid or missing token, incorrectly formatted JSON, an invalid timestamp, an invalid or disallowed index, and so on.

Event data format

You can send any kind of data to Splunk Enterprise through HTTP Event Collector, packaged either as raw text or within a JSON payload envelope. Here's a sample event in JSON format, created according to the HEC event protocol:

{
    "event": { "hello": "world" }
}

This is the simplest kind of event—one that contains just event data. You can also specify event metadata, such as a timestamp, a hostname, source and sourcetype values, and a preferred index.

You can also batch events. That is, you are not limited to one event per HTTP request; you can send multiple events in a single request and Splunk Enterprise or Splunk Cloud will index each event individually.

For more information about the event format that HEC accepts, including raw text and the JSON event format, see Format events for HTTP Event Collector.

Try HTTP Event Collector

Trying out HTTP Event Collector is easy. In this section we'll enable HEC, create a new HEC token, and then send some data.

First, enable HEC. Unless you've already used it, HEC is disabled by default. To enable it, in Splunk Enterprise and self-service or trial Splunk Cloud, go to Settings > Data inputs > HTTP Event Collector. Then click the Global Settings button in the upper-right corner. This will bring up the following configuration screen for HEC:

Event Collector Global settings page

Click the Enable button, and then click Save. You've just turned on HTTP Event Collector.

Note: Managed Splunk Cloud customers can turn on HTTP Event Collector by filing a request ticket with Splunk Support.

Now that HEC is turned on, create a new HTTP Event Collector token. From the HTTP Event Collector page, click the New Token button.

The Select Source screen of the Add Data workflow appears. This is where you name the HEC input, and optionally specify a description, a source field name to assign to all event data accepted with this input's token, and an output group (a named group of Splunk indexers). You can also enable indexer acknowledgement.

Event Collector New token page

An output group is a group of one or more destinations that forwards data. You define output groups in outputs.conf. For more information, see Configure forwarders with outputs.conf in the Forwarding Data manual. Indexer acknowledgement is acknowledgement from the indexer that an event has been indexed. For more information, see Enable indexer acknowledgement.

Enter at least a name for the input, and then click Next.

The Input Settings screen appears. On this screen, you determine how to assign a sourcetype field value to incoming data (either automatically, by specifying an existing one, or by creating a new one) and what indexes are allowed to index the data accepted with this input's token. You also specify the default index to use to index data bearing this input's token.

Event Collector New token input settings page

On the Input Settings page, leave the Source type as Automatic, and then choose at least one index that is not used for production, or real-world, purposes. Then, click Review. The Review page appears.

Event Collector New token Review page

Review your input settings, and then click Submit. You'll see a message that says, "Token input has been created successfully." A token value is simply a globally-unique identifier (GUID) that Splunk Enterprise has generated to identify data intended for this HEC input. You can click the token value from this screen and copy it to your Clipboard for later use, or go back to Settings > Data inputs > HTTP Event Collector, and you'll see that your new input is listed along with its token value and all its other pertinent information.

Select the entire token value, and then copy it to the Clipboard. Now we'll use it to send some data.

Open a command prompt window or terminal. Type the following cURL statement to test out your token. Be sure to replace <host> with your Splunk Enterprise or Splunk Cloud server's hostname, and <token> with the token you just copied to the Clipboard:

curl -k https://<host>:8088/services/collector -H 'Authorization: Splunk <token>' -d '{"sourcetype": "mysourcetype", "event":"Hello, World!"}' 

Alternatively, you can use Basic authentication, as shown here:

curl -k -u "x:<token>" https://<host>:8088/services/collector -d '{"sourcetype": "mysourcetype", "event":"Hello, World!"}'

Notes:

  • When creating requests to Splunk Cloud, you must add a prefix to the URI of the hostname according to your subscription. For self-service Splunk Cloud plans, pre-pend the hostname with input-. For all other Splunk Cloud plans, pre-pend the hostname with http-inputs-. In the previous example, the cURL statement would look like the following for self-service Splunk Cloud instances:
    curl -k https://input-<host>:8088/services/collector -H 'Authorization: Splunk <token>' -d '{"event":"Hello, World!"}' 
    And for all other Splunk Cloud instances:
    curl -k https://http-inputs-<host>:8088/services/collector -H 'Authorization: Splunk <token>' -d '{"event":"Hello, World!"}' 

  • Because of the way Windows handles single and double quotes, these cURL commands do not work on Windows. To get them to work on Windows, you can either replace the single quotation marks (') with double quotation marks (") and then escape the inner double quotation marks, or you can use an app like Postman for Google Chrome to send the request instead.

You should now see the following response:

{"text":"Success","code":0}

This means that Splunk Enterprise or Splunk Cloud has received the data. You can verify it's been received and indexed by searching in the search app.

Back in Splunk Enterprise or Splunk Cloud, on the Apps menu, click Search & Reporting. In the search box, type the following, making sure to replace <input_name> with the name you gave your input:

source="http:<input_name>" 

Press Return or Enter, and you'll see that Splunk Enterprise has found one event that corresponds to your input's name, similar to the following screen shot:

Search window showing the event