HTTP Event Collector (HEC)
Send logs to nano over the HTTP Event Collector (HEC) protocol from Cribl, Fluent Bit, the OpenTelemetry Collector, or your own code
Send logs to nano with the HTTP Event Collector (HEC) protocol. Point your HEC client at the endpoint for your deployment and configure an ingest token. Vector receives HEC on every deployment.
| Ingest hostname: Kubernetes and Self-run with several servers | Port 8088: Self-run on one server, and open core | |
|---|---|---|
| Event endpoint | https://<ingest-host>/services/collector/event | http://<host>:8088/services/collector/event |
| Raw endpoint | https://<ingest-host>/services/collector/raw | http://<host>:8088/services/collector/raw |
Bare /services/collector | Accepted | Not served. Use /services/collector/event. |
| Acknowledgements | /services/collector/ack | /services/collector/ack |
| Token | A per-source ingest token | A per-source ingest token |
| Which source an event gets | The token's source | The token's source |
Both use the HEC Authorization: Splunk <token> header scheme and answer a successful request with {"text":"Success","code":0}, plus an ackId when the request carries a channel.
Tokens and sources
Issue one token per source under Ingestion → Log Sources → Credentials. The token decides the source: every envelope sent with it lands in the token's log source, and the envelope's sourcetype doesn't change that. A forwarder that sends several log types uses one HEC output per type, each with its own token.
Only an install token left in the deprecated legacy multiplex mode routes by sourcetype. See Route by sourcetype (legacy).
Indexer acknowledgements
Send an X-Splunk-Request-Channel header (or a ?channel= query parameter) with a UUID to get an ackId back, then poll POST /services/collector/ack on the same channel with the same token. An ack resolves once Vector has buffered the events for delivery, so it keeps resolving through a ClickHouse outage and the buffer delivers at-least-once afterwards.
- Acks live in the memory of the one Vector process that accepted the events. On Self-run, the ingest edge pins each channel to one Vector instance; send every event and every ack poll of a channel with the same channel ID.
- When Vector scales or restarts, a moved channel's pending acks read
false, and senders re-send. - Every request needs a channel, even if the sender never polls for acks. Without one, nano answers
400withData channel is missing(code 10). On Kubernetes,ingest.edge.hecAcks: falseonly lets the ingest edge scale out; it doesn't turn channels off.
Poll with Content-Type: application/json and a JSON list of the ackId values. Without that header, curl sends a form content type and the ack endpoint answers 415:
CHANNEL=$(uuidgen)
curl -sS "https://<ingest-host>/services/collector/event" \
-H "Authorization: Splunk $NANO_TOKEN" -H "X-Splunk-Request-Channel: $CHANNEL" \
-d '{"event": {"message": "hello from nano"}}'
# {"text":"Success","code":0,"ackId":0}
curl -sS "https://<ingest-host>/services/collector/ack" \
-H "Authorization: Splunk $NANO_TOKEN" -H "X-Splunk-Request-Channel: $CHANNEL" \
-H "Content-Type: application/json" -d '{"acks": [0]}'
# {"acks":{"0":true}}Endpoints by deployment
Ingest hostname (Kubernetes, Self-run with several servers)
These deployments receive HEC on the dedicated ingest hostname over HTTPS on port 443. On a Self-run install with several servers, that is your load balancer's ingest hostname, which forwards to the ingest servers (High availability). The app hostname answers 404 on HEC paths.
curl -sS --fail-with-body "https://<ingest-host>/services/collector/event" \
-H "Authorization: Splunk $NANO_TOKEN" \
-H "X-Splunk-Request-Channel: $(uuidgen)" \
-d '{"event": {"message": "hello from nano"}}'Port 8088 (Self-run on one server, open core)
Vector listens for HEC on port 8088, on a single Self-run server as on open core.
curl -sS --fail-with-body "http://<host>:8088/services/collector/event" \
-H "Authorization: Splunk $NANO_TOKEN" \
-H "X-Splunk-Request-Channel: $(uuidgen)" \
-d '{"event": {"message": "hello from nano"}}'Port 8088 is plain HTTP, and the bundled TLS overlay covers only the web UI, /ingest and /otlp on :80/:443; it doesn't proxy HEC. If senders cross an untrusted network, terminate TLS in front of :8088 with your own reverse proxy or load balancer (you can reuse the certificate from config/nginx/ssl/), forward to http://<host>:8088, and firewall :8088 to that proxy.
Configure your sender
Replace <hec-url> with your deployment's event endpoint and <token> with the token bound to the source.
Cribl Stream. Create an HEC-compatible destination; see Cribl Stream.
Fluent Bit (HEC output, Name splunk):
[OUTPUT]
Name splunk
Match *
Host <host>
Port 8088
Splunk_Token <token>For a dedicated ingest host (Kubernetes, or Self-run with several servers), set Port 443 and TLS On.
OpenTelemetry Collector (HEC exporter, splunk_hec):
exporters:
splunk_hec/nano:
endpoint: <hec-url>
token: "<token>"Batch several events in one request by concatenating envelopes (no array wrapper):
curl -sS "<hec-url>" \
-H "Authorization: Splunk <token>" \
-d '{"time": 1705312800, "event": {"message": "Event 1"}}
{"time": 1705312801, "event": {"message": "Event 2"}}'Send plain text to the raw endpoint:
curl -sS "<raw-url>" \
-H "Authorization: Splunk <token>" \
-d 'Jan 15 14:23:45 fw-01 %ASA-6-302013: Built outbound TCP connection 12345 for outside:203.0.113.50/443'Create the log sources
For each log type your senders use, make sure a log source with a parser exists: a parser nano ships (see Supported sources), or a new log source you build from samples under Ingestion → Log Sources. Publish the parser so Vector picks it up, then issue a token for it. See Set up your first feed.
Route by sourcetype (legacy)
On an install upgraded from before per-source tokens, the install token (VECTOR_AUTH_TOKEN) can stay in the deprecated legacy multiplex mode. Envelopes sent with it are routed by sourcetype:
- Vector lowercases the envelope's
sourcetype. That value is the event's source. - The router sends the event to the parser whose
match_valuesinclude that value. Events no parser claims go to the generic parser. - The parser writes the source into
metadata.log_source, which is what you search on.
Vendor sourcetypes such as WinEventLog:Security contain colons and aren't a parser's default match value. Either add the lowercased sourcetype to the parser's match_values, or add a HEC routing rule that maps it to a nano source (see Push vs Pull Routing). Move senders to per-source tokens and then leave legacy mode under Credentials.
Verify delivery
Run a search after sending a test event to confirm its source. Replace windows_event with the source you configured:
metadata.log_source="windows_event" | head 10Count events per source over the last hour to see what is arriving:
earliest=-1h | stats count by metadata.log_sourceHEC payload reference
{
"time": 1705312800,
"host": "webserver-01",
"source": "/var/log/nginx/access.log",
"sourcetype": "nginx",
"index": "main",
"event": {
"remote_addr": "203.0.113.50",
"request": "GET /api/users HTTP/1.1",
"status": 200
}
}| Field | Required | Description |
|---|---|---|
event | Yes | The log event: a string or a JSON object |
sourcetype | No | Ignored for routing with a per-source token. Routes the event only for an install token in legacy multiplex mode |
time | No | Unix epoch time. If omitted, the receipt time is used |
host, source, index, fields | No | Accepted for HEC compatibility |
For plain-text logs, send the string as event, or use /services/collector/raw.
Request limits
The ingest hostname (Self-run with several servers, Kubernetes) admits HEC requests before they reach Vector, so an overloaded sender can't take ingest down for everyone. From v2.0.10 each limit has a burst allowance, so senders that post batches back to back aren't refused:
| Limit | Sustained | Burst |
|---|---|---|
| Per ingest token | 100 requests/s | 200 requests |
| Per sender IP address | 50 requests/s | 100 requests |
| Per ingest server | 1000 requests/s | 2000 requests |
| Concurrent connections per sender IP | 16 | |
| Request body | 8 MiB |
A request over a limit gets 429 and is not acknowledged, so nothing from it is stored; retry it after a short back-off. Before v2.0.10 there was no burst allowance, and two requests from one sender within 20 ms could get 429 even at a few events per second. The limits count requests, not events: batch many events into each request (HEC accepts several JSON envelopes in one body) instead of raising the request rate. Port 8088 on a single Self-run server and on open core has no request-rate limit.
A new token works on every ingest server within a few seconds. Each server reloads the token list every 2 seconds, so the first requests with a brand-new token can get 401 from a server that hasn't loaded it yet. Wait about 10 seconds after creating a token before you send with it, or retry 401 briefly. Revoking a token takes effect the same way.
Troubleshoot
Need help with these checks? Contact support with the deployment, request ID and time with timezone.
Use the response status and the event's source to narrow down the problem:
| Symptom | Check |
|---|---|
401 | The header is Authorization: Splunk <token>, not Bearer. Check that the token isn't revoked or unbound. A token created in the last few seconds may not have reached every ingest server yet; see Request limits. |
400 Data channel is missing | Send an X-Splunk-Request-Channel header or a ?channel= parameter with a UUID on every request. |
429 | The sender is over a request limit. Back off and retry, and send larger batches less often. |
404 on open core | The sender uses the bare /services/collector path. Change it to /services/collector/event. |
404 on Self-run | The sender points at the app host. Use the ingest host. |
| Connection refused | Port 8088 (open core) or 443 on the ingest host isn't reachable from the sender, or Vector isn't running. |
| Events land with the wrong source | The token decides the source. Issue a token bound to the right source. |
| Acks never resolve | Send events and ack polls with the same channel ID and token. A Vector restart or scale event drops pending acks; re-send. |
| Wrong timestamps | time must be Unix epoch time in UTC. |
On open core, Vector's logs show HEC errors (run from the install directory, ~/nano by default):
docker compose -f docker-compose.opensource.yml logs vector 2>&1 | grep -iE "hec|error"Migrating from another SIEM
Run nano alongside your current SIEM while you migrate. If you use Cribl Stream, route the same data to both:
Sources → Cribl Stream → HEC destination (nano)
→ your current SIEMThis lets you validate nano parsers on production data, compare search results, and move detection rules and sources over one at a time. To translate saved field names from your old schema, see the OCSF field reference.