Manual capture

Wrappers cover the OpenAI, Anthropic, and Vercel AI SDKs. For anything else — custom inference stacks, other providers, backfills — construct canonical events yourself and capture them directly.

Capture methods

carbon.captureLlmCall({ event });   // one LLM event
carbon.captureToolCall({ event });  // one tool event
carbon.captureEvents({ events });   // a mixed batch

All three validate events synchronously against the canonical schema and throw on invalid input, then buffer the events for delivery like any wrapper-captured event. The full field reference is in the event schema.

LLM event example

import { randomUUID } from "node:crypto";

const startTimeMs = Date.now();
const result = await myInferenceCall(prompt);
const endTimeMs = Date.now();

carbon.captureLlmCall({
  event: {
    type: "llm",
    id: randomUUID(),
    startTimeMs,
    endTimeMs,
    durationMs: endTimeMs - startTimeMs,
    status: { state: "ok" },
    instrumentation: {
      vendor: "carbon",
      source: "openai",
      sourcePackage: "openai",
    },
    context: { userId: "user-481" },
    additionalProperties: {},
    properties: {
      llm: {
        model: "gpt-5.4-nano",
        input: { system: "You are concise.", prompt, tools: [] },
        output: { mode: "generate", response: result.text, toolCalls: [] },
        usage: {
          inputTokens: result.usage.inputTokens,
          inputTokenDetails: {
            uncachedTokens: result.usage.inputTokens,
            cacheReadTokens: 0,
            cacheWriteTokens: 0,
          },
          outputTokens: result.usage.outputTokens,
          outputTokenDetails: {
            reasoningTokens: 0,
            responseTokens: result.usage.outputTokens,
          },
          totalTokens: result.usage.inputTokens + result.usage.outputTokens,
        },
      },
    },
  },
});

Omit spaceId and cost — the ingest API sets the space from your API key and computes cost from its model catalog when it recognizes the model.

Tool event example

const startTimeMs = Date.now();
const output = await searchIndex({ query });
const endTimeMs = Date.now();

carbon.captureToolCall({
  event: {
    type: "tool",
    id: randomUUID(),
    traceId,
    startTimeMs,
    endTimeMs,
    durationMs: endTimeMs - startTimeMs,
    status: { state: "ok" },
    instrumentation: {
      vendor: "carbon",
      source: "vercel",
      sourcePackage: "ai",
    },
    context: { agentId: "search-agent" },
    additionalProperties: {},
    properties: {
      tool: {
        name: "search_index",
        input: JSON.stringify({ query }),
        output: JSON.stringify(output),
      },
    },
  },
});

Recording failures

Set status.state to "error" and include what you know about the failure:

status: {
  state: "error",
  error: {
    code: "rate_limit_exceeded",
    httpStatus: 429,
    message: "Provider rate limit hit",
  },
},

Failed calls appear in the dashboard with error status, so error rates can be sliced by model, agent, and user like any other dimension.

Sending without the SDK

If you are not on JavaScript, post the same event shapes to the ingest API directly — see the API reference.

Get started

Integrations

SDK

@carbon-js/connect

Concepts

Dashboard

Manual capture

Capture methods

LLM event example

Tool event example

Recording failures

Sending without the SDK

​Capture methods

​LLM event example

​Tool event example

​Recording failures

​Sending without the SDK

Capture methods

LLM event example

Tool event example

Recording failures

Sending without the SDK