Better Stack

A betterstack drain posts to one Better Stack source’s ingesting host. Records arrive with dt as the timestamp, level as the severity, message as the log line, and the whole Lua record kept alongside as structured fields you can query and alert on. Before you begin

A Better Stack source of type HTTP. Its Connect page gives you two things you need: the ingesting host and the source token.

What to enter

Field	Flag	Value
Name	`--name`	1–64 characters, unique in the organization
Type	`--type betterstack`
Endpoint	`--endpoint`	`https://<your ingesting host>` from the source’s Connect page
Token	`--header Authorization`	The CLI prompts for the value. Enter it as `Bearer <source token>`

lua drains create \
  --name "Better Stack prod" \
  --type betterstack \
  --endpoint https://s1234567.eu-nbg-2.betterstackdata.com \
  --header Authorization \
  --environments production \
  --min-severity info

Output

? Value for header Authorization: ********************************
✔ Created drain drn_44a0cb18e7d2905f31b6ee08 (pending_verification)

Next: lua drains verify drn_44a0cb18e7d2905f31b6ee08

The ingesting host is specific to your source and to the region the source lives in — it is not a single shared endpoint, so copy it from the Connect page rather than guessing.

Better Stack deliveries are not signed. There is no X-Lua-Signature header and no signing secret; the Authorization header authenticates the sender. If you need a signature, use a generic HTTPS drain.

How ownership verification works

Better Stack uses a test post: one batch containing a single lua.drain.test record is sent to the ingesting host, and any 2xx is accepted.

lua drains verify drn_44a0cb18e7d2905f31b6ee08

A 401 means the token is wrong or is missing its Bearer prefix — the stored value is sent as the whole header value, so Bearer is part of what you enter (and, with --header-from-env, part of the variable’s value). The drain stays in pending_verification and keeps buffering (for up to six hours) while you fix it. Verification is limited to 5 attempts per drain per hour.

What arrives

Each record becomes one entry in a JSON array:

[
  {
    "dt": "2026-09-12T12:59:57.644Z",
    "level": "error",
    "message": "Ticket lookup failed: upstream timeout",
    "lua": {
      "id": "1789217997644-jtoulxxxq",
      "timestamp": "2026-09-12T12:59:57.644Z",
      "observedTimestamp": "2026-09-12T12:59:59.102Z",
      "eventName": "lua.skill.error",
      "severityNumber": 17,
      "severityText": "ERROR",
      "body": "Ticket lookup failed: upstream timeout",
      "attributes": {
        "lua.log.type": "log",
        "lua.source": "skill",
        "lua.primitive.name": "tickets",
        "gen_ai.tool.name": "lookup_tickets",
        "gen_ai.operation.name": "execute_tool",
        "lua.duration_ms": 1841,
        "exception.type": "Error",
        "exception.message": "upstream timeout"
      }
    }
  }
]

Better Stack field	Comes from
`dt`	The record’s `timestamp`, RFC 3339
`level`	The severity, lower-cased: `debug`, `info`, `warn`, `error`
`message`	The record’s `body`, or its `eventName` when there is no body
`lua`	The whole record, unchanged, exactly as Event schema describes it

Filtering a source by organization, agent, or environment

Better Stack indexes top-level keys as searchable fields and does not index inside a nested object. The batch’s resource — which is where the organization and agent ids live — rides inside lua, so on a source carrying several agents there was nothing to filter on. Once this is enabled on your deployment, each entry also carries four of those resource attributes as top-level keys:

{
  "dt": "2026-09-12T12:59:57.644Z",
  "level": "error",
  "message": "Ticket lookup failed: upstream timeout",
  "lua.org.id": "org_4f2c9a1b",
  "lua.agent.id": "agent_1789214224176_2vta8rnyn",
  "service.name": "support-agent",
  "deployment.environment.name": "production",
  "lua": { "…": "the record, unchanged" }
}

Top-level key	What it identifies
`lua.org.id`	Your organization
`lua.agent.id`	The agent that produced the record
`service.name`	That agent’s name
`deployment.environment.name`	`production` or `sandbox`

They are a copy, not a move. The lua record is untouched and the batch’s resource stays exactly where the published schema says it is, so nothing you already query changes meaning. What is lifted is ids and names — and, once app fields are enabled for your deployment, the app.<key> fields your own code supplied, under those same keys:

{
  "dt": "2026-09-12T12:59:57.644Z",
  "level": "error",
  "message": "Ticket lookup failed: upstream timeout",
  "lua.org.id": "org_4f2c9a1b",
  "service.name": "support-agent",
  "app.tenant": "acme",
  "app.ticket_id": 48219,
  "lua": { "…": "the record, unchanged" }
}

app.tenant:"acme" AND level:error

Never a secret, never message content, and — ids, names and your own fields alike — never a value the scrubber has not already seen. Every string is scrubbed, and a drain’s redact list applied, before the encoder runs; lifting a key copies the value the record already carries and cannot reveal anything the record did not. A key whose resource value is missing or empty is omitted rather than sent blank, because an empty string is a value a Better Stack query matches and a drain answering lua.org.id:"" would be worse than one answering nothing.

Until this is enabled on your deployment, an entry carries the record and nothing else — so group by lua.attributes["lua.primitive.name"] for a primitive and by lua.eventName for a kind of event, and if you need the agent or the environment on every record in the meantime, send to an OpenTelemetry collector and promote the resource attributes there. The published collector config already copies service.name and the environment onto each record, and its exporter can forward to Better Stack.

Useful queries

lua.severityText:ERROR
lua.eventName:"lua.skill.error"
lua.eventName:"lua.drain.heartbeat"
lua.attributes.gen_ai.tool.name:"lookup_tickets"

And the fleet filter, once the top-level keys are enabled — one agent’s errors on a source that receives the whole organization:

lua.org.id:"org_4f2c9a1b" AND service.name:"support-agent" AND level:error

Caps

Cap	Value
Records per batch	500
Uncompressed bytes per batch	1 MiB
Compression	`gzip`, always
Request timeout	10 s
Retried status codes	`408`, `429`, and every `5xx`
Terminal	Every other `4xx`, and every `3xx`

Test the token with curl

Prove the host and the token before creating the drain. This sends exactly the shape a delivery has:

INGEST='https://s1234567.eu-nbg-2.betterstackdata.com'
SOURCE_TOKEN='<your Better Stack source token>'

curl -sS -i -X POST "$INGEST" \
  -H "Authorization: Bearer $SOURCE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "dt": "2026-09-12T12:59:57.644Z",
      "level": "info",
      "message": "Lua drain connectivity test",
      "lua": {
        "id": "probe-0001",
        "timestamp": "2026-09-12T12:59:57.644Z",
        "observedTimestamp": "2026-09-12T12:59:59.102Z",
        "eventName": "lua.drain.test",
        "severityNumber": 9,
        "severityText": "INFO",
        "attributes": { "lua.drain.id": "drn_probe" }
      }
    }
  ]'

A 202 means accepted; the entry shows up in Live tail within a few seconds. A 401 means the token is wrong or the Bearer prefix is missing; a 404 usually means the ingesting host belongs to a different source or region. Then do the same through the real delivery path:

lua drains test drn_44a0cb18e7d2905f31b6ee08

Alert on it

Better Stack alerts on a saved query. Three that are worth having from day one:

Alert	Query	Condition
Agent errors spiking	`lua.severityText:ERROR`	More than 5 in 5 minutes
Drain heartbeat missing	`lua.eventName:"lua.drain.heartbeat"`	Fewer than 1 in 15 minutes
Records dropped	`lua.eventName:"lua.drain.dropped"`	More than 0 in 15 minutes

The heartbeat is what makes the other two trustworthy: it arrives every five minutes while the drain is healthy, so its absence tells you the pipeline is down rather than that your agents went quiet. Delivery guarantees explains what it does and does not prove.

If it isn’t working

401 on every delivery

The stored header value is sent verbatim as Authorization. It must read Bearer <source token>, prefix included. Update it with lua drains update <id> --header Authorization and re-enter the whole value.

404 or a redirect

The ingesting host is per-source and per-region. Copy it from that source’s Connect page. A 3xx is treated as a failure and never followed, so a host that redirects has to be replaced with its final URL.

Nothing arrives although the drain is healthy

healthy means the ingesting host accepted the batch. Check that you are looking at the right source, and that the source’s retention and any archiving rule have not moved the data. lua drains deliveries <id> shows the status code and response excerpt for each recent batch.If it shows no recent batches, nothing is being selected rather than nothing being accepted — start with --min-severity, which defaults to info and drops every debug record. If a drain isn’t delivering has that check.

Next steps

Event schema

What every field under lua means.

Delivery guarantees

Retry, drops, heartbeat, and health states.

Ship logs to your stack

Selectors, states, and quotas.

lua drains

Every verb and flag.

Get started

Concepts

Build

Channels

Integrations

Devices

Ship and operate

Ship logs to your stack

Marketplace

Build with AI

Examples

What to enter

How ownership verification works

What arrives

Filtering a source by organization, agent, or environment

Useful queries

Caps

Test the token with curl

Alert on it

If it isn’t working

Next steps

Event schema

Delivery guarantees

Ship logs to your stack

lua drains

​What to enter

​How ownership verification works

​What arrives

​Filtering a source by organization, agent, or environment

​Useful queries

​Caps

​Test the token with curl

​Alert on it

​If it isn’t working

​Next steps

Event schema

Delivery guarantees

Ship logs to your stack

lua drains

What to enter

How ownership verification works

What arrives

Filtering a source by organization, agent, or environment

Useful queries

Caps

Test the token with curl

Alert on it

If it isn’t working

Next steps