@agentskit/observability — Functions

Summarize a flat span list into a TraceReport — totals, error count, wall-clock duration. The report JSON is the on-disk format written by createFileTraceSink and the input consumed by renderTraceViewerHtml.

#Parameters

#traceId

string

#spans

TraceSpan[]

#Returns

TraceReport

#Function: chargebackReport()

chargebackReport(samples, options?): ChargebackReport

Defined in: observability/src/cost-chargeback.ts:133

#Parameters

#samples

CostSample[]

#options?

ChargebackReportOptions = \{\}

#Returns

ChargebackReport

#Function: chargebackReportToCsv()

chargebackReportToCsv(report): string

Defined in: observability/src/cost-chargeback.ts:207

#Parameters

#report

ChargebackReport

#Returns

string

#Function: computeCost()

computeCost(usage, price): number

Defined in: observability/src/cost-guard.ts:152

Compute dollar cost from a usage record plus a price record. Hostile token counts are normalized to zero so NaN never poisons totals.

#Parameters

#usage

#completionTokens

number

#promptTokens

number

#price

TokenPrice

#Returns

number

#Function: consoleAlertSink()

consoleAlertSink(): CostAlertSink

Defined in: observability/src/cost-guard-alert-sinks.ts:10

Console alert sink — [cost:<type>] <tenant> <window> $<cost>/$<budget>.

#Returns

CostAlertSink

#Function: consoleLogger()

consoleLogger(config?): Observer

Defined in: observability/src/console-logger.ts:79

#Parameters

#config?

ConsoleLoggerConfig = \{\}

#Returns

Observer

#Function: costGuard()

costGuard(options): Observer & object

Defined in: observability/src/cost-guard.ts:254

A cost-guarded observer. Tracks token usage from llm:end events, computes running cost incrementally per active model, aborts the run when the budget is exceeded.

#Parameters

#options

CostGuardOptions

#Returns

#Function: countTokens()

countTokens(messages, options?): Promise<number>

Defined in: observability/src/token-counter.ts:88

Count (or estimate) tokens for a list of messages.

When no custom counter is provided, falls back to the built-in approximateCounter (zero deps, chars/4 heuristic).

#Parameters

#messages

readonly Pick<Message, "role" | "content">[]

#options?

TokenCounterOptions & object

#Returns

Promise<number>

#Example

import { countTokens } from '@agentskit/observability'

// Quick approximate count
const total = await countTokens(messages)

// With a custom provider-specific counter
const exact = await countTokens(messages, { counter: tiktokenCounter, model: 'gpt-4o' })

#Function: countTokensDetailed()

countTokensDetailed(messages, options?): Promise<TokenCountResult>

Defined in: observability/src/token-counter.ts:99

Same as countTokens but returns per-message breakdown.

#Parameters

#messages

readonly Pick<Message, "role" | "content">[]

#options?

TokenCounterOptions & object

#Returns

Promise<TokenCountResult>

#Function: createAdvancedCostGuard()

createAdvancedCostGuard(options): AdvancedCostGuard

Defined in: observability/src/cost-guard-advanced.ts:69

#Parameters

#options

AdvancedCostGuardOptions

#Returns

AdvancedCostGuard

#Function: createControlSurface()

createControlSurface(options?): ControlSurface

Defined in: observability/src/prod-control.ts:200

#Parameters

#options?

ControlSurfaceOptions = \{\}

#Returns

ControlSurface

#Function: createDevtoolsServer()

createDevtoolsServer(options?): DevtoolsServer

Defined in: observability/src/devtools.ts:45

In-process pub/sub hub for agent events. Transport-agnostic — hand the returned attach function any object that can send envelopes (an SSE response, a WebSocket, a test sink). Designed as the contract a browser devtools extension speaks against.

New clients receive a hello envelope followed by a replay of the ring buffer (so the extension can jump in mid-session and see recent history), then replay-end, then the live feed.

#Parameters

#options?

DevtoolsServerOptions = \{\}

#Returns

DevtoolsServer

#Function: createFileTraceSink()

createFileTraceSink(dir): FileTraceSink

Defined in: observability/src/trace-viewer.ts:112

Collect spans in memory and write them to disk on demand. The default layout under dir is: <traceId>.json — TraceReport (JSON) <traceId>.html — offline viewer page (when html !== false)

#Parameters

#dir

string

#Returns

FileTraceSink

#Function: createInMemoryAuditStore()

createInMemoryAuditStore(): AuditLogStore

Defined in: observability/src/audit-log.ts:179

In-memory AuditLogStore — tests, demos, transient deployments.

#Returns

AuditLogStore

#Function: createProviderCounter()

createProviderCounter(options): TokenCounter

Defined in: observability/src/token-counter.ts:168

Create a token counter backed by a real tokenizer.

This factory lets you plug in any tokenizer library (tiktoken, Anthropic's tokenizer, etc.) while conforming to the TokenCounter contract.

#Parameters

#options

ProviderTokenCounterOptions

#Returns

TokenCounter

#Example

import { createProviderCounter } from '@agentskit/observability'
import { encoding_for_model } from 'tiktoken'

const enc = encoding_for_model('gpt-4o')
const tiktokenCounter = createProviderCounter({
  name: 'tiktoken',
  tokenize: (text) => [...enc.encode(text)],
})

const tokens = await countTokens(messages, { counter: tiktokenCounter })

#Function: createSignedAuditLog()

createSignedAuditLog(options): SignedAuditLog

Defined in: observability/src/audit-log.ts:100

Hash-chained + HMAC-signed audit log. Every entry references the previous entry's hash, and every entry's body is signed with a caller-supplied secret. Together: tamper-evident (chain detects splicing) + authenticated (HMAC detects content edits by anyone who doesn't hold the secret).

Designed for SOC 2 / HIPAA friendly evidence. The store contract is three methods so you can back the log with SQLite, S3 + GCS, Postgres, or a read-only log service — anything append-only.

#Parameters

#options

AuditLogOptions

#Returns

SignedAuditLog

#Function: createTopologyGraph()

createTopologyGraph(options?): TopologyGraph

Defined in: observability/src/topology-graph.ts:97

#Parameters

#options?

TopologyGraphOptions = \{\}

#Returns

TopologyGraph

#Function: createTraceTracker()

createTraceTracker(callbacks): object

Defined in: observability/src/trace-tracker.ts:81

Builds nested spans from a sequential AgentEvent stream.

Assumption: events for the same kind (llm/tool/delegate) are sequential and non-interleaved. When present, the optional correlation envelope is copied to span attributes; it does not change the ordering contract.

#Parameters

#callbacks

TraceTrackerCallbacks

#Returns

object

#flush()

flush(): void

#Returns

void

#handle()

handle(event): void

#Parameters

event

CorrelatedAgentEvent

#Returns

void

#Function: datadogSink()

datadogSink(config): LifecycleObserver

Defined in: observability/src/datadog.ts:54

Datadog Logs sink. Batches span start/end as JSON log entries to Datadog's HTTP intake. Failures are isolated — observability never breaks the main loop.

#Parameters

#config

DatadogSinkConfig

#Returns

LifecycleObserver

#Function: diffState()

diffState(previous, next): readonly StateDiffEntry[]

Defined in: observability/src/replay-timeline.ts:84

#Parameters

#previous

Readonly<Record<string, unknown>>

#next

Readonly<Record<string, unknown>>

#Returns

readonly StateDiffEntry[]

#Function: langsmith()

langsmith(config): LangSmithObserver

Defined in: observability/src/langsmith.ts:49

LangSmith observer. Construction is pure (no SDK import). The SDK is loaded lazily on the first span that needs a remote run.

#Parameters

#config

LangSmithConfig

#Returns

LangSmithObserver

#Function: multiTenantCostGuard()

multiTenantCostGuard(options): Observer & object

Defined in: observability/src/cost-guard-multi-tenant.ts:94

Per-tenant cost-guard. Same incremental accounting as costGuard, partitioned by tenant id, with separate budgets per tenant and a no-abort default (the SaaS gateway typically enforces).

#Parameters

#options

MultiTenantCostGuardOptions

#Returns

#Function: newRelicSink()

newRelicSink(config): LifecycleObserver

Defined in: observability/src/new-relic.ts:51

New Relic Logs sink. Batches span start/end events to New Relic's Log API. Errors are isolated.

#Parameters

#config

NewRelicSinkConfig

#Returns

LifecycleObserver

#Function: opentelemetry()

opentelemetry(config?): OpenTelemetryObserver

Defined in: observability/src/opentelemetry.ts:73

OpenTelemetry observer. Construction is pure. SDK modules load lazily on the first span. Owned providers use OTel JS v2 spanProcessors constructor config.

#Parameters

#config?

OpenTelemetryConfig = \{\}

#Returns

OpenTelemetryObserver

#Function: positionAt()

positionAt(steps, timeline, index): ReplayPosition

Defined in: observability/src/replay-timeline.ts:110

#Parameters

#steps

readonly ReplayStep[]

#timeline

Timeline

#index

number

#Returns

ReplayPosition

#Function: priceFor()

priceFor(model, prices?): TokenPrice

Defined in: observability/src/cost-guard.ts:99

Look up the best price match for a model id. Prefix match — 'gpt-4o-mini' matches its own entry before 'gpt-4o'. Returns { input: 0, output: 0 } (free) for unknown models. Use hasPriceFor or resolvePrice when unknown-model handling must be explicit.

#Parameters

#model

string | undefined

#prices?

Record<string, TokenPrice> = DEFAULT_PRICES

#Returns

TokenPrice

#Function: renderTraceViewerHtml()

renderTraceViewerHtml(report): string

Defined in: observability/src/trace-viewer.ts:51

Render a self-contained HTML page visualizing a TraceReport as a gantt-style waterfall — no JS dependency, no network. Open the output file in a browser for offline Jaeger-style debugging.

#Parameters

#report

TraceReport

#Returns

string

#Function: replayBisect()

replayBisect(history, oracle, opts?): Promise<BisectVerdict>

Defined in: observability/src/replay-bisect.ts:28

Locate the earliest change that flips the run from pass to fail. Convention: index 0 is the oldest known-good change; higher indices are newer. The oracle returns 'fail' for any index ≥ the culprit and 'pass' before. Returns the first failing index, or all_clean / all_broken when no transition exists.

#Parameters

#history

readonly object[]

#oracle

ReplayOracle

#opts?

BisectOpts = \{\}

#Returns

Promise<BisectVerdict>

#Function: replayEvents()

replayEvents<E>(events, handlers): Promise<void>

Defined in: observability/src/replay.ts:11

#Type Parameters

#E

E

#Parameters

#events

readonly E[]

#handlers

readonly ReplayHandler<E>[]

#Returns

Promise<void>

#Function: sloObserver()

sloObserver(options?): SloObserver

Defined in: observability/src/slo.ts:157

#Parameters

#options?

SloOptions = \{\}

#Returns

SloObserver

#Function: throttle()

throttle(sink, windowMs, now?): CostAlertSink

Defined in: observability/src/cost-guard-alert-sinks.ts:50

Throttle wrapper — at most one alert per (tenant, window, type) per windowMs. Wrap any sink to bound emit rate.

#Parameters

#sink

CostAlertSink

#windowMs

number

#now?

() => number

#Returns

CostAlertSink

#Function: toSseFrame()

toSseFrame(envelope): string

Defined in: observability/src/devtools.ts:130

Serialize a devtools envelope as a single data: ...\n\n SSE frame. Framework-agnostic — hook into Express / Hono / plain http by writing the returned string to your response.