@telemetry-dev/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 telemetry.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @telemetry-dev/sdk
+
+Pure TypeScript SDK for [telemetry.dev](https://telemetry.dev): add LLM traces, logs, and GenAI
+metrics to any app. Built on OpenTelemetry — spans use the `gen_ai.*` semantic conventions and
+ship as OTLP protobuf to `https://ingest.telemetry.dev`. Works on Node >= 20.19 and edge runtimes
+(Vercel Edge, Cloudflare Workers with `nodejs_compat`). ESM-only; CJS consumers can `require()` it
+on Node >= 20.19.
+
+```sh
+npm install @telemetry-dev/sdk
+```
+
+## Quickstart
+
+```ts
+import { init, observe, startSpan, propagateAttributes, log, flush } from "@telemetry-dev/sdk";
+
+init({ apiKey: "td_live_..." }); // or TELEMETRY_DEV_API_KEY
+
+const answer = observe(
+  async function answer(question: string) {
+    const generation = startSpan("chat-completion", {
+      type: "generation",
+      model: "gpt-4o",
+      provider: "openai",
+      input: [{ role: "user", content: question }],
+    });
+    const res = await llm.chat(question);
+    generation.end({
+      output: res.message,
+      usage: { inputTokens: res.usage.input, outputTokens: res.usage.output },
+    });
+    log("generation finished", { attributes: { cached: false } });
+    return res.message;
+  },
+  { type: "agent" },
+);
+
+await propagateAttributes({ userId: "user_123", sessionId: "conv_42" }, () =>
+  answer("What is OTLP?"),
+);
+await flush();
+```
+
+Without an API key every call is a silent no-op — the SDK never throws into your code.
+
+## Configuration
+
+| Option        | Env var                     | Default                        |
+| ------------- | --------------------------- | ------------------------------ |
+| `apiKey`      | `TELEMETRY_DEV_API_KEY`     | — (absent ⇒ no-op)             |
+| `baseUrl`     | `TELEMETRY_DEV_BASE_URL`    | `https://ingest.telemetry.dev` |
+| `environment` | `TELEMETRY_DEV_ENVIRONMENT` | `production`                   |
+| `serviceName` | `OTEL_SERVICE_NAME`         | `unknown_service`              |
+
+Other `init()` options: `enabled` (kill switch), `registerGlobal`, `exportMode: "batched" |
+"immediate"`, `captureInput` / `captureOutput`, `mask(value, { key })` redaction hook,
+`maxAttributeLength` (default 65536, truncated values end with `...[truncated]`), `batch`
+(`maxExportBatchSize` 64, `scheduledDelayMillis` 1000, `maxQueueSize` 2048,
+`exportTimeoutMillis` 30000), `spanFilter`, `resourceAttributes`, `logLevel` (SDK diagnostics,
+default `"warn"`), `fetch`, `waitUntil`, `onError`.
+
+## API
+
+- `init(options?)` — create the client (isolated OTel TracerProvider by default).
+- `observe(fn, options?)` — wrap a sync/async function: args → input, return → output, errors
+  captured and rethrown; activates context for nesting.
+- `startSpan(name, options?)` — manual handle; does **not** activate context. `handle.update()`,
+  `handle.end()`, `handle.traceparent`, `handle.span` (raw OTel span).
+- `startActiveSpan(name, options?, fn)` — callback-scoped; activates context, auto-ends.
+- `updateActiveSpan(fields)` — update the innermost active span.
+- `propagateAttributes({ userId, sessionId, metadata }, fn)` — stamps `user.id`,
+  `gen_ai.conversation.id`, and `td.metadata.*` on every span and log record in scope.
+- `log(message, { level, eventName, attributes }?)` — log record correlated to the active trace.
+- `getTraceparent()` — W3C traceparent of the active span (pass to other services; accept it via
+  `startSpan(name, { parent })`).
+- `flush()` / `shutdown()` — export pending data; required before serverless freeze/exit.
+
+Span types: `span` (default) | `generation` | `tool` | `agent` | `embedding` — mapped to
+`gen_ai.operation.name` `function` / `chat` / `execute_tool` / `invoke_agent` / `embeddings`.
+Generation fields (`model`, `provider`, `usage`, `costUsd`, sampling params, …) map to the OTel
+GenAI semantic conventions; cost is computed server-side from usage unless `costUsd` is set.
+
+Duration and token-usage histograms (`gen_ai.client.operation.duration`,
+`gen_ai.client.token.usage`) are recorded automatically for generation/agent/embedding/tool spans.
+
+## Serverless
+
+Use `exportMode: "immediate"` and either `await flush()` before returning or pass the platform
+extender: `init({ waitUntil: (p) => ctx.waitUntil(p) })`. In batched mode spans wait up to
+`scheduledDelayMillis` for a timer that frozen isolates may never fire.
+
+## Bring your own OpenTelemetry
+
+If your app already runs an OTel setup (NodeSDK, `@vercel/otel`), don't use `init()` — attach the
+span processor to your provider; it exports every span it sees (narrow with `spanFilter`). The BYO
+surface ships as its own package and the SDK is not required for it:
+
+```sh
+npm i @telemetry-dev/otel
+```
+
+```ts
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { TelemetrySpanProcessor } from "@telemetry-dev/otel";
+
+const sdk = new NodeSDK({ spanProcessors: [new TelemetrySpanProcessor()] });
+sdk.start();
+```
+
+Alternatively `init({ registerGlobal: true })` makes the SDK's provider the app's global one; in
+that mode only this SDK's spans are exported by default.
+
+Any vanilla OTel app can also skip the SDK entirely: point a stock OTLP/HTTP protobuf exporter at
+`https://ingest.telemetry.dev/v1/traces` with an `Authorization: Bearer td_live_...` header.
+
+## Notes
+
+- AsyncLocalStorage powers context propagation. On runtimes without it (Workers without
+  `nodejs_compat`) automatic nesting is unavailable entirely unless the host app registered its
+  own global OTel context manager — pass `parent` explicitly there.
+- `@opentelemetry/api` is a peer dependency (installed automatically by npm/pnpm) so the SDK
+  shares the host app's OTel API singleton.

package/dist/index.d.mts

@@ -0,0 +1,184 @@
+import { AttributeValue, Context, Span, SpanContext } from "@opentelemetry/api";
+import { LogRecordExporter } from "@opentelemetry/sdk-logs";
+import { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
+import { BatchOptions, BatchOptions as BatchOptions$1, ExportMode, ExportMode as ExportMode$1, LogLevel, PropagatedAttributes, SdkLogLevel, SdkLogLevel as SdkLogLevel$1, propagateAttributes } from "@telemetry-dev/otel";
+import { PushMetricExporter } from "@opentelemetry/sdk-metrics";
+
+//#region src/config.d.ts
+/** Redaction hook applied to captured content (input/output/log message) before JSON stringification. */
+type MaskFn = (value: unknown, ctx: {
+  key: string;
+}) => unknown;
+interface TelemetryOptions {
+  /** telemetry.dev ingest key (`td_live_…`). Falls back to `TELEMETRY_DEV_API_KEY`. When absent the SDK is a no-op. */
+  apiKey?: string;
+  /** Ingest base URL. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  baseUrl?: string;
+  /** Deployment environment label. Falls back to `TELEMETRY_DEV_ENVIRONMENT`, then `production`. */
+  environment?: string;
+  /** Service name attached to every trace. Falls back to `OTEL_SERVICE_NAME`, then `unknown_service`. */
+  serviceName?: string;
+  /** Kill switch: `false` makes the SDK a complete no-op (tests). Default true. */
+  enabled?: boolean;
+  /** Register this SDK's TracerProvider/context manager/propagator globally. Default false (isolated). */
+  registerGlobal?: boolean;
+  /** "batched" (default) buffers spans; "immediate" exports per span (serverless). */
+  exportMode?: ExportMode$1;
+  /** Capture span inputs (args, prompts) by default. Default true. */
+  captureInput?: boolean;
+  /** Capture span outputs (results, completions) by default. Default true. */
+  captureOutput?: boolean;
+  /** Redaction hook run on captured content before stringify/truncate. */
+  mask?: MaskFn;
+  /** Truncation cap (chars) for content attributes; also set as the provider's attributeValueLengthLimit. Default 65536. */
+  maxAttributeLength?: number;
+  batch?: BatchOptions$1;
+  /** Export filter. Default when registerGlobal: only spans from this SDK's instrumentation scope. */
+  spanFilter?: (span: ReadableSpan) => boolean;
+  /** Extra resource attributes merged onto service.name / deployment.environment.name. */
+  resourceAttributes?: Record<string, AttributeValue>;
+  /** SDK self-diagnostics console level. Default "warn"; "silent" disables. */
+  logLevel?: SdkLogLevel$1;
+  /** Injected fetch implementation. Defaults to `globalThis.fetch`. */
+  fetch?: typeof fetch;
+  /** Serverless extender (e.g. Cloudflare `ctx.waitUntil`). When provided, `flush()` does not await exports. */
+  waitUntil?: (p: Promise<unknown>) => void;
+  /** Receives any error raised while emitting telemetry; the SDK never throws into user code. */
+  onError?: (error: unknown) => void;
+}
+//#endregion
+//#region src/attrs.d.ts
+type SpanType = "span" | "generation" | "tool" | "agent" | "embedding";
+interface TokenUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+  reasoningOutputTokens?: number;
+}
+interface GenerationFields {
+  model?: string;
+  provider?: string;
+  systemInstructions?: unknown;
+  responseModel?: string;
+  responseId?: string;
+  usage?: TokenUsage;
+  /** Optional client-side cost override; the server computes cost from usage by default. */
+  costUsd?: number;
+  finishReason?: string;
+  outputType?: string;
+  temperature?: number;
+  topP?: number;
+  topK?: number;
+  maxTokens?: number;
+  stopSequences?: string[];
+  seed?: number;
+  frequencyPenalty?: number;
+  presencePenalty?: number;
+  timeToFirstChunkMs?: number;
+}
+interface ToolFields {
+  toolName?: string;
+  toolCallId?: string;
+  toolDescription?: string;
+}
+interface AgentFields {
+  agentName?: string;
+  agentId?: string;
+}
+interface SpanFields extends GenerationFields, ToolFields, AgentFields {
+  /** Rename the span (update only). */
+  name?: string;
+  input?: unknown;
+  output?: unknown;
+  /** Marks the span failed: status ERROR + error.type + an "exception" event. */
+  error?: unknown;
+  /** td.metadata.<key> on this span only; use propagateAttributes for scope-wide metadata. */
+  metadata?: Record<string, unknown>;
+  /** Raw attribute escape hatch, merged last. */
+  attributes?: Record<string, AttributeValue>;
+}
+//#endregion
+//#region src/client.d.ts
+/** Test seam: inject in-memory exporters instead of the OTLP fetch transport. */
+interface ClientOverrides {
+  spanExporter?: SpanExporter;
+  logRecordExporter?: LogRecordExporter;
+  metricExporter?: PushMetricExporter;
+}
+interface TelemetryClient {
+  readonly enabled: boolean;
+  /** Never rejects; hands the export off to waitUntil when configured. */
+  flush(): Promise<void>;
+  /** Flush + teardown + unregister globals; the client becomes a no-op afterwards. */
+  shutdown(): Promise<void>;
+}
+declare function flush(): Promise<void>;
+declare function shutdown(): Promise<void>;
+declare function init(options?: TelemetryOptions, overrides?: ClientOverrides): TelemetryClient;
+//#endregion
+//#region src/logs.d.ts
+interface LogOptions {
+  /** Default "info". */
+  level?: LogLevel;
+  attributes?: Record<string, unknown>;
+  eventName?: string;
+  timestamp?: Date | number;
+}
+/**
+ * Emit a log record to /v1/logs, correlated to the active span (when any) and stamped with the
+ * propagated correlation attributes. Works inside and outside spans.
+ */
+declare function log(message: string, options?: LogOptions): void;
+//#endregion
+//#region src/span.d.ts
+type ParentRef = string | SpanHandle | SpanContext | Context;
+interface StartSpanOptions extends SpanFields {
+  /** Default "span" → operation "function". */
+  type?: SpanType;
+  /** Parent override; defaults to the active context. */
+  parent?: ParentRef;
+  startTime?: Date | number;
+  /** Per-call override of the global captureInput. */
+  captureInput?: boolean;
+  /** Per-call override of the global captureOutput. */
+  captureOutput?: boolean;
+}
+interface SpanHandle {
+  /** Raw OTel span (interop escape hatch). */
+  readonly span: Span;
+  /** Context with this span active, for manual parenting. */
+  readonly context: Context;
+  readonly traceId: string;
+  readonly spanId: string;
+  /** W3C traceparent for this span; null for the no-op handle. */
+  readonly traceparent: string | null;
+  readonly isRecording: boolean;
+  update(fields: SpanFields): SpanHandle;
+  end(fields?: SpanFields & {
+    endTime?: Date | number;
+  }): void;
+}
+/** Start a span WITHOUT activating context; the caller must call .end(). */
+declare function startSpan(name: string, options?: StartSpanOptions): SpanHandle;
+declare function startActiveSpan<T>(name: string, fn: (span: SpanHandle) => T): T;
+declare function startActiveSpan<T>(name: string, options: StartSpanOptions, fn: (span: SpanHandle) => T): T;
+/** Update the innermost active span; no-op when none is recording. */
+declare function updateActiveSpan(fields: SpanFields): void;
+/** Serialize the active span context as a W3C traceparent; null when there is none. */
+declare function getTraceparent(): string | null;
+//#endregion
+//#region src/observe.d.ts
+interface ObserveOptions extends StartSpanOptions {
+  /** Span name; defaults to fn.name or "anonymous". */
+  name?: string;
+}
+/**
+ * Wrap a function (sync or async) so every call becomes a span: args → input, return value →
+ * output, thrown/rejected errors captured and rethrown. Activates context so nested SDK calls
+ * parent to it. Resolves the client at call time, so wrapping at module load before init() works.
+ */
+declare function observe<TArgs extends unknown[], TReturn>(fn: (...args: TArgs) => TReturn, options?: ObserveOptions): (...args: TArgs) => TReturn;
+//#endregion
+export { type AgentFields, type BatchOptions, type ClientOverrides, type ExportMode, type GenerationFields, type LogLevel, type LogOptions, type MaskFn, type ObserveOptions, type ParentRef, type PropagatedAttributes, type SdkLogLevel, type SpanFields, type SpanHandle, type SpanType, type StartSpanOptions, type TelemetryClient, type TelemetryOptions, type TokenUsage, type ToolFields, flush, getTraceparent, init, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan };