Configuration

Carbon client options, event buffering and flushing, retries, and transports.

Client options

All options are optional. With no arguments, Carbon reads CARBON_API_KEY from the environment and sends events to the production ingest API.

import { Carbon } from "@carbon-js/sdk";

const carbon = new Carbon({
  apiKey: process.env.CARBON_API_KEY,
  baseUrl: "https://ingest.oncarbon.site",
});

apiKey · string · default: "process.env.CARBON_API_KEY"

API key used to authenticate with the ingest API. Create one in the dashboard under Settings → API Keys.

baseUrl · string · default: "https://ingest.oncarbon.site"

Base URL of the ingest API. Override only when pointing at a non-production environment.

bufferBatchSize · number · default: "50"

Number of buffered events that triggers an immediate flush.

bufferMaxBatchBytes · number · default: "3670016"

Maximum serialized batch size in bytes (3.5 MiB). A batch flushes before it would exceed this size. A single event larger than this limit throws at capture time.

bufferMaxTimeMs · number · default: "5000"

Maximum time in milliseconds an event waits in the buffer before a scheduled flush sends it.

transport · T_EventTransport

Custom transport for delivering event batches. Defaults to HttpTransport. See Transports.

Buffering and flushing

Captured events go into an in-memory buffer. A flush happens when any of these is reached:

• the buffer holds bufferBatchSize events (50 by default)
• the next event would push the serialized batch past bufferMaxBatchBytes
• an event has waited bufferMaxTimeMs (5 seconds by default)

Background flushes retry transient failures automatically and never throw into your application code. Failed batches return to the front of the buffer, so event order is preserved.

Flushing on shutdown

flushPendingEvents drains the buffer and resolves once every event is delivered. It rejects if delivery ultimately fails, so callers can decide how to handle loss at shutdown:

try {
  await carbon.flushPendingEvents();
} catch (error) {
  console.error("Carbon flush failed", error);
}

Call it before exit in serverless functions and other short-lived environments — scripts, CLIs, batch jobs. Long-running servers only need it for graceful shutdown.

HTTP delivery and retries

The default HttpTransport posts batches to POST /v1/ingest-events with your API key as a bearer token.

• Requests time out after 15 seconds.
• Failed requests are retried up to 2 times, within a 30 second overall window.
• Responses with status 408, 409, 425, 429, or any 5xx are retried; other 4xx responses are not.

Delivery failures surface as CarbonIngestError, which carries status (the HTTP status, when available) and retryable.

import { HttpTransport } from "@carbon-js/sdk";

const carbon = new Carbon({
  transport: new HttpTransport({
    apiKey: process.env.CARBON_API_KEY,
    timeoutMs: 30_000,
    retryMaxAttempts: 4,
    retryMaxElapsedMs: 60_000,
  }),
});

The ingest API deduplicates by event ID, so retried batches never create duplicate events. See Delivery guarantees.

Transports

A transport implements sendBatch({ batch }). Three are built in:

Transport	Use
HttpTransport	Production delivery to the ingest API (default)
MemoryTransport	Tests — batches accumulate on the in-memory batches array
FileTransport	Local development — each batch is written as a JSON file

import { Carbon, MemoryTransport } from "@carbon-js/sdk";

const transport = new MemoryTransport();
const carbon = new Carbon({ transport });

// ...exercise your code, then assert on captured events
expect(transport.batches[0].events).toHaveLength(1);

FileTransport accepts a dirPath option and defaults to .tmp in the working directory:

import { Carbon, FileTransport } from "@carbon-js/sdk";

const carbon = new Carbon({
  transport: new FileTransport({ dirPath: "./carbon-events" }),
});