Documentation / @agentick/kernel / Telemetry

Class: Telemetry

Defined in: kernel/src/telemetry.ts:159

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: kernel/src/telemetry.ts:206

End the current trace.

Returns

void

---

getCounter()

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

Defined in: kernel/src/telemetry.ts:217

Get or create a counter metric.

Parameters

name

string

Metric name (e.g., 'agentick.tokens')

unit?

string

Unit of measurement (e.g., 'count', 'bytes')

description?

string

Human-readable description

Returns

Counter

A Counter instance

---

getHistogram()

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

Defined in: kernel/src/telemetry.ts:228

Get or create a histogram metric.

Parameters

name

string

Metric name (e.g., 'agentick.latency')

unit?

string

Unit of measurement (e.g., 'ms', 'bytes')

description?

string

Human-readable description

Returns

Histogram

A Histogram instance

---

recordError()

static recordError(error): void

Defined in: kernel/src/telemetry.ts:199

Record an error in the current trace/span.

Parameters

error

any

The error to record

Returns

void

---

resetProvider()

static resetProvider(): void

Defined in: kernel/src/telemetry.ts:173

Reset to the default no-op provider.

Returns

void

---

setProvider()

static setProvider(provider): void

Defined in: kernel/src/telemetry.ts:166

Set the telemetry provider for all Agentick operations.

Parameters

provider

TelemetryProvider

The telemetry provider implementation

Returns

void

---

startSpan()

static startSpan(name): Span

Defined in: kernel/src/telemetry.ts:191

Start a new span within the current trace.

Parameters

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

Defined in: kernel/src/telemetry.ts:182

Start a new trace.

Parameters

name?

string = "operation"

Name of the trace (e.g., 'agent-execution')

Returns

string

The trace ID