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

# Log Drains

> Stream run logs to external HTTP destinations.

Log drains forward run log events from your jobs to external HTTP endpoints in near real-time. This allows you to integrate Strait's execution logs with external observability platforms, SIEM tools, or custom log aggregation services.

## LogDrain Model

The `LogDrain` struct (defined in `apps/strait/internal/domain/types.go`) contains the following fields:

| Field          | Type                | Description                                                                   |
| :------------- | :------------------ | :---------------------------------------------------------------------------- |
| `id`           | `string`            | Unique identifier.                                                            |
| `project_id`   | `string`            | The project this log drain belongs to.                                        |
| `name`         | `string`            | Human-readable name of the log drain.                                         |
| `drain_type`   | `string`            | Format and protocol used for delivery (e.g., HTTP POST with JSON).            |
| `endpoint_url` | `string`            | The HTTP URL where log events are delivered.                                  |
| `auth_type`    | `string`            | Authentication method used when calling the endpoint.                         |
| `auth_config`  | `map[string]string` | Key-value pairs containing credentials for the chosen `auth_type`.            |
| `level_filter` | `[]string`          | Optional list of log levels to forward. When empty, all levels are forwarded. |
| `enabled`      | `bool`              | Whether the log drain is active and delivering events.                        |
| `created_at`   | `time.Time`         | Timestamp when the log drain was created.                                     |
| `updated_at`   | `time.Time`         | Timestamp of the last update.                                                 |

## Drain Types

The `drain_type` field specifies the format and protocol used when delivering log events to the endpoint. For example, an HTTP POST drain sends a JSON payload to the configured `endpoint_url` for each batch of log events.

<Tip>
  Choose a drain type that matches your destination's ingestion API. Most observability platforms accept JSON over HTTP POST.
</Tip>

## Authentication

The `auth_type` field determines how Strait authenticates with the external endpoint. The `auth_config` map holds the credentials for the chosen method.

| `auth_type` | Expected `auth_config` keys | Behavior                                         |
| :---------- | :-------------------------- | :----------------------------------------------- |
| `bearer`    | `token`                     | Sends an `Authorization: Bearer <token>` header. |
| `basic`     | `username`, `password`      | Sends an `Authorization: Basic <base64>` header. |
| `header`    | Any key-value pairs         | Sends each entry as a custom HTTP header.        |

<Warning>
  The `auth_config` map contains sensitive credentials. Treat it with the same care as API keys or secrets.
</Warning>

## Level Filtering

The `level_filter` field accepts an array of log level strings. When set, only log events matching one of the specified levels are forwarded to the endpoint. When omitted or empty, all log levels are delivered.

```json theme={null}
{
  "level_filter": ["error", "warn"]
}
```

This is useful for high-volume environments where you only want critical events sent to an external destination.

## CRUD Lifecycle

Log drains are managed through the following API operations:

| Operation | Method   | Path                                      |
| :-------- | :------- | :---------------------------------------- |
| Create    | `POST`   | `/v1/log-drains`                          |
| List      | `GET`    | `/v1/log-drains?project_id=...`           |
| Get       | `GET`    | `/v1/log-drains/{drainID}?project_id=...` |
| Update    | `PATCH`  | `/v1/log-drains/{drainID}?project_id=...` |
| Delete    | `DELETE` | `/v1/log-drains/{drainID}?project_id=...` |

Creating a log drain requires `project_id`, `name`, `drain_type`, `endpoint_url`, and `auth_type`. Updates are partial -- only the fields included in the PATCH body are modified.

<Note>
  All operations are scoped to a `project_id`. List and single-resource endpoints require it as a query parameter.
</Note>

## Configuration

The log drain delivery worker runs on a configurable interval controlled by the `LOG_DRAIN_WORKER_INTERVAL` environment variable. It defaults to `60s`.

| Variable                    | Default | Description                                                         |
| :-------------------------- | :------ | :------------------------------------------------------------------ |
| `LOG_DRAIN_WORKER_INTERVAL` | `60s`   | Interval at which the delivery worker polls for pending log events. |

## Related Concepts

* [Runs](/concepts/runs): The execution instances whose log events are forwarded by log drains.
* [Jobs](/concepts/jobs): The job definitions that produce the runs generating log events.