Ship logs to Elastic

Use this guide to index your Audit Logs into Elasticsearch. Elastic Cloud, Elastic Cloud Serverless, self-managed clusters, and compatible clusters such as OpenSearch are all supported.

Step 1: Create an Elasticsearch API key

Create a base64-encoded Elasticsearch API key with permission to manage index templates and to write to the data stream Firezone will use, which defaults to logs-firezone-default. In Kibana this is under Stack Management → API keys.

Step 2: Create the Log Sink in Firezone

In the admin portal, go to SettingsLog Sinks, click Add, and select Elastic. Configure the sink:

FieldDescription
NameA name to identify this log sink.
Endpoint URLYour cluster's Elasticsearch endpoint, such as https://my-deployment.es.us-east-1.aws.elastic-cloud.com.
API KeyA base64-encoded Elasticsearch API key with permission to manage index templates and write to the data stream.
Data streamThe data stream to append events to. Firezone creates it on first delivery. Manage retention with the stream's lifecycle in Kibana. Defaults to logs-firezone-default.

The endpoint URL must be HTTPS, and hostnames that resolve to private or reserved IP addresses are rejected. A trailing /_bulk is stripped if you paste one. The data stream name must be lowercase and may contain digits, ., _, and -.

Then choose which Log streams to deliver, all four of which are enabled by default, and optionally check Deliver existing logs to backfill logs recorded before the sink was created.

Deliver existing logs can only be selected when you create the sink. It can't be turned on later for an existing sink.

Click Create. Before the first delivery, Firezone creates an index template with priority 500, the data stream, and field mappings that index Firezone event fields as keyword/flattened with date detection disabled. You don't need to define any of these yourself.

Delivery format

Firezone POSTs to <Endpoint URL>/_bulk as NDJSON, using the create actions that data streams require, with the event's log_id as the document _id:

{"create":{"_index":"logs-firezone-default","_id":"c0654d20aa1b4a0000000002"}}
{"@timestamp":"2026-07-14T09:26:31.114Z","message":"firezone change c0654d20aa1b4a0000000002","stream":"change","firezone":{...}}

The full event is under the firezone field of each document:

{
  "@timestamp": "2026-07-14T09:26:31.114Z",
  "message": "firezone change c0654d20aa1b4a0000000002",
  "stream": "change",
  "firezone": {
    "type": "change",
    "log_id": "c0654d20aa1b4a0000000002",
    "timestamp": "2026-07-14T09:26:31.114213Z",
    "object": "policies",
    "operation": "update",
    "before": { "id": "0a83588e-…", "description": "Engineering → GitLab" },
    "after": {
      "id": "0a83588e-…",
      "description": "Engineering → GitLab (MFA required)"
    },
    "subject": {
      "actor_id": "e2f6a9c4-…",
      "actor_name": "Jamie Admin",
      "actor_email": "jamie@company.com",
      "actor_type": "account_admin_user",
      "auth_provider_id": "9d0c2f4e-…",
      "ip": "203.0.113.44",
      "ip_region": "US",
      "ip_city": "San Francisco",
      "ip_lat": 37.7749,
      "ip_lon": -122.4194,
      "user_agent": "Mozilla/5.0 …"
    }
  }
}

How Firezone responds to HTTP status codes

The bulk API reports per-document outcomes inside an HTTP 200, so Firezone inspects item-level results as well as the response status:

ResponseBehavior
200 with no item errorsThe batch is accepted and delivery advances.
200 with item 409sAccepted. The documents already exist, which is the _id-based idempotency working as intended.
200 with item 429/503sThe cluster is overloaded, so the whole batch is retried. The _id prevents the retry from creating duplicate documents.
200 with mapping-conflict item errorsThe batch is bisected to isolate the rejected document. Delivery pauses at it, Firezone engineers are notified, and the data stream is rolled over as described below. No entries are skipped.
200 with other item errors, for example a cluster blockTreated as transient and retried. If failures persist for 24 hours, the sink is disabled and admins are emailed.
413The batch is split in half and retried to isolate an oversized document.
429, 5xxRetried every minute. Disabled after 24 hours of persistent failure.
Other non-2xx, for example 401Treated as a configuration error: the sink is disabled immediately.

Duplicates and self-healing

Redelivery does not normally create duplicate documents. Every document is created with its log_id as its _id, so if Firezone delivers the same batch twice, Elasticsearch rejects the second copy of each document as already existing. The one exception is a retry that lands after the data stream has rolled over to a new backing index, which can produce a duplicate document, so deduplicate on firezone.log_id in queries if you need strict uniqueness.

The sink also heals itself: if a document is rejected due to a mapping conflict, for example a manually edited mapping that no longer accepts Firezone's fields, Firezone automatically rolls the data stream over, at most once per hour, so that corrected mappings apply to a fresh backing index, and delivery of healthy documents continues past the conflict.

Recovering a failed sink

A sink showing Warning is retrying automatically, so unless the failures continue there's nothing you need to do. A sink showing Error has stopped delivering and needs attention: fix the cause , commonly an expired API key or missing privileges, then open the sink, click Edit, and click Save to re-enable it. Delivery picks up right where it left off, from the last acknowledged entry, and Deliver Now triggers a delivery immediately if you don't want to wait for the next cycle.

Deleting the sink deletes its delivery state but not the data stream or its documents, so re-creating it starts fresh: the new sink delivers logs recorded from its creation onward, plus a full backfill if Deliver existing logs is selected. Thanks to _id-based deduplication, a backfill into the same data stream won't duplicate documents that are still in the current backing index.

Need help? See all support options.

Found a problem with this page? Open an issue
Last updated: July 20, 2026