AIDK API Reference / aidk-kernel / Telemetry

Class: Telemetry

Defined in: packages/kernel/src/telemetry.ts:161

Global telemetry service for tracing, spans, and metrics.

By default, uses a no-op provider. Call Telemetry.setProvider() to integrate with your observability platform (OpenTelemetry, DataDog, etc.).

Traces and Spans

Traces represent end-to-end operations. Spans are units of work within a trace.

const traceId = Telemetry.startTrace('agent-execution');
const span = Telemetry.startSpan('model-call');
try {
  // ... do work
  span.setAttribute('model', 'gpt-4');
} finally {
  span.end();
}
Telemetry.endTrace();

Metrics

Counters track cumulative values. Histograms track distributions.

const tokenCounter = Telemetry.getCounter('tokens', 'count', 'Token usage');
tokenCounter.add(150, { model: 'gpt-4', type: 'input' });

const latency = Telemetry.getHistogram('latency', 'ms', 'Response time');
latency.record(250);

See

TelemetryProvider - Implement this to add a custom provider

Constructors

Constructor

new Telemetry(): Telemetry;

Returns

Telemetry

Methods

endTrace()

static endTrace(): void;

Defined in: packages/kernel/src/telemetry.ts:208

End the current trace.

Returns

void

---

getCounter()

static getCounter(
   name: string, 
   unit?: string, 
   description?: string): Counter;

Defined in: packages/kernel/src/telemetry.ts:219

Get or create a counter metric.

Parameters

Parameter	Type	Description
name	string	Metric name (e.g., 'aidk.tokens')
unit?	string	Unit of measurement (e.g., 'count', 'bytes')
description?	string	Human-readable description

Returns

Counter

A Counter instance

---

getHistogram()

static getHistogram(
   name: string, 
   unit?: string, 
   description?: string): Histogram;

Defined in: packages/kernel/src/telemetry.ts:230

Get or create a histogram metric.

Parameters

Parameter	Type	Description
name	string	Metric name (e.g., 'aidk.latency')
unit?	string	Unit of measurement (e.g., 'ms', 'bytes')
description?	string	Human-readable description

Returns

Histogram

A Histogram instance

---

recordError()

static recordError(error: any): void;

Defined in: packages/kernel/src/telemetry.ts:201

Record an error in the current trace/span.

Parameters

Parameter	Type	Description
error	any	The error to record

Returns

void

---

resetProvider()

static resetProvider(): void;

Defined in: packages/kernel/src/telemetry.ts:175

Reset to the default no-op provider.

Returns

void

---

setProvider()

static setProvider(provider: TelemetryProvider): void;

Defined in: packages/kernel/src/telemetry.ts:168

Set the telemetry provider for all AIDK operations.

Parameters

Parameter	Type	Description
provider	TelemetryProvider	The telemetry provider implementation

Returns

void

---

startSpan()

static startSpan(name: string): Span;

Defined in: packages/kernel/src/telemetry.ts:193

Start a new span within the current trace.

Parameters

Parameter	Type	Description
name	string	Name of the span (e.g., 'model-call', 'tool-execution')

Returns

Span

A Span object to track the operation

---

startTrace()

static startTrace(name: string): string;

Defined in: packages/kernel/src/telemetry.ts:184

Start a new trace.

Parameters

Parameter	Type	Default value	Description
name	string	"operation"	Name of the trace (e.g., 'agent-execution')

Returns

string

The trace ID