Cribl LogStream – Docs

Cribl LogStream Documentation

Questions? We'd love to help you! Meet us in #Cribl Community Slack (sign up)
Download entire manual as PDF - v2.3.2

HTTP/S (Bulk API)

Cribl LogStream supports receiving data over HTTP/S using the Cribl Bulk API, Splunk HEC, or Elastic Bulk API.

📘

Type: Push | TLS Support: YES | Event Breaker Support: No

Configuring Cribl LogStream to Receive Data over HTTP(S)

Select Data > Sources, then select HTTP from the Data Sources page's tiles or left menu. Click Add New to open the New HTTP source pane, which provides the following fields.

General Settings

Input ID: Enter a unique name to identify this HTTP(S) Source definition.

Address: Enter the hostname/IP on which to listen for HTTP(S) data. (E.g., localhost or 0.0.0.0.)

Port: Enter the port number.

Auth tokens: Shared secrets to be provided by any client (Authorization: <token>). Click Generate to create a new secret. If empty, unauthenticated access will be permitted.

Cribl HTTP event API: Absolute path on which to listen for Cribl HTTP API requests. Currently, the only supported option is the default /cribl, which LogStream expands as /cribl/_bulk. Use an empty string to disable. Maximum payload size is 2MB.

Elastic API endpoint (for Bulk API): Absolute path on which to listen for Elasticsearch API requests. Currently, the only supported option is the default /elastic, which LogStream expands as /elastic/_bulk. Other entries are faked as success. Use an empty string to disable.

📘

Cribl generally recommends instead using the dedicated Elasticsearch API Source. The Elastic API implementation here is provided for backward compatibility, and for users who want to ingest multiple inputs on one HTTP/S port.

Splunk HEC endpoint: Absolute path on which to listen for Splunk HTTP Event Collector (HEC) API requests. Use an empty string to disable. Default entry is /services/collector.

Splunk HEC acks: Whether to enable Splunk HEC acknowledgements. Defaults to No.

📘

This Splunk HEC implementation is an event (i.e., not raw) endpoint. For details, see Splunk's documentation. To send data to it from a HEC client, use either /services/collector or /services/collector/event. (See the examples below.)

Cribl generally recommends instead using the dedicated Splunk HEC Source. The Splunk HEC implementation here is provided for backward compatibility, and for users who want to ingest multiple inputs on one HTTP/S port.

TLS Settings (Server Side)

Enabled defaults to No. When toggled to Yes:

Certificate name: The name of the predefined certificate.

Private key path: Server path containing the private key (in PEM format) to use. Path can reference $ENV_VARS.

Passphrase: Passphrase to use to decrypt private key.

Certificate path: Server path containing certificates in (PEM format) to use. Path can reference $ENV_VARS.

CA certificate path: Server path containing CA certificates (in PEM format) to use. Path can reference $ENV_VARS.

Authenticate client (mutual auth): Require clients to present their certificates. Used to perform mutual authentication using SSL certs. Defaults to No. When toggled to Yes:

  • Common name: Regex matching peer certificate subject common names allowed to connect. Defaults to .*.

Validate client certs: Require server to reject any connection that is not authorized with the list of supplied CAs. Defaults to No.

Processing Settings

Fields (Metadata)

In this section, you can add fields/metadata to each event using Eval-like functionality.

Name: Field name.

Value: JavaScript expression to compute field's value (can be a constant).

Pre-Processing

In this section's Pipeline drop-down list, you can select a single existing Pipeline to process data from this input before the data is sent through the Routes.

Internal Fields

Cribl LogStream uses a set of internal fields to assist in handling of data. These "meta" fields are not part of an event, but they are accessible, and Functions can use them to make processing decisions.

Fields for this Source:

  • __inputId
  • __id (Elastic In)
  • __type (Elastic In)
  • __index (Elastic In)
  • __host (Elastic In)

Format and Endpoint

LogStream expects HTTP(S) events to be formatted as one JSON record per event. Here are two event records:

{"_time":1541280341, "_raw":"this is a sample event ", "host":"myHost", "source":"mySource", "fieldA":"valueA", "fieldB":"valueB"}
{"_time":1541280341, "host":"myOtherHost", "source":"myOtherSource", "_raw": "{\"message\":\"Something informative happened\", \"severity\":\"INFO\"}"}

Note 1: Events can be sent as separate POSTs, but Cribl highly recommends combining multiple events in newline-delimited groups, and POSTing them together.

Note 2: If an HTTP(S) source is routed to a Splunk destination, fields within the JSON payload are mapped to Splunk fields. Fields that do not have corresponding (native) Splunk fields become index-time fields. For example, let's assume we have a HTTP(S) event like this:

{"_time":1541280341, "host":"myHost", "source":"mySource", "_raw":"this is a sample event ", "fieldA":"valueA"}

Here, _time, host and source become their corresponding fields in Splunk. The value of _raw becomes the actual body of the event, and fieldA becomes an index-time field. (fieldA::valueA).

Examples

For the following examples:

  1. Configure Cribl to listen on port 10080 for HTTP (default). Set authToken to myToken42.
  2. Send a payload to your Cribl LogStream receiver.

Cribl Endpoint – Single Event

curl -k http://<myCriblHost>:10080/cribl/_bulk -H 'Authorization: myToken42' -d '{"_raw":"this is a sample event ", "host":"myHost", "source":"mySource", "fieldA":"valueA", "fieldB":"valueB"}'

Cribl Endpoint – Multiple Events

curl -k http://<myCriblHost>:10080/cribl/_bulk -H 'Authorization: myToken42' -d $'{"_raw":"this is a sample event ", "host":"myHost", "source":"mySource", "fieldA":"valueA", "fieldB":"valueB"} \n {"_raw":"this is another sample event ", "host":"myOtherHost", "source":"myOtherSource", "fieldA":"valueA", "fieldB":"valueB"}'

Splunk HEC Event Endpoint

curl -k http://<myCriblHost>:10080/services/collector/event -H 'Authorization: myToken42' -d '{"event":"this is a sample event ", "host":"myHost", "source":"mySource", "fieldA":"valueA", "fieldB":"valueB"}'

curl -k http://<myCriblHost>:10080/services/collector -H 'Authorization: myToken42' -d '{"event":"this is a sample event ", "host":"myHost", "source":"mySource", "fieldA":"valueA", "fieldB":"valueB"}'

📘

For Splunk HEC, the token specification can be either Splunk <token> or <token>.

Updated 17 days ago

HTTP/S (Bulk API)


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.