Jump to a page

@nightowlsdev/telemetry-core

Telemetry

Shared SwarmSpan-to-OpenTelemetry replay engine that the OTLP and Langfuse telemetry adapters are built on.

What it does

Takes the pre-recorded run/generation/tool SwarmSpans that @nightowlsdev/core's engine emits at the end of a swarm run and replays them through a real OpenTelemetry BasicTracerProvider. It derives a deterministic 32-hex trace id from the run id (UUIDs are dash-stripped; other ids are sha256-hashed), nests generation/tool children under the run span, maps generations to gen_ai.* semantic conventions (model, input/output token usage, cost_usd), replays the original epoch-ms timings, and awaits forceFlush() so nothing is lost in serverless invocations. You normally don't depend on it directly: backend adapters call replayerExporter({ exporter | processor }) and return the resulting TelemetryExporter from their own factory.

Install

pnpm add @nightowlsdev/telemetry-core

Key exports

createSpanReplayer
replayerExporter
deriveTraceId
deriveRootSpanId
KIND_MAP
toOtelAttributes
SpanReplayer (type)
SpanReplayerOpts (type)

Usage

telemetry-core.ts

import { replayerExporter } from "@nightowlsdev/telemetry-core";

// Backend adapters build on this, wrap an OTel exporter into a TelemetryExporter.
export function myTelemetry(exporter) {
  return replayerExporter({ exporter });
}