> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON log drain

> This topic explains how to send JSON-formatted logs over HTTP to LaunchDarkly observability features, including from Fastly log streams and Courier outbound webhooks.

**Developer**

**Federal docs**

**EU docs**

**Federal docs**

> [!CAUTION]
>
> **Observability is not available in federal environments**
>
> To learn more, read [LaunchDarkly in federal environments](https://launchdarkly.com/docs/home/infrastructure/federal).

This topic explains how to send JSON-formatted logs over HTTP to LaunchDarkly observability features using the JSON log drain. You can send logs from any service that can make an HTTPS request with a JSON body, including Fastly log streams and Courier outbound webhooks.

After you configure a sender, its logs appear on the [Logs](https://launchdarkly.com/docs/home/observability/logs.md) page of the LaunchDarkly user interface.

## Prerequisites

Before you configure the JSON log drain, you must:

* Have LaunchDarkly observability enabled for your project.
* Know your LaunchDarkly client-side ID.

To find your client-side ID:

1. In the LaunchDarkly UI, open the project menu.
2. Select **Project settings**.
3. Click **Environments**.
4. Find the environment you want to use and copy the **Client-side ID** value.

## Send JSON logs

Send a `POST` request to the JSON log drain endpoint with your logs in the request body. Set the `x-highlight-project` header to your LaunchDarkly client-side ID. This tells LaunchDarkly which project to route the logs to.

Here is an example request:

**Developer**

```bash title="Send a single log entry" lines wrap theme={null}
curl -X POST https://pub.observability.app.launchdarkly.com/v1/logs/json \
  -H 'x-highlight-project: YOUR_CLIENT_SIDE_ID' \
  -H 'Content-Type: application/json' \
  -d '{"timestamp":"2025-01-15T09:30:00Z","level":"info","message":"Checkout completed"}'
```

**Federal docs**

```bash title="Send a single log entry" lines wrap theme={null}
curl -X POST https://pub.observability.app.launchdarkly.com/v1/logs/json \
  -H 'x-highlight-project: YOUR_CLIENT_SIDE_ID' \
  -H 'Content-Type: application/json' \
  -d '{"timestamp":"2025-01-15T09:30:00Z","level":"info","message":"Checkout completed"}'
```

**EU docs**

```bash title="Send a single log entry" lines wrap theme={null}
curl -X POST https://pub.observability.app.eu.launchdarkly.com/v1/logs/json \
  -H 'x-highlight-project: YOUR_CLIENT_SIDE_ID' \
  -H 'Content-Type: application/json' \
  -d '{"timestamp":"2025-01-15T09:30:00Z","level":"info","message":"Checkout completed"}'
```

Replace `YOUR_CLIENT_SIDE_ID` with your LaunchDarkly client-side ID.

### Accepted body formats

The JSON log drain accepts a single JSON object, an array of JSON objects, newline-delimited JSON (NDJSON), or a sequence of JSON objects concatenated together with no separator. LaunchDarkly detects the shape of the body for you, which means you do not have to set the `application/x-ndjson` content type to send more than one log entry in a request.

Here are three bodies that send the same two log entries:

```json title="Array" lines wrap theme={null}
[
  {"timestamp":"2025-01-15T09:30:00Z","level":"info","message":"Checkout completed"},
  {"timestamp":"2025-01-15T09:30:01Z","level":"error","message":"Payment declined"}
]
```

```json title="Newline-delimited" lines wrap theme={null}
{"timestamp":"2025-01-15T09:30:00Z","level":"info","message":"Checkout completed"}
{"timestamp":"2025-01-15T09:30:01Z","level":"error","message":"Payment declined"}
```

```json title="Concatenated" lines wrap theme={null}
{"timestamp":"2025-01-15T09:30:00Z","level":"info","message":"Checkout completed"}{"timestamp":"2025-01-15T09:30:01Z","level":"error","message":"Payment declined"}
```

### Log entry fields

LaunchDarkly reads the following keys from each JSON object. It matches the key names without regard to case, which means `message`, `Message`, and `MESSAGE` all work:

<table>
  <thead>
    <tr>
      <th>Key</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`message`</td>
      <td>The log message. If the object does not contain this key, LaunchDarkly uses the raw JSON object as the message.</td>
    </tr>

    <tr>
      <td>`level`</td>
      <td>The log level, such as `info` or `error`.</td>
    </tr>

    <tr>
      <td>`timestamp`</td>
      <td>The time your service emitted the log entry.</td>
    </tr>
  </tbody>
</table>

### Timestamp formats

LaunchDarkly accepts a timestamp in any of the following formats:

* [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339), such as `2025-01-15T09:30:00Z`.
* A date and time with a numeric UTC offset, such as `+0700`.
* An epoch value in seconds, milliseconds, microseconds, or nanoseconds.

If a log entry has no timestamp, LaunchDarkly uses the time it received the entry. If the entry has a timestamp that LaunchDarkly cannot parse, LaunchDarkly also uses the receive time, and keeps the original value as a `timestamp` attribute on the log. This means you can still search for it.

### Responses

LaunchDarkly returns a success response when it accepts at least one log entry from the request. If one entry in a batch is malformed, LaunchDarkly skips that entry and ingests the rest. The request fails only when LaunchDarkly accepts no entries at all.

> [!WARNING]
>
> **Requests that do not identify a project now fail**
>
> A request with a missing or unrecognized project returns a `400` response instead of a success response. If LaunchDarkly cannot resolve the project because of a temporary problem, it returns a `503` response, and you can retry the request. If you monitor the response status of your log senders, confirm that each one sets the `x-highlight-project` header to a valid client-side ID.

## Send logs from Fastly

If you serve traffic through [Fastly](https://www.fastly.com), you can create an HTTPS logging endpoint that streams your service logs to the JSON log drain.

Configure the Fastly logging endpoint with the following values:

* **URL**: The JSON log drain endpoint described in [Send JSON logs](#send-json-logs)
* **Content type**: `application/json`
* **Custom request header**: `x-highlight-project`, set to your LaunchDarkly client-side ID
* **Log format**: A JSON object that contains a `message` key, and optionally `level` and `timestamp` keys

Fastly batches several log lines into a single request. The JSON log drain reads batched objects whether or not they are separated by newlines, which means you do not need to add delimiters to your log format.

## Send Courier webhooks

If you use Courier to send notifications, you can point a Courier outbound webhook at the JSON log drain to record notification activity as logs.

Configure the outbound webhook in Courier with the JSON log drain endpoint described in [Send JSON logs](#send-json-logs), and add an `x-highlight-project` header set to your LaunchDarkly client-side ID.

LaunchDarkly recognizes a Courier webhook payload and does the following:

* Derives the log message and severity from the payload.
* Reads the send time from the `courier-signature` header and uses it as the log timestamp.
* Links the log entry to a trace when the payload contains `data.metadata.trace_id`.

## Verify that logs are being received

After you configure a sender, its logs begin forwarding to LaunchDarkly.

To verify that your logs are being received:

1. Open the **Telemetry** section and navigate to the **Logs** list.
2. Choose or search for logs from the service you configured.

It may take a few minutes for logs to appear after you first configure the log drain.

## Filter logs

You can configure ingestion filters to control which logs are stored in LaunchDarkly. This is useful for excluding noisy logs or limiting ingestion to stay within your observability quotas.

To learn more, read [Filters](https://launchdarkly.com/docs/home/observability/settings.md#filters).
