@agentskit/observability — for agents

#Install

npm install @agentskit/observability

#Primary exports

#Loggers / tracers

• consoleLogger(config?) — local dev logging.
• langsmith(config) — LangSmith lifecycle observer (flush / idempotent shutdown; optional langsmith peer, lazy).
• opentelemetry(config) — OpenTelemetry lifecycle observer (optional OTel peers, lazy).
• createTraceTracker({ onSpanStart, onSpanEnd }) — low-level span lifecycle.

#Sinks (batch HTTP exporters)

All three return LifecycleObserver (flush(): Promise<void>, idempotent shutdown(): Promise<void>). Shared HttpBatchOptions defaults: batchSize 25, maxQueueSize 1000 (drop-oldest), flushIntervalMs 2000, maxRetries 3, retryBaseDelayMs 100, requestTimeoutMs 10000, plus isolated onError. Single-flight batching, timeout, and retries are best-effort — not an at-least-once guarantee. Await shutdown() on graceful termination.

• datadogSink(config) — Datadog Logs intake.
• axiomSink(config) — Axiom dataset ingest.
• newRelicSink(config) — New Relic Log API.

#Vendor adapters

• @agentskit/observability/langfuse — Langfuse logger backend. Install the optional langfuse peer when using this subpath.

#Guards + counters

• costGuard({ budgetUsd, controller, prices?, onCost?, onExceeded?, onError? }) — per-run dollar ceiling; aborts via AbortController when exceeded.
• multiTenantCostGuard({ budgets, defaultBudgetUsd?, tenantOf?, … }) — per-tenant bookkeeping; host enforces (no automatic abort).
• createAdvancedCostGuard({ budgets, caps?, mode?, disableRuntime?, alertSinks?, onError?, now? }) — production guard with rolling window caps, 50/80/100 % threshold + forecast alerts, and modes:
  • warn — observe only.
  • reject — host must consult isRejected(tenant) (window rejections clear on roll; overall until reset). Package does not abort the runtime.
  • kill — requires disableRuntime; use isDisabled(tenant); fail-closed if disable fails.
• Accounting is incremental per llm:end / active model; hostile usage normalizes to zero; zero-budget payloads stay finite. Callback/sink/clock errors are isolated.
• consoleAlertSink(), webhookAlertSink({ url, headers, fetch? }), throttle(sink, windowMs) — built-in alert sinks (webhook uses injected or globalThis.fetch; no-op if none).
• chargebackReport(samples, { groupBy, from, to }) + chargebackReportToCsv(report) — pure cost-attribution exporter.
• priceFor, computeCost, DEFAULT_PRICES — baseline prices; override for current provider rates.
• approximateCounter, countTokens, countTokensDetailed, createProviderCounter.

#PII redaction

• wrapObserverWithRedaction(observer, { rules, mode?, vault?, allowedRoles? }) — redact (or tokenize via @agentskit/core/security) string content fields in the AgentEvent stream (llm:end.content, tool:start.args, tool:end.result, agent:delegate:end.result, error.message) before they hit the underlying sink. Numeric / structural fields pass through unchanged so dashboards stay correct.

#Local trace viewer

• createFileTraceSink(dir), buildTraceReport, renderTraceViewerHtml. See Trace viewer.

#Devtools server

• createDevtoolsServer, toSseFrame. See Devtools server.
• createTopologyGraph — live multi-agent topology graph for the devtools UI.
• createControlSurface — production pause / step / replay control surface.

#SLO

• sloObserver(targets?), DEFAULT_SLO_TARGETS — emit SLO breach events from latency / error / cost windows.

#Signed audit log

• createSignedAuditLog, createInMemoryAuditStore. Hash-chain + HMAC. See Audit log.
• appendPiiAuditEvents(log, { actor, action, hits, subjectId?, reason? }) — append one signed entry per PII redaction hit to an existing SignedAuditLog. action is pii:redact, pii:reveal, or pii:reveal-denied; each payload records rule id, counts, and match offset/length only (no raw spans), for tamper-evident audit evidence alongside the hash chain.

#Replay & timeline

• replayEvents(events, handlers) — feed a historical event sequence through any number of handlers in order; generic over the event type, so it replays AgentEvents, TraceSpans, or a host app's own event union against live telemetry sinks.
• replayBisect(history, oracle, opts?) — O(log n) regression localisation. Given a change history (oldest-first) and an async oracle that returns 'pass' | 'fail' for a replay at a given index, it returns a BisectVerdict (culprit / all_clean / all_broken / inconsistent).
• buildTimeline(steps) — turn recorded ReplaySteps into a Timeline of rows carrying cumulative cost / token / latency totals plus the run span.
• diffState(previous, next) — structural diff between two state snapshots as add / remove / change entries.
• positionAt(steps, timeline, index) — resolve a scrubber position to its cumulative row plus the diffState from the previous checkpoint (throws on an out-of-range index).

#Minimal example

import { consoleLogger, costGuard, datadogSink } from '@agentskit/observability'
import { createRuntime } from '@agentskit/runtime'

const controller = new AbortController()
const dd = datadogSink({ apiKey: process.env.DD_API_KEY!, service: 'agent' })

const runtime = createRuntime({
  adapter,
  observers: [
    consoleLogger(),
    costGuard({ budgetUsd: 0.5, controller }),
    dd,
  ],
})

try {
  await runtime.run('…', { signal: controller.signal })
} finally {
  await dd.shutdown()
}

#Related

• @agentskit/eval
• @agentskit/runtime
• @agentskit/core/security — vault / tokenization used by wrapObserverWithRedaction.

#Source

• npm: https://www.npmjs.com/package/@agentskit/observability
• repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/observability