@telemetry-dev/otel 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,87 @@
+# @telemetry-dev/otel
+
+Bring-your-own OpenTelemetry base layer for [telemetry.dev](https://telemetry.dev). It provides the span processor and OTLP/protobuf trace exporter used by `@telemetry-dev/sdk`, without requiring the SDK runtime.
+
+```sh
+npm i @telemetry-dev/otel
+```
+
+`@opentelemetry/api` is a peer dependency and is installed automatically by current npm and pnpm versions.
+
+## NodeSDK
+
+```ts
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { TelemetrySpanProcessor } from "@telemetry-dev/otel";
+
+const sdk = new NodeSDK({
+  spanProcessors: [new TelemetrySpanProcessor()],
+});
+
+sdk.start();
+```
+
+## Vercel / Next.js `registerOTel`
+
+```ts
+import { registerOTel } from "@vercel/otel";
+import { TelemetrySpanProcessor } from "@telemetry-dev/otel";
+
+export function register() {
+  registerOTel({
+    serviceName: "my-app",
+    spanProcessors: [new TelemetrySpanProcessor()],
+  });
+}
+```
+
+## BasicTracerProvider
+
+```ts
+import { trace } from "@opentelemetry/api";
+import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+import { TelemetrySpanProcessor } from "@telemetry-dev/otel";
+
+const provider = new BasicTracerProvider({
+  spanProcessors: [new TelemetrySpanProcessor()],
+});
+
+trace.setGlobalTracerProvider(provider);
+```
+
+## Options
+
+| Option         | Fallback                                                      | Default / behavior                                                                                                    |
+| -------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `apiKey`       | `TELEMETRY_DEV_API_KEY`                                       | When absent and no `spanExporter` override is provided, the processor is a no-op.                                     |
+| `baseUrl`      | `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev` | Trailing slashes are removed before building OTLP URLs.                                                               |
+| `exportMode`   | —                                                             | `"batched"`; use `"immediate"` for serverless paths that flush explicitly.                                            |
+| `batch`        | —                                                             | Merged over `{ maxExportBatchSize: 64, scheduledDelayMillis: 1000, maxQueueSize: 2048, exportTimeoutMillis: 30000 }`. |
+| `spanFilter`   | —                                                             | Exports every span by default because attaching the processor is an explicit BYO choice.                              |
+| `metrics`      | —                                                             | `true`; records GenAI duration/token histograms when an API key is present.                                           |
+| `serviceName`  | `OTEL_SERVICE_NAME`                                           | `unknown_service`; used on the metrics resource.                                                                      |
+| `environment`  | `TELEMETRY_DEV_ENVIRONMENT`                                   | `production`; used as `deployment.environment.name` on the metrics resource.                                          |
+| `fetch`        | —                                                             | `globalThis.fetch`; override for tests or custom runtimes.                                                            |
+| `onError`      | —                                                             | Receives export and processor errors; errors are also reported through diagnostics.                                   |
+| `spanExporter` | —                                                             | Advanced/test seam replacing the built-in OTLP trace exporter.                                                        |
+
+## Missing API key behavior
+
+`new TelemetrySpanProcessor()` never throws. Without an API key, and without a `spanExporter` override, it becomes a no-op processor and emits only a debug-level diagnostic. This makes it safe to construct during local development or in environments where telemetry is disabled.
+
+## Raw span exporter
+
+Use `createTelemetrySpanExporter()` when you want to keep your own `BatchSpanProcessor` or `SimpleSpanProcessor` but send OTLP/HTTP protobuf payloads to telemetry.dev.
+
+```ts
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { createTelemetrySpanExporter } from "@telemetry-dev/otel";
+
+const processor = new BatchSpanProcessor(createTelemetrySpanExporter());
+```
+
+The exporter reads `apiKey`, `baseUrl`, `fetch`, and `onError` from the same option names and environment variables as `TelemetrySpanProcessor`.
+
+## Correlation attributes
+
+`propagateAttributes({ userId, sessionId, metadata }, fn)` works standalone with BYO providers. The function stores correlation attributes in the same OTel context key that `TelemetrySpanProcessor` reads on span start, so spans created inside `fn` receive `user.id`, `gen_ai.conversation.id`, and `td.metadata.*` attributes without installing `@telemetry-dev/sdk`.

package/dist/index.d.mts

@@ -0,0 +1,195 @@
+import { Attributes, Context, ContextManager } from "@opentelemetry/api";
+import { PushMetricExporter } from "@opentelemetry/sdk-metrics";
+import { Resource } from "@opentelemetry/resources";
+import { ReadableSpan, Span, SpanExporter, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { LogRecordExporter } from "@opentelemetry/sdk-logs";
+
+//#region src/attrs.d.ts
+declare const SCOPE_NAME = "@telemetry-dev/sdk";
+declare const SCOPE_VERSION = "0.0.0";
+declare function omitUndefined(attributes: Attributes): Attributes;
+declare function jsonAttr(value: unknown): string | undefined;
+//#endregion
+//#region src/config.d.ts
+type LogLevel = "debug" | "info" | "warn" | "error";
+type SdkLogLevel = LogLevel | "silent";
+type ExportMode = "batched" | "immediate";
+interface BatchOptions {
+  /** Spans per export batch. LLM spans are large; keep batches small. Default 64. */
+  maxExportBatchSize?: number;
+  /** Delay between batch exports in milliseconds. Default 1000. */
+  scheduledDelayMillis?: number;
+  /** Maximum spans buffered before drops. Default 2048. */
+  maxQueueSize?: number;
+  /** Per-export timeout in milliseconds. Default 30000. */
+  exportTimeoutMillis?: number;
+}
+declare const DEFAULT_BASE_URL = "https://ingest.telemetry.dev";
+declare const DEFAULT_BATCH: Required<BatchOptions>;
+declare function resolveEnv(): Record<string, string | undefined>;
+//#endregion
+//#region src/context.d.ts
+declare const als: AsyncLocalStorage<Context> | undefined;
+/**
+ * The active context: our AsyncLocalStorage when available, falling back to the OTel global
+ * context (which joins a host app's own OTel setup when one is registered).
+ */
+declare function activeContext(): Context;
+/** Run `fn` with `ctx` active in both our ALS and the global OTel context manager. */
+declare function withContext<T>(ctx: Context, fn: () => T): T;
+declare const PROPAGATED_KEY: symbol;
+interface PropagatedAttributes {
+  /** Stamped as user.id on every span and log record in scope. */
+  userId?: string;
+  /** Stamped as gen_ai.conversation.id on every span and log record in scope. */
+  sessionId?: string;
+  /** Stamped as td.metadata.<key> on every span and log record in scope. */
+  metadata?: Record<string, unknown>;
+}
+declare function buildPropagatedAttributes(attrs: PropagatedAttributes): Attributes;
+declare function propagatedFromContext(ctx: Context): Attributes | undefined;
+/**
+ * Stamp correlation attributes (user, session/conversation, metadata) on every span and log
+ * record created inside `fn`. Inner scopes merge over outer ones per key. Works before init().
+ */
+declare function propagateAttributes<T>(attributes: PropagatedAttributes, fn: () => T): T;
+/** Minimal ContextManager over our AsyncLocalStorage, registered only for registerGlobal. */
+declare class AlsContextManager implements ContextManager {
+  private readonly storage;
+  constructor(storage: AsyncLocalStorage<Context>);
+  active(): Context;
+  with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(context: Context, fn: F, thisArg?: ThisParameterType<F>, ...args: A): ReturnType<F>;
+  bind<T>(context: Context, target: T): T;
+  enable(): this;
+  disable(): this;
+}
+//#endregion
+//#region src/debug.d.ts
+declare function setLogLevel(level: SdkLogLevel): void;
+declare const diag: {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+};
+/** Fail-open guard: SDK internals report through onError + diagnostics, never into user code. */
+declare function reportError(onError: ((error: unknown) => void) | undefined, error: unknown): void;
+//#endregion
+//#region src/metrics.d.ts
+declare const DURATION_BUCKETS: number[];
+declare const TOKEN_BUCKETS: number[];
+declare const DORMANT_INTERVAL_MS: number;
+declare const BATCHED_METRIC_INTERVAL_MS = 60000;
+interface MetricsPipeline {
+  record(span: ReadableSpan): void;
+  forceFlush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+declare function createMetricsPipeline({
+  resource,
+  exporter,
+  exportIntervalMillis
+}: {
+  resource: Resource;
+  exporter: PushMetricExporter;
+  exportIntervalMillis: number;
+}): MetricsPipeline;
+//#endregion
+//#region src/otel.d.ts
+interface TelemetrySpanProcessorOptions {
+  /** telemetry.dev ingest key. Falls back to `TELEMETRY_DEV_API_KEY`; absent ⇒ no-op processor. */
+  apiKey?: string;
+  /** Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  baseUrl?: string;
+  /** "batched" (default) or "immediate". */
+  exportMode?: ExportMode;
+  batch?: BatchOptions;
+  /** Default for BYO providers: export EVERY span (the user deliberately attached the processor). */
+  spanFilter?: (span: ReadableSpan) => boolean;
+  /** Record GenAI duration/token histograms for exported chat/agent/embedding/tool spans. Default true. */
+  metrics?: boolean;
+  /** service.name on the metrics resource. Falls back to `OTEL_SERVICE_NAME`. */
+  serviceName?: string;
+  /** deployment.environment.name on the metrics resource. Falls back to `TELEMETRY_DEV_ENVIRONMENT`. */
+  environment?: string;
+  fetch?: typeof fetch;
+  onError?: (error: unknown) => void;
+  /** Advanced/test seam: replaces the OTLP fetch exporter. */
+  spanExporter?: SpanExporter;
+}
+/**
+ * BYO-OpenTelemetry surface: add this processor to your own TracerProvider (NodeSDK,
+ * registerOTel, …) to ship its spans to telemetry.dev. Also stamps propagateAttributes
+ * correlation attributes onto every span it sees.
+ */
+declare class TelemetrySpanProcessor implements SpanProcessor {
+  private readonly inner?;
+  private readonly metrics?;
+  constructor(options?: TelemetrySpanProcessorOptions);
+  onStart(span: Span, parentContext: Context): void;
+  onEnd(span: ReadableSpan): void;
+  forceFlush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+/** Raw OTLP/protobuf fetch exporter for users wiring their own BatchSpanProcessor. */
+declare function createTelemetrySpanExporter(options?: {
+  apiKey?: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+  onError?: (error: unknown) => void;
+}): SpanExporter;
+//#endregion
+//#region src/processor.d.ts
+interface StampingProcessorOptions {
+  exporter: SpanExporter;
+  exportMode: ExportMode;
+  batch: Required<BatchOptions>;
+  spanFilter?: (span: ReadableSpan) => boolean;
+  recordMetrics?: (span: ReadableSpan) => void;
+  onError?: (error: unknown) => void;
+}
+/**
+ * The vendor span processor: stamps propagated correlation attributes onto every span at start,
+ * then filters, records auto-metrics, and delegates to a Batch/SimpleSpanProcessor at end.
+ */
+declare class StampingSpanProcessor implements SpanProcessor {
+  private readonly options;
+  private readonly inner;
+  constructor(options: StampingProcessorOptions);
+  onStart(span: Span, parentContext: Context): void;
+  onEnd(span: ReadableSpan): void;
+  forceFlush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+//#endregion
+//#region src/transport.d.ts
+interface Transport {
+  fetchImpl: typeof fetch;
+  onError?: (error: unknown) => void;
+}
+interface OtlpTarget {
+  url: string;
+  headers: Record<string, string>;
+}
+declare const postOtlp: ({
+  fetchImpl,
+  url,
+  headers,
+  body
+}: {
+  fetchImpl: typeof fetch;
+  url: string;
+  headers: Record<string, string>;
+  body: Uint8Array;
+}) => Promise<Response>;
+declare function maybeGzip(body: Uint8Array): Promise<{
+  body: Uint8Array;
+  contentEncoding?: "gzip";
+}>;
+declare function createTraceExporter(target: OtlpTarget, transport: Transport): SpanExporter;
+declare function createLogExporter(target: OtlpTarget, transport: Transport): LogRecordExporter;
+declare function createMetricExporter(target: OtlpTarget, transport: Transport): PushMetricExporter;
+declare function otlpHeaders(apiKey: string): Record<string, string>;
+//#endregion
+export { AlsContextManager, BATCHED_METRIC_INTERVAL_MS, type BatchOptions, DEFAULT_BASE_URL, DEFAULT_BATCH, DORMANT_INTERVAL_MS, DURATION_BUCKETS, type ExportMode, type LogLevel, type MetricsPipeline, type OtlpTarget, PROPAGATED_KEY, type PropagatedAttributes, SCOPE_NAME, SCOPE_VERSION, type SdkLogLevel, type StampingProcessorOptions, StampingSpanProcessor, TOKEN_BUCKETS, TelemetrySpanProcessor, type TelemetrySpanProcessorOptions, type Transport, activeContext, als, buildPropagatedAttributes, createLogExporter, createMetricExporter, createMetricsPipeline, createTelemetrySpanExporter, createTraceExporter, diag, jsonAttr, maybeGzip, omitUndefined, otlpHeaders, postOtlp, propagateAttributes, propagatedFromContext, reportError, resolveEnv, setLogLevel, withContext };