Introductionv0.1.4

Koralog is an observability SDK for applications using LLMs (Anthropic, OpenAI, Gemini). It monitors latency, errors, estimated cost, and usage per feature/user — sending data to the Koralog backend without interfering with your application's flow.

The SDK is designed to be non-intrusive: if not initialized, track() passes through without instrumenting. Network failures are always silent and never propagate to your application.

Installation

Install Koralog from npm:

npm install koralog

AI-powered Setup

Instead of applying track() manually, paste the Koralog setup prompt into any AI coding assistant (Claude, Cursor, Copilot) and it will handle everything autonomously:

// Before
const response = await fetch('https://api.openai.com/v1/chat/completions', options)
const data = await response.json()
const content = data.choices[0].message.content

// After
import { track } from '@/lib/koralog'

const data = await track(
  () => fetch('https://api.openai.com/v1/chat/completions', options).then(res => res.json()),
  {
    feature: 'chat-sendMessage',
    provider: 'openai',
    model: 'gpt-4o', // required for fetch — not auto-detected
  }
)
const content = data.choices[0].message.content

Quick Start

Full working example — init, identify a user, track an LLM call, and flush before shutdown.

import { init, track, setUser, shutdown } from 'koralog'

init({
  apiKey: 'kora_live_abc123',
  serverless: false,
  debug: false,
})

setUser({ id: 'usr_456', email: 'maria@company.com', name: 'Maria' })

const response = await track(
  () => anthropic.messages.create({
    model: 'claude-sonnet-4-6',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Explain JWT in 3 lines.' }],
  }),
  {
    feature: 'explain-tech',
    provider: 'anthropic',
    model: 'claude-sonnet-4-6',
    tags: { env: 'prod', version: '2' },
    requestParams: { temperature: 0.5, max_tokens: 1024 },
  }
)

// On server shutdown:
await shutdown()

init()

Initializes the SDK. Must be called once at application boot, before any track() calls. Calling it multiple times has no effect after the first call.

import { init } from 'koralog'

init({
  apiKey: 'kora_live_abc123',
  debug: false,
  serverless: true,
})

track()

Wraps an async function (typically an LLM call) and records latency, status, and error type. Returns the same value the original function would return. If the SDK is not initialized, the function runs without any overhead.

import { track } from 'koralog'

const response = await track(
  () => anthropic.messages.create({
    model: 'claude-sonnet-4-6',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello' }],
  }),
  {
    feature: 'chat',
    provider: 'anthropic',
    model: 'claude-sonnet-4-6',
    tags: { env: 'prod' },
  }
)

setUser()

Defines the active user for the current session or request. User data (id, email, name) is merged into all subsequent events until clearUser() is called.

clearUser()

Removes the active user. Events after this call will not include user data unless setUser() is called again.

import { setUser, clearUser } from 'koralog'

setUser({ id: 'usr_123', email: 'user@example.com', name: 'Alice' })

// later, to remove the active user:
clearUser()

flush()

Forces immediate dispatch of all queued events. Returns a Promise that resolves when the flush completes.

shutdown()

Alias for flush(). Semantically clearer at process termination — call it in your SIGTERM or process.on('exit') handler to ensure all events are sent before the process exits.

import { flush, shutdown } from 'koralog'

// Force immediate send:
await flush()

// Before process exit:
await shutdown()

KoralogConfig

Options object passed to init(). Only apiKey is required.

TrackMetadata

Optional second argument to track(). All fields are optional and can be combined freely.

Payload Reference

Each event sent to the Koralog backend contains these fields:

Error Classification

The SDK automatically classifies exceptions intercepted inside track(). After recording, the original exception is always rethrown.

Batching Strategy

Privacy & Sensitive Fields

Koralog is privacy-first by default. The SDK strips response content fields before sending payloads:

To capture full response content, set capturePrompts: true in init().

To include userIp and custom sensitive fields, set showSensitiveFields: true.

API Key Modes

The API key prefix determines where events are sent. A custom baseUrl overrides both prefix-based endpoints.