@langfuse/otel 4.0.0-beta.0 → 4.0.0-beta.2

package/dist/index.d.cts

@@ -2,26 +2,140 @@ import { ReadableSpan, SpanExporter, BatchSpanProcessor, Span } from '@opentelem
 import { MediaContentType } from '@langfuse/core';
 export { MediaContentType } from '@langfuse/core';
 
+/**
+ * Function type for masking sensitive data in spans before export.
+ *
+ * @param params - Object containing the data to be masked
+ * @param params.data - The data that should be masked
+ * @returns The masked data (can be of any type)
+ *
+ * @example
+ * ```typescript
+ * const maskFunction: MaskFunction = ({ data }) => {
+ *   if (typeof data === 'string') {
+ *     return data.replace(/password=\w+/g, 'password=***');
+ *   }
+ *   return data;
+ * };
+ * ```
+ *
+ * @public
+ */
 type MaskFunction = (params: {
     data: any;
 }) => any;
+/**
+ * Function type for determining whether a span should be exported to Langfuse.
+ *
+ * @param params - Object containing the span to evaluate
+ * @param params.otelSpan - The OpenTelemetry span to evaluate
+ * @returns `true` if the span should be exported, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const shouldExportSpan: ShouldExportSpan = ({ otelSpan }) => {
+ *   // Only export spans that took longer than 100ms
+ *   return otelSpan.duration[0] * 1000 + otelSpan.duration[1] / 1000000 > 100;
+ * };
+ * ```
+ *
+ * @public
+ */
 type ShouldExportSpan = (params: {
     otelSpan: ReadableSpan;
 }) => boolean;
+/**
+ * Configuration parameters for the LangfuseSpanProcessor.
+ *
+ * @public
+ */
 interface LangfuseSpanProcessorParams {
+    /**
+     * Custom OpenTelemetry span exporter. If not provided, a default OTLP exporter will be used.
+     */
     exporter?: SpanExporter;
+    /**
+     * Langfuse public API key. Can also be set via LANGFUSE_PUBLIC_KEY environment variable.
+     */
     publicKey?: string;
+    /**
+     * Langfuse secret API key. Can also be set via LANGFUSE_SECRET_KEY environment variable.
+     */
     secretKey?: string;
+    /**
+     * Langfuse instance base URL. Can also be set via LANGFUSE_BASE_URL environment variable.
+     * @defaultValue "https://cloud.langfuse.com"
+     */
     baseUrl?: string;
+    /**
+     * Number of spans to batch before flushing. Can also be set via LANGFUSE_FLUSH_AT environment variable.
+     */
     flushAt?: number;
+    /**
+     * Flush interval in seconds. Can also be set via LANGFUSE_FLUSH_INTERVAL environment variable.
+     */
     flushInterval?: number;
+    /**
+     * Function to mask sensitive data in spans before export.
+     */
     mask?: MaskFunction;
+    /**
+     * Function to determine whether a span should be exported to Langfuse.
+     */
     shouldExportSpan?: ShouldExportSpan;
+    /**
+     * Environment identifier for the traces. Can also be set via LANGFUSE_TRACING_ENVIRONMENT environment variable.
+     */
     environment?: string;
+    /**
+     * Release identifier for the traces. Can also be set via LANGFUSE_RELEASE environment variable.
+     */
     release?: string;
+    /**
+     * Request timeout in seconds. Can also be set via LANGFUSE_TIMEOUT environment variable.
+     * @defaultValue 5
+     */
     timeout?: number;
+    /**
+     * Additional HTTP headers to include with requests.
+     */
     additionalHeaders?: Record<string, string>;
 }
+/**
+ * OpenTelemetry span processor for sending spans to Langfuse.
+ *
+ * This processor extends the standard BatchSpanProcessor to provide:
+ * - Automatic batching and flushing of spans to Langfuse
+ * - Media content extraction and upload from base64 data URIs
+ * - Data masking capabilities for sensitive information
+ * - Conditional span export based on custom logic
+ * - Environment and release tagging
+ *
+ * @example
+ * ```typescript
+ * import { NodeSDK } from '@opentelemetry/sdk-node';
+ * import { LangfuseSpanProcessor } from '@langfuse/otel';
+ *
+ * const sdk = new NodeSDK({
+ *   spanProcessors: [
+ *     new LangfuseSpanProcessor({
+ *       publicKey: 'pk_...',
+ *       secretKey: 'sk_...',
+ *       baseUrl: 'https://cloud.langfuse.com',
+ *       environment: 'production',
+ *       mask: ({ data }) => {
+ *         // Mask sensitive data
+ *         return data.replace(/api_key=\w+/g, 'api_key=***');
+ *       }
+ *     })
+ *   ]
+ * });
+ *
+ * sdk.start();
+ * ```
+ *
+ * @public
+ */
 declare class LangfuseSpanProcessor extends BatchSpanProcessor {
     private pendingMediaUploads;
     private publicKey?;
@@ -31,12 +145,74 @@ declare class LangfuseSpanProcessor extends BatchSpanProcessor {
     private mask?;
     private shouldExportSpan?;
     private apiClient;
+    /**
+     * Creates a new LangfuseSpanProcessor instance.
+     *
+     * @param params - Configuration parameters for the processor
+     *
+     * @example
+     * ```typescript
+     * const processor = new LangfuseSpanProcessor({
+     *   publicKey: 'pk_...',
+     *   secretKey: 'sk_...',
+     *   environment: 'staging',
+     *   flushAt: 10,
+     *   flushInterval: 2,
+     *   mask: ({ data }) => {
+     *     // Custom masking logic
+     *     return typeof data === 'string'
+     *       ? data.replace(/secret_\w+/g, 'secret_***')
+     *       : data;
+     *   },
+     *   shouldExportSpan: ({ otelSpan }) => {
+     *     // Only export spans from specific services
+     *     return otelSpan.name.startsWith('my-service');
+     *   }
+     * });
+     * ```
+     */
     constructor(params?: LangfuseSpanProcessorParams);
     private get logger();
+    /**
+     * Called when a span is started. Adds environment and release attributes to the span.
+     *
+     * @param span - The span that was started
+     * @param parentContext - The parent context
+     *
+     * @override
+     */
     onStart(span: Span, parentContext: any): void;
+    /**
+     * Called when a span ends. Processes the span for export to Langfuse.
+     *
+     * This method:
+     * 1. Checks if the span should be exported using the shouldExportSpan function
+     * 2. Applies data masking to sensitive attributes
+     * 3. Handles media content extraction and upload
+     * 4. Logs span details in debug mode
+     * 5. Passes the span to the parent processor for export
+     *
+     * @param span - The span that ended
+     *
+     * @override
+     */
     onEnd(span: ReadableSpan): void;
     private flush;
+    /**
+     * Forces an immediate flush of all pending spans and media uploads.
+     *
+     * @returns Promise that resolves when all pending operations are complete
+     *
+     * @override
+     */
     forceFlush(): Promise<void>;
+    /**
+     * Gracefully shuts down the processor, ensuring all pending operations are completed.
+     *
+     * @returns Promise that resolves when shutdown is complete
+     *
+     * @override
+     */
     shutdown(): Promise<void>;
     private handleMediaInPlace;
     private applyMaskInPlace;
@@ -45,31 +221,151 @@ declare class LangfuseSpanProcessor extends BatchSpanProcessor {
     private uploadMediaWithBackoff;
 }
 
+/**
+ * Parameters for creating a LangfuseMedia instance.
+ *
+ * Supports two input formats:
+ * - Base64 data URI (e.g., "data:image/png;base64,...")
+ * - Raw bytes with explicit content type
+ *
+ * @public
+ */
 type LangfuseMediaParams = {
+    /** Indicates the media is provided as a base64 data URI */
     source: "base64_data_uri";
+    /** The complete base64 data URI string */
     base64DataUri: string;
 } | {
+    /** Indicates the media is provided as raw bytes */
     source: "bytes";
+    /** The raw content bytes */
     contentBytes: Buffer;
+    /** The MIME type of the content */
     contentType: MediaContentType;
 };
 /**
  * A class for wrapping media objects for upload to Langfuse.
  *
  * This class handles the preparation and formatting of media content for Langfuse,
- * supporting both base64 data URIs and raw content bytes.
+ * supporting both base64 data URIs and raw content bytes. It automatically:
+ * - Parses base64 data URIs to extract content type and bytes
+ * - Generates SHA-256 hashes for content integrity
+ * - Creates unique media IDs based on content hash
+ * - Formats media references for embedding in traces
+ *
+ * @example
+ * ```typescript
+ * // From base64 data URI
+ * const media1 = new LangfuseMedia({
+ *   source: "base64_data_uri",
+ *   base64DataUri: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
+ * });
+ *
+ * // From raw bytes
+ * const media2 = new LangfuseMedia({
+ *   source: "bytes",
+ *   contentBytes: Buffer.from("Hello World"),
+ *   contentType: "text/plain"
+ * });
+ *
+ * console.log(media1.id); // Unique media ID
+ * console.log(media1.tag); // Media reference tag
+ * ```
+ *
+ * @public
  */
 declare class LangfuseMedia {
     _contentBytes?: Buffer;
     _contentType?: MediaContentType;
     _source?: string;
+    /**
+     * Creates a new LangfuseMedia instance.
+     *
+     * @param params - Media parameters specifying the source and content
+     *
+     * @example
+     * ```typescript
+     * // Create from base64 data URI
+     * const media = new LangfuseMedia({
+     *   source: "base64_data_uri",
+     *   base64DataUri: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
+     * });
+     * ```
+     */
     constructor(params: LangfuseMediaParams);
+    /**
+     * Parses a base64 data URI to extract content bytes and type.
+     *
+     * @param data - The base64 data URI string
+     * @returns Tuple of [contentBytes, contentType] or [undefined, undefined] on error
+     * @private
+     */
     private parseBase64DataUri;
+    /**
+     * Gets a unique identifier for this media based on its content hash.
+     *
+     * The ID is derived from the first 22 characters of the URL-safe base64-encoded
+     * SHA-256 hash of the content.
+     *
+     * @returns The unique media ID, or null if hash generation failed
+     *
+     * @example
+     * ```typescript
+     * const media = new LangfuseMedia({...});
+     * console.log(media.id); // "A1B2C3D4E5F6G7H8I9J0K1"
+     * ```
+     */
     get id(): string | null;
+    /**
+     * Gets the length of the media content in bytes.
+     *
+     * @returns The content length in bytes, or undefined if no content is available
+     */
     get contentLength(): number | undefined;
+    /**
+     * Gets the SHA-256 hash of the media content.
+     *
+     * The hash is used for content integrity verification and generating unique media IDs.
+     * Returns undefined if crypto is not available or hash generation fails.
+     *
+     * @returns The base64-encoded SHA-256 hash, or undefined if unavailable
+     */
     get contentSha256Hash(): string | undefined;
+    /**
+     * Gets the media reference tag for embedding in trace data.
+     *
+     * The tag format is: `@@@langfuseMedia:type=<contentType>|id=<mediaId>|source=<source>@@@`
+     * This tag can be embedded in trace attributes and will be replaced with actual
+     * media content when the trace is viewed in Langfuse.
+     *
+     * @returns The media reference tag, or null if required data is missing
+     *
+     * @example
+     * ```typescript
+     * const media = new LangfuseMedia({...});
+     * console.log(media.tag);
+     * // "@@@langfuseMedia:type=image/png|id=A1B2C3D4E5F6G7H8I9J0K1|source=base64_data_uri@@@"
+     * ```
+     */
     get tag(): string | null;
+    /**
+     * Gets the media content as a base64 data URI.
+     *
+     * @returns The complete data URI string, or null if no content is available
+     *
+     * @example
+     * ```typescript
+     * const media = new LangfuseMedia({...});
+     * console.log(media.base64DataUri);
+     * // "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB..."
+     * ```
+     */
     get base64DataUri(): string | null;
+    /**
+     * Serializes the media to JSON (returns the base64 data URI).
+     *
+     * @returns The base64 data URI, or null if no content is available
+     */
     toJSON(): string | null;
 }