TypeScript API: Telemetry

Exporting runs to Langfuse or any OpenTelemetry backend. Generated from the declarations and doc comments of criogenai 0.1.7. See also: TypeScript API overview, the same module in Python.

import { Telemetry, TelemetryOptions } from "criogenai";

Contents#

Telemetry#

class Telemetry {
  constructor(spec: Record<string, unknown>);
}

An exporter shared by any number of agents: new Agent({ …, telemetry }). Exports in the background; call flush() before a script ends, and shutdown() when done.

Each run becomes one trace, with spans for steps, model calls and tool calls. Without captureContent the trace holds names, timings, token counts and error codes, not prompts or outputs.

Parameters

• spec (Record<string, unknown>): The exporter's settings, as the engine reads them.

Example

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

// Sends to the local trace viewer: start it first with `npx criogenai trace`.
const telemetry = Telemetry.local();
const agent = new Agent({ model: new FakeModel(["Hello."]), telemetry });
await agent.run("Hi");
await telemetry.flush();
console.log(telemetry.stats()); // e.g. { exported: 3, failed: 0, dropped: 0, lastError: null }

Telemetry.langfuse#

static langfuse(options?: TelemetryOptions & { publicKey?: string; secretKey?: string; baseUrl?: string; }): Telemetry

Langfuse (cloud or self-hosted). Keys default to LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY and the address to LANGFUSE_BASE_URL.

Parameters

• options (TelemetryOptions & { publicKey?: string; secretKey?: string; baseUrl?: string; }, default {}): publicKey and secretKey (pass both, or neither to read both from the environment), baseUrl (when given it is always used; else LANGFUSE_BASE_URL or LANGFUSE_HOST, else https://cloud.langfuse.com), plus captureContent and serviceName.

Raises

• ValidationError: Only one key was passed, or none and the environment variables are not set (invalid_value).

Example

import { Agent, Telemetry } from "criogenai";

// Reads LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY and LANGFUSE_BASE_URL.
const telemetry = Telemetry.langfuse({ serviceName: "support-bot" });
const agent = new Agent({ model: "openai:gpt-5-mini", telemetry });
await agent.run("Hello");
await telemetry.shutdown();

Telemetry.otlp#

static otlp(endpoint: string, options?: TelemetryOptions & { headers?: Record<string, string>; }): Telemetry

Any OTLP/HTTP (JSON) collector, e.g. "http://localhost:4318/v1/traces".

Parameters

• endpoint (string): The collector's traces URL, including its path (usually /v1/traces).
• options (TelemetryOptions & { headers?: Record<string, string>; }, default {}): headers sent with every export (e.g. an API key), plus captureContent and serviceName.

Example

import { Telemetry } from "criogenai";

const telemetry = Telemetry.otlp("https://otel.example.com/v1/traces", {
  headers: { authorization: `Bearer ${process.env.OTEL_TOKEN}` },
  serviceName: "support-bot",
});

Telemetry.local#

static local(options?: TelemetryOptions & { url?: string; }): Telemetry

The local trace viewer (npx criogenai trace, serveTraces()). Content only with captureContent: true; it stays on this computer either way.

Parameters

• options (TelemetryOptions & { url?: string; }, default {}): url: the viewer's address (default http://127.0.0.1:4318; /v1/traces is added), plus captureContent and serviceName.

Telemetry.flush#

flush(): Promise<void>

Waits until everything sent so far is exported.

Telemetry.shutdown#

shutdown(): Promise<void>

Exports what is left and stops.

Telemetry.stats#

stats(): { exported: number; failed: number; dropped: number; lastError: string | null; }

Exported, failed and dropped counts, and the last error.

Returns: exported: spans the backend accepted. failed: spans lost after failed export attempts. dropped: events dropped because the queue was full (a run is never blocked). lastError: the last export error, or null.

Telemetry.toJSON#

toJSON(): Record<string, unknown>

{ telemetry: true }: the exporter's settings (keys, headers) never appear in JSON output.

TelemetryOptions#

interface TelemetryOptions {
  captureContent?: boolean;
  serviceName?: string;
}

Settings every exporter takes.

Fields

• captureContent (boolean, optional): Send message text and tool arguments too (default false).
• serviceName (string, default "criogenai"): The service.name of the traces.