Cribl LogStream ā€“ Docs

Cribl LogStream Documentation

Questions? We'd love to help you! Meet us in #Cribl Community Slack (sign up here)
Download entire manual as PDF ā€“ v.3.1.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 LogStream to Receive Data over HTTP(S)

From the top nav of a LogStream instance or Group, select Sources, then select [PushĀ >] HTTP from the DataĀ Sources page's tiles or the Sources left nav. Click +Ā AddĀ New to open the HTTP > NewĀ Source modal, which provides the fields outlined below.

šŸ‘

LogStream ships with an HTTP Source preconfigured to listen on PortĀ 10080, and on several default endpoints. YouĀ can clone or directly modify this Source to further configure it, and then enable it.

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 that you use the dedicated Elasticsearch API Source instead of this endpoint. 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.

šŸ“˜

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 that you use the dedicated Splunk HEC Source instead of this endpoint. The Splunk HEC implementation here is provided for backward compatibility, and for users who want to ingest multiple inputs on one HTTP/S port.

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

TLS Settings (ServerĀ Side)

Enabled defaults to No. When toggled to Yes:

Certificate name: Name of the predefined certificate.

Private key path: Path on server where to find the private key to use in PEM format. Path can reference $ENV_VARS.

Passphrase: Passphrase to use to decrypt private key.

Certificate path: Server path at which to find certificates (in PEM format) to use. PathĀ can reference $ENV_VARS.

CA certificate path: Server path at which to find 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:

  • Validate client certs: Reject certificates that are not authorized by a CA in the CAĀ certificate path, or by another trusted CA (e.g., the system's CA). Defaults toĀ No.

  • Common name: Regex matching subject common names in peer certificates allowed to connect. DefaultsĀ toĀ .*. Matches on the substring after CN=. AsĀ needed, escape regex tokens to match literal characters. E.g., to match the subject CN=worker.cribl.local, you would enter: worker\.cribl\.local.

Minimum TLS version: Optionally, select the minimum TLS version to accept from connections.

Maximum TLS version: Optionally, select the maximum TLS version to accept from connections.

šŸš§

In a Cribl.Cloud deployment, do not set the TLSĀ Settings (ServerĀ Side) tab's Enabled slider to Yes, nor configure any of the tab's resulting TLS fields. Any settings that you configure here would conflict with the LogStreamĀ Cloud Source's predefined TLS configuration.

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.

Advanced Settings

Enable Proxy Protocol: Enable if the connection is proxied by a device that supports Proxy Protocol v1 or v2.

Max active requests: Maximum number of active requests allowed for this Source, per WorkerĀ Process. Defaults to 256. EnterĀ 0 for unlimited.

Activity log sample rate: Determines how often request activity is logged at the info level. The default 100 value logs every 100th value; a 1 value would log every request; a 10 value would log every 10th request; etc.

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
  • __srcIpPort
  • __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

LogStream

The examples in this section demonstrate sending HTTP data into a LogStream binary that you manage on-prem, or on a VM. To set up these 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>.

LogStream Cloud ā€“ Single Event

  1. Generate and copy a token in your LogStreamĀ Cloud instance's HTTP Source > GeneralĀ Settings.

  2. From the command line, use https, your Cribl.Cloud portalā€™s Ingest Endpoint and port, and the token's value:

curl -k https://in.logstream.<tenantā€‘ID>.cribl.cloud:10080/cribl/_bulk -H 'Authorization: <token_value> $'{"_raw":"this is a sample event ", "host":"myHost", "source":"mySource", "fieldA":"valueA", "fieldB":"valueB"}'

Updated 15 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.