@telemetry-dev/otel 0.1.1 → 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";
 
@@ -27,7 +27,7 @@ interface BatchOptions {
 }
 declare const DEFAULT_BASE_URL = "https://ingest.telemetry.dev";
 declare const DEFAULT_BATCH: Required<BatchOptions>;
-declare function resolveEnv(): NodeJS.ProcessEnv;
+declare function resolveEnv(): Record<string, string | undefined>;
 //#endregion
 //#region src/context.d.ts
 declare const als: AsyncLocalStorage<Context> | undefined;
@@ -138,6 +138,7 @@ declare function createTelemetrySpanExporter(options?: {
   baseUrl?: string;
   fetch?: typeof fetch;
   onError?: (error: Error) => void;
+  exportTimeoutMillis?: number;
 }): SpanExporter;
 //#endregion
 //#region src/processor.d.ts
@@ -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: 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;
@@ -196,4 +233,4 @@ declare function otlpHeaders(apiKey: string, sdkName?: 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 };