TypeScript API: Trace viewer

A local page that shows your runs, with no account. Generated from the declarations and doc comments of criogenai 0.1.7. See also: TypeScript API overview, the same module in Python.

import { serveTraces, TraceViewer, TraceViewerOptions } from "criogenai";

Contents#

serveTraces#

function serveTraces(options?: TraceViewerOptions): Promise<TraceViewer>

Starts the local trace viewer in the background.

It receives traces over OTLP/HTTP (Telemetry.local() sends there) and shows each run on a page at viewer.url. Node only; the same viewer runs from the command line with npx criogenai trace.

Parameters

• options (TraceViewerOptions, default {}): Port, host, database, retention, prices and token.

Returns: The running viewer: its url and stop().

Raises

• ValidationError: The viewer cannot start (invalid_value): the port is taken, the database cannot be opened, or the host is not this computer and there is no token.
• CriogenError: The engine has no trace viewer (unsupported, e.g. in the browser).

Example

import { Agent, FakeModel, Telemetry, serveTraces } from "criogenai";

const viewer = await serveTraces({ port: 0, db: ":memory:" });
const telemetry = Telemetry.local({ url: viewer.url });
const agent = new Agent({ model: new FakeModel(["Hello."]), telemetry });
await agent.run("Hi");
await telemetry.flush();
console.log(`Open ${viewer.url} to see the run.`);
await viewer.stop();

TraceViewer#

interface TraceViewer {
  readonly url: string;
  stop(): Promise<void>;
}

A viewer serving in the background.

Fields

• url (string): The page's address.
• stop (() => Promise<void>): Stops serving. The runs stay in the database file. Calling it twice does nothing.

TraceViewerOptions#

interface TraceViewerOptions {
  port?: number;
  host?: string;
  db?: string;
  keepRuns?: number;
  keepDays?: number;
  prices?: Record<string, { input?: number; output?: number }>;
  token?: string;
}

Settings for serveTraces.

Fields

• port (number, optional): Default 4318 (OTLP/HTTP's port); 0 picks a free one.
• host (string, optional): Default "127.0.0.1"; anything else needs a token.
• db (string, optional): A SQLite file (default ~/.criogen/traces.db) or ":memory:".
• keepRuns (number, default 10000): How many of the newest runs are kept (at least 1); older ones are deleted.
• keepDays (number, default 14): How many days a run is kept (at least 1).
• prices (Record<string, { input?: number; output?: number; }>, optional): USD per million tokens by "provider:model" or model name, for the cost column.
• token (string, optional): Clients must send Authorization: Bearer <token>.