Introduction to Splunk HTTP Event Collector

Welcome to Splunk HTTP Event Collector (EC). The Event Collector is a new way to send data to Splunk Enterprise. Notably, the EC enables you to send data over HTTP (or HTTPS) directly to Splunk Enterprise from your application. The EC was created with application developers in mind, so that all it takes is a few lines of code added to an app for the app to send data. Also, the EC is token-based, so you never need to hard-code your Splunk Enterprise credentials in your app or supporting files. HTTP Event Collector provides a new way for developers to send application logging and metrics directly to Splunk Enterprise via HTTP in a highly efficient and secure manner.

How does HTTP Event Collector work?

The basics of Splunk HTTP Event Collector are relatively simple:

  1. Turn on the Event Collector in Splunk Enterprise by enabling the HTTP input endpoint. It is not enabled by default.
  2. From the Splunk Enterprise instance, generate an EC token.
  3. On the machine that will log to Splunk Enterprise, create a POST request, and set its authentication header to include the EC token.
  4. POST data in JSON format to the EC token receiver.

While you can send any kind of data to Splunk Enterprise through HTTP Event Collector, it must be contained within a JSON payload envelope. You can simplify the process by using a logging library, such as Splunk logging for Java or Splunk logging for .NET, which will automatically package and send data to HTTP Event Collector in the correct format. HTTP Event Collector also supports assigning different sourcetypes, indexes, and groups of indexers ("output groups"), so you can fine-tune where and how your data gets consumed by Splunk Enterprise. You can use Deployment Server to deploy HTTP Event Collector configuration files.

Following is a sample event in JSON format, created according to the HTTP Event Collector protocol. For more information about the contents of each event packet, see About the JSON event protocol in HTTP Event Collector.

{
    "time": 1426279439, 
    "host": "localhost",
    "source": "datasource",
    "sourcetype": "txt",
    "index": "main",
    "event": { "hello": "world" }
}

HTTP Event Collector data flow

Data is logged to HTTP Event Collector as follows:

  • On the data source, data is packaged using an agent such as:

    • A Splunk logging library (Splunk logging for Java or Splunk logging for .NET)
    • A JavaScript request library
    • The Java Apache HTTP client
    • Some other client, as long as the data is packaged in JSON according to the event protocol specification

  • Each JSON data package is assigned the same unique token in its authorization header, which has been generated using the management endpoint on the Splunk Enterprise instance using any of the following:

    • the HTTP Event Collector UI
    • cURL
    • Splunk Enterprise command-line interface (CLI)

  • The data package, each of which includes the token, is sent as an HTTP (or HTTPS) request to the data input endpoint on the Splunk Enterprise instance.
  • The token is verified against the list of known good tokens. If it's valid, an affirmative (OK) response is returned to the sender and the data package is consumed by Splunk Enterprise.
  • Splunk Enterprise sends the event data from the JSON packet payload to indexers to be indexed.

HTTP Event Collector work flow

There are three major workflows in HTTP Event Collector:

End user

An end user (third-party app developer, etc.) of HTTP Event Collector simply needs to add a few lines of code to his or her app to enable it to log to Splunk Enterprise. The easiest way to do this is to integrate the Splunk logging for Java or Splunk logging for .NET libraries into the app. If the user doesn't want to use one of the libraries, he or she must manually configure the app to send JSON in the correct format over HTTP (or HTTPS) to the HTTP Event Collector endpoint.

Token admin

The token admin can be the Splunk Enterprise admin or a different person who does not necessarily have experience with Splunk Enterprise. Tokens are required for HTTP Event Collector to accept data that is sent to it through its port. A token admin uses the Splunk Enterprise management UI or Command Line Interface (CLI) to create, edit, disable, enable, and remove tokens. The token admin can also use the REST API token management endpoints to directly edit token configurations, and can enable or disable the HTTP Event Collector endpoints themselves.

Enabling HTTP Event Collector on Splunk Enterprise also adds a new capability: edit_token_http specifically enables roles to create and edit HTTP Event Collector tokens.

Splunk Enterprise admin

On the Splunk Enterprise instance on which HTTP Event Collector is running, the Splunk Enterprise admin can choose what do with and where to send the data that is sent from clients. For example, the admin can specify indexes, sourcetypes, and output groups. To do this, the Splunk Enterprise admin edits the HTTP Event Collector endpoint.