@latitude-data/telemetry 3.0.0-alpha.0 → 3.0.0-alpha.1

package/dist/index.d.ts

@@ -1,33 +1,56 @@
+import { SpanProcessor, Span, ReadableSpan, SpanExporter, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
 import * as otel from '@opentelemetry/api';
-import { TextMapPropagator } from '@opentelemetry/api';
-import { SpanProcessor, Span, ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-node';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { TracerProvider, Context } from '@opentelemetry/api';
 
-interface BaseInstrumentation {
-    isEnabled(): boolean;
-    enable(): void;
-    disable(): void;
-}
-
-type CaptureOptions = {
-    tags?: string[];
-    metadata?: Record<string, unknown>;
-    sessionId?: string;
-    userId?: string;
-};
-declare class ManualInstrumentation implements BaseInstrumentation {
-    private enabled;
-    private readonly _tracer;
-    constructor(tracer: otel.Tracer);
-    get tracer(): otel.Tracer;
-    isEnabled(): boolean;
-    enable(): void;
-    disable(): void;
-    resume(ctx: {
-        traceparent: string;
-        baggage?: string;
-    }): otel.Context;
+/**
+ * Supported LLM instrumentation types.
+ * Use these string identifiers to enable auto-instrumentation.
+ */
+type InstrumentationType = "openai" | "anthropic" | "bedrock" | "cohere" | "langchain" | "llamaindex" | "togetherai" | "vertexai" | "aiplatform";
+/**
+ * Options for creating LLM instrumentations.
+ */
+interface CreateInstrumentationsOptions {
+    /** List of instrumentation types to enable. */
+    instrumentations: InstrumentationType[];
+    /**
+     * Optional module references for auto-instrumentation.
+     * If not provided, the instrumentation will attempt to require the module.
+     * Used for Traceloop-based instrumentations.
+     */
+    modules?: Partial<Record<InstrumentationType, unknown>>;
+    /**
+     * Per-instrumentation token enrichment settings.
+     * @default { openai: true }
+     */
+    enrichTokens?: Partial<Record<InstrumentationType, boolean>>;
 }
+/**
+ * Registers LLM instrumentations with the global OpenTelemetry instrumentation registry.
+ *
+ * This is a convenience wrapper around `createLatitudeInstrumentations` and
+ * `@opentelemetry/instrumentation`'s `registerInstrumentations`.
+ *
+ * @example
+ * ```typescript
+ * import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"
+ * import { registerLatitudeInstrumentations, LatitudeSpanProcessor } from "@latitude-data/telemetry"
+ *
+ * const provider = new NodeTracerProvider({
+ *   spanProcessors: [new LatitudeSpanProcessor(apiKey, projectSlug)],
+ * })
+ *
+ * await registerLatitudeInstrumentations({
+ *   instrumentations: ["openai", "anthropic"],
+ *   tracerProvider: provider,
+ * })
+ *
+ * provider.register()
+ * ```
+ */
+declare function registerLatitudeInstrumentations(options: CreateInstrumentationsOptions & {
+    tracerProvider: TracerProvider;
+}): Promise<void>;
 
 interface RedactSpanProcessorOptions {
     attributes: (string | RegExp)[];
@@ -43,81 +66,104 @@ declare class RedactSpanProcessor implements SpanProcessor {
     private shouldRedact;
     private redactAttributes;
 }
-declare const DEFAULT_REDACT_SPAN_PROCESSOR: () => RedactSpanProcessor;
 
-type TelemetryContext = otel.Context;
-declare class ContextManager {
-    private readonly telemetry;
-    constructor(telemetry: ManualInstrumentation);
-    resume(ctx: {
-        traceparent: string;
-        baggage?: string;
-    }): otel.Context;
-    active(): otel.Context;
-    with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(ctx: TelemetryContext, fn: F, thisArg?: ThisParameterType<F>, ...args: A): ReturnType<F>;
-}
-declare class InstrumentationManager {
-    private readonly instrumentations;
-    constructor(instrumentations: BaseInstrumentation[]);
-    enable(): void;
-    disable(): void;
+type SmartFilterOptions = {
+    /**
+     * When true, all spans are exported (legacy behavior).
+     * Default false — only LLM-relevant spans are exported.
+     */
+    disableSmartFilter?: boolean;
+    /**
+     * When smart filter is on, also export spans for which this returns true
+     * (in addition to {@link isDefaultExportSpan}).
+     */
+    shouldExportSpan?: (span: ReadableSpan) => boolean;
+    /** Instrumentation scope names to drop (exact match) even if they pass the default predicate. */
+    blockedInstrumentationScopes?: string[];
+};
+/** Input for {@link buildShouldExportSpanFromFields}; allows `undefined` field values for ergonomics. */
+type SmartFilterFieldsInput = {
+    disableSmartFilter?: boolean | undefined;
+    shouldExportSpan?: ((span: ReadableSpan) => boolean) | undefined;
+    blockedInstrumentationScopes?: string[] | undefined;
+};
+/**
+ * Builds the export predicate from loose option fields (`exactOptionalPropertyTypes`-safe call sites).
+ */
+declare function buildShouldExportSpanFromFields(fields: SmartFilterFieldsInput): (span: ReadableSpan) => boolean;
+/** True if the span uses OpenTelemetry GenAI semantic conventions or common LLM attribute namespaces. */
+declare function isGenAiOrLlmAttributeSpan(span: ReadableSpan): boolean;
+/** True if the span was created with Latitude's tracer scopes. */
+declare function isLatitudeInstrumentationSpan(span: ReadableSpan): boolean;
+/**
+ * Default export predicate (smart filter): Latitude scopes, GenAI / LLM attributes,
+ * or known LLM instrumentation scopes.
+ */
+declare function isDefaultExportSpan(span: ReadableSpan): boolean;
+declare function buildShouldExportSpan(options: SmartFilterOptions): (span: ReadableSpan) => boolean;
+/**
+ * Drops spans that fail the export predicate before passing them to the inner processor.
+ * Inner processor should perform redaction and export.
+ */
+declare class ExportFilterSpanProcessor implements SpanProcessor {
+    private readonly shouldExport;
+    private readonly inner;
+    constructor(shouldExport: (span: ReadableSpan) => boolean, inner: SpanProcessor);
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
 }
-declare const DEFAULT_SPAN_EXPORTER: (apiKey: string, projectSlug: string) => OTLPTraceExporter;
-declare enum Instrumentation {
-    Anthropic = "anthropic",
-    AIPlatform = "aiplatform",
-    Bedrock = "bedrock",
-    Cohere = "cohere",
-    Langchain = "langchain",
-    LlamaIndex = "llamaindex",
-    Manual = "manual",
-    OpenAI = "openai",
-    TogetherAI = "togetherai",
-    VertexAI = "vertexai"
+/** Runs optional redaction then the export processor (batch/simple). */
+declare class RedactThenExportSpanProcessor implements SpanProcessor {
+    private readonly redact;
+    private readonly exportProcessor;
+    constructor(redact: SpanProcessor | null, exportProcessor: SpanProcessor);
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
 }
-type TelemetryOptions = {
-    serviceName?: string;
+
+type ContextOptions = {
+    name?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    sessionId?: string;
+    userId?: string;
+};
+type InitLatitudeOptions = SmartFilterOptions & {
+    apiKey: string;
+    projectSlug: string;
+    instrumentations?: InstrumentationType[];
+    disableRedact?: boolean;
+    redact?: RedactSpanProcessorOptions;
     disableBatch?: boolean;
     exporter?: SpanExporter;
-    processors?: SpanProcessor[];
-    propagators?: TextMapPropagator[];
-    instrumentations?: {
-        [Instrumentation.AIPlatform]?: unknown;
-        [Instrumentation.Anthropic]?: unknown;
-        [Instrumentation.Bedrock]?: unknown;
-        [Instrumentation.Cohere]?: unknown;
-        [Instrumentation.OpenAI]?: unknown;
-        [Instrumentation.LlamaIndex]?: unknown;
-        [Instrumentation.TogetherAI]?: unknown;
-        [Instrumentation.VertexAI]?: unknown;
-        [Instrumentation.Langchain]?: {
-            callbackManagerModule?: unknown;
-        };
-    };
 };
-declare class LatitudeTelemetry {
-    private options;
-    private nodeProvider;
-    private instrumentationsList;
-    /** OpenTelemetry tracer for creating custom spans. */
-    readonly tracer: otel.Tracer;
-    readonly context: ContextManager;
-    readonly instrumentation: InstrumentationManager;
-    private readonly lifecycle;
-    constructor(apiKey: string, projectSlug: string, options?: TelemetryOptions);
-    flush(): Promise<void>;
+type LatitudeSpanProcessorOptions = SmartFilterOptions & {
+    disableRedact?: boolean;
+    redact?: RedactSpanProcessorOptions;
+    disableBatch?: boolean;
+    exporter?: SpanExporter;
+};
+
+declare function capture<T>(name: string, fn: () => T | Promise<T>, options?: ContextOptions): T | Promise<T>;
+
+declare function initLatitude(options: InitLatitudeOptions): {
+    provider: NodeTracerProvider;
+    flush: () => Promise<void>;
+    shutdown: () => Promise<void>;
+    ready: Promise<void>;
+};
+
+declare class LatitudeSpanProcessor implements SpanProcessor {
+    private readonly tail;
+    constructor(apiKey: string, projectSlug: string, options?: LatitudeSpanProcessorOptions);
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    forceFlush(): Promise<void>;
     shutdown(): Promise<void>;
-    private initProviderInstrumentations;
-    /**
-     * Wrap a block of code with trace-wide context attributes.
-     * Baggage entries (tags, metadata, sessionId, userId) are propagated
-     * to all spans created within the callback via BaggageSpanProcessor.
-     *
-     * If there is no active span, a root span is created so all child spans
-     * are grouped under a single trace. If a span is already active, only
-     * baggage is set without creating an extra wrapper span.
-     */
-    capture<T>(options: CaptureOptions, fn: (ctx: TelemetryContext) => T | Promise<T>): Promise<T>;
 }
 
-export { type CaptureOptions, DEFAULT_REDACT_SPAN_PROCESSOR, DEFAULT_SPAN_EXPORTER, Instrumentation, LatitudeTelemetry, RedactSpanProcessor, type RedactSpanProcessorOptions, type TelemetryContext, type TelemetryOptions };
+export { type ContextOptions, ExportFilterSpanProcessor, type InitLatitudeOptions, type InstrumentationType, LatitudeSpanProcessor, type LatitudeSpanProcessorOptions, RedactSpanProcessor, type RedactSpanProcessorOptions, RedactThenExportSpanProcessor, type SmartFilterFieldsInput, type SmartFilterOptions, buildShouldExportSpan, buildShouldExportSpanFromFields, capture, initLatitude, isDefaultExportSpan, isGenAiOrLlmAttributeSpan, isLatitudeInstrumentationSpan, registerLatitudeInstrumentations };