@telemetry-dev/otel 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -9,7 +9,7 @@ import { LogRecordExporter } from "@opentelemetry/sdk-logs";
 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;
+declare function jsonAttr<T>(value: T): string | undefined;
 //#endregion
 //#region src/config.d.ts
 type LogLevel = "debug" | "info" | "warn" | "error";
@@ -27,7 +27,7 @@ interface BatchOptions {
 }
 declare const DEFAULT_BASE_URL = "https://ingest.telemetry.dev";
 declare const DEFAULT_BATCH: Required<BatchOptions>;
-declare function resolveEnv(): Record<string, string | undefined>;
+declare function resolveEnv(): NodeJS.ProcessEnv;
 //#endregion
 //#region src/context.d.ts
 declare const als: AsyncLocalStorage<Context> | undefined;
@@ -39,13 +39,13 @@ 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 {
+interface PropagatedAttributes<MetadataValue = unknown> {
   /** 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>;
+  metadata?: Record<string, MetadataValue>;
 }
 declare function buildPropagatedAttributes(attrs: PropagatedAttributes): Attributes;
 declare function propagatedFromContext(ctx: Context): Attributes | undefined;
@@ -74,7 +74,7 @@ declare const diag: {
   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;
+declare function reportError(onError: ((error: Error) => void) | undefined, cause: unknown): void;
 //#endregion
 //#region src/metrics.d.ts
 declare const DURATION_BUCKETS: number[];
@@ -114,7 +114,7 @@ interface TelemetrySpanProcessorOptions {
   /** deployment.environment.name on the metrics resource. Falls back to `TELEMETRY_DEV_ENVIRONMENT`. */
   environment?: string;
   fetch?: typeof fetch;
-  onError?: (error: unknown) => void;
+  onError?: (error: Error) => void;
   /** Advanced/test seam: replaces the OTLP fetch exporter. */
   spanExporter?: SpanExporter;
 }
@@ -137,7 +137,7 @@ declare function createTelemetrySpanExporter(options?: {
   apiKey?: string;
   baseUrl?: string;
   fetch?: typeof fetch;
-  onError?: (error: unknown) => void;
+  onError?: (error: Error) => void;
 }): SpanExporter;
 //#endregion
 //#region src/processor.d.ts
@@ -147,7 +147,7 @@ interface StampingProcessorOptions {
   batch: Required<BatchOptions>;
   spanFilter?: (span: ReadableSpan) => boolean;
   recordMetrics?: (span: ReadableSpan) => void;
-  onError?: (error: unknown) => void;
+  onError?: (error: Error) => void;
 }
 /**
  * The vendor span processor: stamps propagated correlation attributes onto every span at start,
@@ -166,7 +166,7 @@ declare class StampingSpanProcessor implements SpanProcessor {
 //#region src/transport.d.ts
 interface Transport {
   fetchImpl: typeof fetch;
-  onError?: (error: unknown) => void;
+  onError?: (error: Error) => void;
 }
 interface OtlpTarget {
   url: string;
@@ -190,6 +190,10 @@ declare function maybeGzip(body: Uint8Array): Promise<{
 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>;
+declare function otlpHeaders(apiKey: string, sdkName?: string): {
+  "content-type": string;
+  authorization: string;
+  "x-telemetry-dev-sdk": 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 };

package/dist/index.mjs

@@ -34,7 +34,7 @@ const DEFAULT_BATCH = {
 	exportTimeoutMillis: 3e4
 };
 function resolveEnv() {
-	if (typeof process !== "undefined" && process.env) return process.env;
+	if (globalThis.process !== void 0 && process.env) return process.env;
 	return {};
 }
 //#endregion
@@ -61,11 +61,11 @@ const diag = {
 	error: (...args) => emit("error", args)
 };
 /** Fail-open guard: SDK internals report through onError + diagnostics, never into user code. */
-function reportError(onError, error) {
+function reportError(onError, cause) {
 	try {
-		onError?.(error);
+		onError?.(cause instanceof Error ? cause : new Error(String(cause)));
 	} catch {}
-	diag.error(error);
+	diag.error(cause);
 }
 //#endregion
 //#region src/context.ts
@@ -204,7 +204,7 @@ const TOKEN_OPERATIONS = new Set([
 const DORMANT_INTERVAL_MS = 2 ** 31 - 1;
 const BATCHED_METRIC_INTERVAL_MS = 6e4;
 function stringAttr(value) {
-	return typeof value === "string" ? value : void 0;
+	return value?.constructor === String ? `${value}` : void 0;
 }
 function createMetricsPipeline({ resource, exporter, exportIntervalMillis }) {
 	const reader = new PeriodicExportingMetricReader({
@@ -226,7 +226,7 @@ function createMetricsPipeline({ resource, exporter, exportIntervalMillis }) {
 	});
 	const record = (span) => {
 		const operation = span.attributes["gen_ai.operation.name"];
-		if (typeof operation !== "string" || !DURATION_OPERATIONS.has(operation)) return;
+		if (operation?.constructor !== String || !DURATION_OPERATIONS.has(`${operation}`)) return;
 		const attrs = omitUndefined({
 			"gen_ai.operation.name": operation,
 			"gen_ai.provider.name": stringAttr(span.attributes["gen_ai.provider.name"]),
@@ -241,12 +241,12 @@ function createMetricsPipeline({ resource, exporter, exportIntervalMillis }) {
 		} : attrs);
 		if (!TOKEN_OPERATIONS.has(operation)) return;
 		const inputTokens = span.attributes["gen_ai.usage.input_tokens"];
-		if (typeof inputTokens === "number") tokenHistogram.record(inputTokens, {
+		if (inputTokens?.constructor === Number) tokenHistogram.record(inputTokens, {
 			...attrs,
 			"gen_ai.token.type": "input"
 		});
 		const outputTokens = span.attributes["gen_ai.usage.output_tokens"];
-		if (typeof outputTokens === "number") tokenHistogram.record(outputTokens, {
+		if (outputTokens?.constructor === Number) tokenHistogram.record(outputTokens, {
 			...attrs,
 			"gen_ai.token.type": "output"
 		});
@@ -335,7 +335,7 @@ const postOtlp = async ({ fetchImpl, url, headers, body }) => {
 };
 const GZIP_THRESHOLD_BYTES = 1024;
 async function maybeGzip(body) {
-	if (body.byteLength <= GZIP_THRESHOLD_BYTES || typeof CompressionStream === "undefined") return { body };
+	if (body.byteLength <= GZIP_THRESHOLD_BYTES || globalThis.CompressionStream === void 0) return { body };
 	try {
 		const stream = new Blob([body]).stream().pipeThrough(new CompressionStream("gzip"));
 		return {
@@ -455,10 +455,11 @@ function createMetricExporter(target, transport) {
 		shutdown: () => Promise.resolve()
 	};
 }
-function otlpHeaders(apiKey) {
+function otlpHeaders(apiKey, sdkName = "@telemetry-dev/otel") {
 	return {
 		"content-type": "application/x-protobuf",
-		authorization: `Bearer ${apiKey}`
+		authorization: `Bearer ${apiKey}`,
+		"x-telemetry-dev-sdk": sdkName
 	};
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-dev/otel",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Bring-your-own OpenTelemetry base layer for telemetry.dev: span processor and OTLP/protobuf trace exporter.",
   "keywords": [
     "genai",

package/src/attrs.ts

@@ -19,7 +19,15 @@ export function omitUndefined(attributes: Attributes): Attributes {
 
 // Stringify structured content (messages / tool args) for the gen_ai.* string attributes the
 // ingest parses back into JSON. Returns undefined so omitUndefined drops absent content.
-export function jsonAttr(value: unknown): string | undefined {
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export function jsonAttr<T>(value: T): string | undefined {
   if (value === undefined) return undefined;
   if (typeof value === "string") return value;
   try {

package/src/config.ts

@@ -22,8 +22,7 @@ export const DEFAULT_BATCH: Required<BatchOptions> = {
   exportTimeoutMillis: 30000,
 };
 
-export function resolveEnv(): Record<string, string | undefined> {
-  if (typeof process !== "undefined" && process.env) return process.env;
-  const emptyEnv: Record<string, string | undefined> = {};
-  return emptyEnv;
+export function resolveEnv() {
+  if (globalThis.process !== undefined && process.env) return process.env;
+  return {};
 }

package/src/context.ts

@@ -53,13 +53,13 @@ export function withContext<T>(ctx: Context, fn: () => T): T {
 
 export const PROPAGATED_KEY = createContextKey("telemetry.dev propagated attributes");
 
-export interface PropagatedAttributes {
+export interface PropagatedAttributes<MetadataValue = unknown> {
   /** 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>;
+  metadata?: Record<string, MetadataValue>;
 }
 
 const RESERVED_METADATA_KEYS = new Set(["userId", "sessionId", "user_id", "session_id"]);

package/src/debug.ts

@@ -1,6 +1,9 @@
 import type { LogLevel, SdkLogLevel } from "./config.ts";
 
-const ORDER: Record<SdkLogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
+const ORDER = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 } satisfies Record<
+  SdkLogLevel,
+  number
+>;
 
 let currentLevel: SdkLogLevel = "warn";
 
@@ -22,11 +25,11 @@ export const diag = {
 };
 
 /** Fail-open guard: SDK internals report through onError + diagnostics, never into user code. */
-export function reportError(onError: ((error: unknown) => void) | undefined, error: unknown): void {
+export function reportError(onError: ((error: Error) => void) | undefined, cause: unknown): void {
   try {
-    onError?.(error);
+    onError?.(cause instanceof Error ? cause : new Error(String(cause)));
   } catch {
     // onError itself must never propagate
   }
-  diag.error(error);
+  diag.error(cause);
 }

package/src/metrics.ts

@@ -31,8 +31,8 @@ export interface MetricsPipeline {
   shutdown(): Promise<void>;
 }
 
-function stringAttr(value: unknown): string | undefined {
-  return typeof value === "string" ? value : undefined;
+function stringAttr(value: Attributes[string]): string | undefined {
+  return value?.constructor === String ? `${value}` : undefined;
 }
 
 export function createMetricsPipeline({
@@ -59,7 +59,7 @@ export function createMetricsPipeline({
 
   const record = (span: ReadableSpan): void => {
     const operation = span.attributes["gen_ai.operation.name"];
-    if (typeof operation !== "string" || !DURATION_OPERATIONS.has(operation)) return;
+    if (operation?.constructor !== String || !DURATION_OPERATIONS.has(`${operation}`)) return;
     const attrs: Attributes = omitUndefined({
       "gen_ai.operation.name": operation,
       "gen_ai.provider.name": stringAttr(span.attributes["gen_ai.provider.name"]),
@@ -74,11 +74,11 @@ export function createMetricsPipeline({
     );
     if (!TOKEN_OPERATIONS.has(operation)) return;
     const inputTokens = span.attributes["gen_ai.usage.input_tokens"];
-    if (typeof inputTokens === "number") {
+    if (inputTokens?.constructor === Number) {
       tokenHistogram.record(inputTokens, { ...attrs, "gen_ai.token.type": "input" });
     }
     const outputTokens = span.attributes["gen_ai.usage.output_tokens"];
-    if (typeof outputTokens === "number") {
+    if (outputTokens?.constructor === Number) {
       tokenHistogram.record(outputTokens, { ...attrs, "gen_ai.token.type": "output" });
     }
   };

package/src/otel.ts

@@ -47,7 +47,7 @@ export interface TelemetrySpanProcessorOptions {
   /** deployment.environment.name on the metrics resource. Falls back to `TELEMETRY_DEV_ENVIRONMENT`. */
   environment?: string;
   fetch?: typeof fetch;
-  onError?: (error: unknown) => void;
+  onError?: (error: Error) => void;
   /** Advanced/test seam: replaces the OTLP fetch exporter. */
   spanExporter?: SpanExporter;
 }
@@ -142,7 +142,7 @@ export function createTelemetrySpanExporter(
     apiKey?: string;
     baseUrl?: string;
     fetch?: typeof fetch;
-    onError?: (error: unknown) => void;
+    onError?: (error: Error) => void;
   } = {},
 ): SpanExporter {
   const env = resolveEnv();

package/src/processor.ts

@@ -18,7 +18,7 @@ export interface StampingProcessorOptions {
   batch: Required<BatchOptions>;
   spanFilter?: (span: ReadableSpan) => boolean;
   recordMetrics?: (span: ReadableSpan) => void;
-  onError?: (error: unknown) => void;
+  onError?: (error: Error) => void;
 }
 
 /**

package/src/transport.ts

@@ -16,7 +16,7 @@ import { reportError } from "./debug.ts";
 
 export interface Transport {
   fetchImpl: typeof fetch;
-  onError?: (error: unknown) => void;
+  onError?: (error: Error) => void;
 }
 
 export interface OtlpTarget {
@@ -74,7 +74,7 @@ const GZIP_THRESHOLD_BYTES = 1024;
 export async function maybeGzip(
   body: Uint8Array,
 ): Promise<{ body: Uint8Array; contentEncoding?: "gzip" }> {
-  if (body.byteLength <= GZIP_THRESHOLD_BYTES || typeof CompressionStream === "undefined") {
+  if (body.byteLength <= GZIP_THRESHOLD_BYTES || globalThis.CompressionStream === undefined) {
     return { body };
   }
   try {
@@ -147,7 +147,7 @@ export function createTraceExporter(target: OtlpTarget, transport: Transport): S
     export(spans, resultCallback) {
       send(spans).then(
         () => resultCallback({ code: ExportResultCode.SUCCESS }),
-        (error: unknown) => {
+        (error: Error) => {
           reportError(transport.onError, error);
           resultCallback({
             code: ExportResultCode.FAILED,
@@ -172,7 +172,7 @@ export function createLogExporter(target: OtlpTarget, transport: Transport): Log
     export(logs, resultCallback) {
       send(logs).then(
         () => resultCallback({ code: ExportResultCode.SUCCESS }),
-        (error: unknown) => {
+        (error: Error) => {
           reportError(transport.onError, error);
           resultCallback({
             code: ExportResultCode.FAILED,
@@ -225,7 +225,7 @@ export function createMetricExporter(target: OtlpTarget, transport: Transport):
           }
           resultCallback({ code: 0 });
         })
-        .catch((error: unknown) => {
+        .catch((error: Error) => {
           reportError(onError, error);
           resultCallback({ code: 1, error: error instanceof Error ? error : undefined });
         });
@@ -236,9 +236,10 @@ export function createMetricExporter(target: OtlpTarget, transport: Transport):
   };
 }
 
-export function otlpHeaders(apiKey: string): Record<string, string> {
+export function otlpHeaders(apiKey: string, sdkName = "@telemetry-dev/otel") {
   return {
     "content-type": "application/x-protobuf",
     authorization: `Bearer ${apiKey}`,
+    "x-telemetry-dev-sdk": sdkName,
   };
 }