@telemetry-dev/otel 0.1.0 → 0.1.2

package/README.md

@@ -80,8 +80,44 @@ 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`.
+The exporter accepts `apiKey`, `baseUrl`, `fetch`, `onError`, and `exportTimeoutMillis`. The timeout caps each export request and defaults to 30,000 ms. The API key and base URL use the same environment variable fallbacks 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`.
+
+`TelemetrySpanProcessor` on your provider adds `gen_ai.conversation.id`, but it cannot change trace IDs. Use `withSessionParent(context.active(), sessionId, apiKey)` for each root span. A nonempty API key and session ID put each session root in the same trace. A deterministic session parent (`SHA-256(apiKey ‖ 0x00 ‖ sessionId)`) is the parent, but the SDK does not send it. If one value is empty, the function keeps the input context.
+
+**Install `sessionSampler(yourSampler)` on the provider before you use `withSessionParent` or `sessionRootTracerProvider`.** The OTel API does not expose a provider's sampler. A context helper alone cannot keep the root policy. Pass the existing programmatic sampler to the wrapper. Without an argument, `sessionSampler()` reads `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`. It does not inspect an existing provider.
+
+The wrapper uses the original parent context and the deterministic session trace ID for the sampling decision. Real active and explicit parents keep their sampling decisions. The framework-root wrapper reparents recognized turns inside workflow spans, but keeps the workflow parent's sampling policy and trace state. Context values and baggage stay intact.
+
+`sessionSpanContext` only calculates IDs. Its flags are not a sampling decision. Do not use it directly as a parent.
+
+```ts
+import { context } from "@opentelemetry/api";
+import {
+  BasicTracerProvider,
+  ParentBasedSampler,
+  TraceIdRatioBasedSampler,
+} from "@opentelemetry/sdk-trace-base";
+import { sessionSampler, TelemetrySpanProcessor, withSessionParent } from "@telemetry-dev/otel";
+
+const sampler = new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(0.1) });
+const provider = new BasicTracerProvider({
+  sampler: sessionSampler(sampler),
+  spanProcessors: [new TelemetrySpanProcessor()],
+});
+const span = provider
+  .getTracer("my-app")
+  .startSpan(
+    "turn",
+    {},
+    withSessionParent(context.active(), sessionId, process.env.TELEMETRY_DEV_API_KEY),
+  );
+span.end();
+```
+
+The environment modes are `always_on`, `always_off`, `traceidratio`, `parentbased_always_on` (default), `parentbased_always_off`, and `parentbased_traceidratio`.
+Ratio modes accept a finite argument in `[0, 1]`. Missing, invalid, or out-of-range arguments use `1` and cause an OTel diagnostic. Unknown modes use `parentbased_always_on`.
+The TypeScript and Python SDKs share deterministic session IDs. Their built-in ratio samplers can select different sessions because the OTel algorithms differ.

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { Attributes, Context, ContextManager } from "@opentelemetry/api";
+import { Attributes, Context, ContextManager, SpanContext, TracerProvider } 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 { ReadableSpan, Sampler, Span, SpanExporter, SpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { LogRecordExporter } from "@opentelemetry/sdk-logs";
 
@@ -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";
@@ -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,8 @@ declare function createTelemetrySpanExporter(options?: {
   apiKey?: string;
   baseUrl?: string;
   fetch?: typeof fetch;
-  onError?: (error: unknown) => void;
+  onError?: (error: Error) => void;
+  exportTimeoutMillis?: number;
 }): SpanExporter;
 //#endregion
 //#region src/processor.d.ts
@@ -147,7 +148,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,
@@ -163,10 +164,44 @@ declare class StampingSpanProcessor implements SpanProcessor {
   shutdown(): Promise<void>;
 }
 //#endregion
+//#region src/session.d.ts
+/**
+ * Install on the provider used with withSessionParent or sessionRootTracerProvider.
+ * Pass the provider's configured sampler explicitly; OTel cannot read it back from a provider.
+ * Without an argument, uses OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG defaults.
+ */
+declare function sessionSampler(inner?: Sampler): Sampler;
+/**
+ * Deterministic remote parent for a session: every root span of the session joins one trace
+ * (`traceId = SHA-256(apiKey ‖ 0x00 ‖ sessionId)[0:16]`, parent `spanId = digest[16:24]`).
+ * The API key is part of the input so two projects with the same session id never share a trace
+ * id. No span is ever emitted for the parent. Its flags are not a sampling decision:
+ * use withSessionParent and install sessionSampler on the provider. Python mirrors these IDs.
+ */
+declare function sessionSpanContext(apiKey: string | undefined, sessionId: string): SpanContext;
+/** Returns the session id when a span must start a new turn in the session trace. */
+type SessionRootOf = (name: string, attributes: Attributes) => string | undefined;
+/**
+ * Wraps a provider so that spans `sessionRootOf` recognizes are parented under the session
+ * parent even when a parent is active. Frameworks that run each turn inside their own
+ * engine span (eve's "workflow" scope) otherwise give every turn its own trace.
+ * The inner provider MUST use sessionSampler(configuredSampler) to retain sampling policy.
+ */
+declare function sessionRootTracerProvider(inner: TracerProvider, apiKey: string | undefined, sessionRootOf: SessionRootOf, onError?: (error: Error) => void): TracerProvider;
+/**
+ * Parent a would-be root under the session; nested spans keep their real parent.
+ * Requires sessionSampler(configuredSampler) on the provider that starts the span.
+ */
+declare function withSessionParent(ctx: Context, sessionId: string | undefined, apiKey: string | undefined): Context;
+declare function sessionIdOf(ctx: Context, attributes?: Attributes): string | undefined;
+/** FIPS 180-4 SHA-256 in plain JS: the package must stay synchronous and runtime-neutral. */
+declare function sha256(bytes: Uint8Array): Uint8Array;
+//#endregion
 //#region src/transport.d.ts
 interface Transport {
   fetchImpl: typeof fetch;
-  onError?: (error: unknown) => void;
+  onError?: (error: Error) => void;
+  exportTimeoutMillis?: number;
 }
 interface OtlpTarget {
   url: string;
@@ -176,12 +211,14 @@ declare const postOtlp: ({
   fetchImpl,
   url,
   headers,
-  body
+  body,
+  signal
 }: {
   fetchImpl: typeof fetch;
   url: string;
   headers: Record<string, string>;
   body: Uint8Array;
+  signal?: AbortSignal;
 }) => Promise<Response>;
 declare function maybeGzip(body: Uint8Array): Promise<{
   body: Uint8Array;
@@ -190,6 +227,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 };
+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 SessionRootOf, 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, sessionIdOf, sessionRootTracerProvider, sessionSampler, sessionSpanContext, setLogLevel, sha256, withContext, withSessionParent };