Log drains

Stream an environment's logs and audit events to your own logging stack.

A log drain is an HTTPS endpoint that receives an environment's log as it is written: every API request, email event and webhook attempt, plus the changes made to the environment (from the organization's audit log). coss.com posts them in batches, usually within a few seconds, signed like webhooks: as NDJSON to an endpoint you run, or straight into Grafana Cloud, Datadog or an OpenTelemetry collector, with no relay in between.

A drain takes every source unless you list some. Organization-wide changes (members, domains, SSO) stay in the organization's audit log and are not sent to drains.

Create a drain

In the dashboard, open Log drains in an environment. Or with the API:

const { ,  } = await ..({
  : "https://logs.example.com/coss",
  : ["api", "email"],
});
// Store data.secret: it is returned only now.

Drains belong to the API key's environment, like webhook endpoints. An environment can have up to 5 drains.

Formats

A drain's format picks the body of each request; auth_header adds a header the destination authenticates with (its value is stored encrypted and never shown again; a drain only reports auth_header_name). The dashboard's Destination presets fill both in.

Every format carries each line whole (the same object NDJSON would), so nothing is lost by choosing one. Change a drain's format, URL or header at any time: a batch being retried goes out as the drain is then.

Grafana Cloud

With Loki, use your stack's Loki URL (its details page in the Grafana Cloud portal) and Basic authentication with the Loki user and an access policy token with the logs:write scope:

const  = "123456";
const  = .. ?? "";
await ..({
  : "https://logs-prod-012.grafana.net/loki/api/v1/push",
  : "loki",
  : {
    : "Authorization",
    : `Basic ${(`${}:${}`)}`,
  },
});

Lines arrive labelled service_name="coss", environment_id, source and level; each line is the JSON object, so {service_name="coss"} | json reads its fields. Grafana Cloud's OTLP endpoint works too (format: "otlp", its URL + /v1/logs, the instance ID as the user).

Datadog

await ..({
  : "https://http-intake.logs.datadoghq.com/api/v2/logs",
  : "datadog",
  : { : "DD-API-KEY", : .. ?? "" },
});

For another Datadog site, use its intake host (http-intake.logs.datadoghq.eu, http-intake.logs.us3.datadoghq.com…). Logs arrive with service:coss, source:coss, tags source:<source> and environment_id:<id>, a status from the line's level, its message, and the whole line under the coss attribute (@coss.status_code, @coss.type…).

OpenTelemetry

format: "otlp" posts OTLP/HTTP logs as JSON to any /v1/logs endpoint (a collector, Honeycomb, Grafana Cloud…): service.name is coss, each record's severity comes from the line's level, its time from the line, and its body is the line as a map. Put the destination's key in auth_header (Authorization: Bearer …, x-honeycomb-team…).

Header names coss.com sets itself (Content-Type, User-Agent, webhook-*, coss-*, Host…) can't be used.

NDJSON

Each request is a POST with Content-Type: application/x-ndjson: one JSON object per line, each line ending with a newline, at most 500 lines or 1 MB per request. Log lines are exactly the objects GET /v1/logs returns ("object": "log"), and audit events the objects of the audit log ("object": "audit_event"):

{"object":"log","id":"log_01k7c8m4…","occurred_at":"2026-01-15T09:30:00.000Z","source":"api","level":"info","type":"api.request","message":"POST /v1/emails 202","request_id":"req_01k7c8m4…","status_code":202,…}
{"object":"audit_event","id":"oaudit_01k7c8n1…","created_at":"2026-01-15T09:30:02.000Z","actor_type":"api_key","actor_id":"key_01k7…","action":"webhook_endpoint.created","target_type":"webhook_endpoint","target_id":"whep_01k7…",…}

The headers carry a Standard Webhooks signature over the body (webhook-id, webhook-timestamp, webhook-signature), plus coss-log-drain-id and coss-environment-id (requests of every format carry them). Verify every request with the drain's secret before storing its lines:

const  = await (
  await .(),
  .,
  .. ?? "",
);
for (const  of ) {
  if (. === "log") .(., ., .);
  else .(., ., .);
}

verifyLogDrainBatch throws WebhookVerificationError when the signature doesn't match or the request is more than five minutes old: answer with a 4xx status then.

Delivery

  • Answer with a 2xx status once the lines are stored. Anything else (or no answer within 15 seconds) is retried after 5 seconds, 1 minute, 5 minutes, 30 minutes, 1, 2, 4, 8 and 8 hours.
  • A batch can arrive more than once: the webhook-id header is the batch's id and stays the same on every retry, and each line has its own id. Skip what you already stored. (Loki drops a repeated line with the same timestamp by itself.)
  • Batches go out one at a time per drain, in the order lines were written. API request lines are written within about a second of the response, so they can follow the email events a request caused: sort by occurred_at (audit events: created_at) if order matters. Lines logged while a batch is being retried wait for it.
  • If a batch fails all 10 attempts (about a day), coss.com disables the drain and drops the lines still waiting for it; the audit log records log_drain.disabled. Fix the endpoint, then enable the drain again: it receives lines logged from then on.
  • Disabling a drain yourself also drops its waiting lines, and nothing is kept for a disabled drain.
  • While an organization is suspended, its drains are held; lines that wait more than 3 days are dropped.

Each drain's page in the dashboard (or coss.logDrains.batches.list()) shows its recent batches with every attempt, its status code and the start of the response. Batches are kept for 7 days.

Last updated