Documentation / @agentick/core / Telemetry

Class: Telemetry

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

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:347

End the current trace.

Returns

void

---

getCounter()

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

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

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:369

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:340

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:294

Reset to the default no-op provider.

Returns

void

---

setProvider()

static setProvider(provider): void

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

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:319

Start a new span within the current trace.

If the active KernelContext carries baggage, every key/value is applied to the new span via setAttributes before returning. This is how Context.withBaggage(...) and proc.withBaggage(...) propagate ambient attributes onto every span in their scope without callers having to pass anything through.

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:303

Start a new trace.

Parameters

name?

string = "operation"

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

Returns

string

The trace ID