Shippers

The recommended way to send logs to HeliosLogs is Native NDJSON — your shipper POSTs newline-delimited JSON to /api/ingest. This page has ready-to-use configs for the common shippers, starting with Fluent Bit.

The target

Endpoint	POST /api/ingest
Body	NDJSON — one JSON object per line
Query params	index (partition, default default), env (default default), source (optional tag)
Headers	Authorization: Bearer <token> if require-auth is on; X-Helios-Env / X-Helios-Index as alternatives to the query params
Compression	gzip bodies are inflated automatically
Max body	256 MB per request

Set the environment with an ingest token (recommended — the token pins its env) or with the X-Helios-Env header / ?env= query param.

Fluent Bit

Use the http output plugin with format json_lines (that's NDJSON). This is the recommended shipper config:

[OUTPUT]
    Name             http
    Match            *
    Host             helios.example.com
    Port             7300
    URI              /api/ingest?index=app
    Format           json_lines
    Header           Authorization Bearer <ingest-token>
    Header           X-Helios-Env prod
    json_date_key    timestamp
    json_date_format iso8601
    tls              On

• json_date_key timestamp makes Fluent Bit emit the event time under the timestamp key HeliosLogs recognizes (see field mapping).
• Route different inputs to different indexes by giving each [OUTPUT] its own Match and URI=...?index=<name> (or template per event — see below).
• Drop tls On for plain HTTP behind a trusted network.

Per-event index routing

The index param accepts a template: URI /api/ingest?index=app- routes each event by its service field. See index templating.

Vector

The http sink with newline-delimited JSON:

[sinks.helios]
type           = "http"
inputs         = ["my_source"]
uri            = "https://helios.example.com/api/ingest?index=app"
method         = "post"
encoding.codec = "json"
framing.method = "newline_delimited"
compression    = "gzip"

[sinks.helios.request.headers]
Authorization = "Bearer <ingest-token>"
X-Helios-Env  = "prod"

OpenTelemetry Collector

If your pipeline is OpenTelemetry, export logs with the OTLP/HTTP exporter — HeliosLogs accepts OTLP directly (see Compatibility APIs):

exporters:
  otlphttp/helios:
    logs_endpoint: https://helios.example.com/v1/logs
    headers:
      Authorization: Bearer <ingest-token>
      X-Helios-Env: prod

service:
  pipelines:
    logs:
      exporters: [otlphttp/helios]

Application loggers

Any logger that can POST JSON works — your app can hit /api/ingest directly. Most structured-logging formats parse with no mapping (zap, pino, logrus, bunyan, Serilog, log4j2/logback, python-json-logger, …). See Log formats & field mapping for the recognized timestamp/message keys.

Non-JSON logs: /api/ingest/raw

When the source isn't clean JSON — plain text, CSV, logfmt, or lines you want parsed with a pattern — POST the raw bytes to /api/ingest/raw and let HeliosLogs parse them:

curl -X POST 'http://localhost:7300/api/ingest/raw?index=app&format=text' \
  --data-binary @app.log

Parameter	Values	Notes
format	auto, ndjson, json, text, syslog, logfmt, csv/tsv, grok, cef, w3c	Auto-detected when omitted.
compression	auto, gzip, zstd, none	Auto-sniffed.
multiline_pattern	regex	A matching line opens a new event; following lines fold in (stack traces).
multiline_max_lines	integer	Cap on folded lines.
grok_pattern	preset / %{...} / named-capture regex	For format=grok. Presets: nginx_access, apache_common, apache_combined, log4j/logback, containerd.

Example — a multi-line Java/log4j file:

curl -X POST 'http://localhost:7300/api/ingest/raw?index=app&format=grok&grok_pattern=log4j&multiline_pattern=^\d{4}-\d{2}-\d{2}' \
  --data-binary @application.log

Anything the parser can't structure is preserved losslessly as a message field.

Verify it's flowing

After pointing a shipper at HeliosLogs, search * | stats count by index over a recent range, or check the _helioshttp self-log for ingest requests. Seeing 429s? That's backpressure — the shipper should retry with backoff.