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

package/dist/index.d.ts

@@ -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;
 }
 

package/dist/index.mjs

@@ -12,7 +12,8 @@ import {
   LangfuseAPIClient,
   LANGFUSE_SDK_VERSION,
   LangfuseOtelSpanAttributes,
-  getEnv
+  getEnv,
+  uint8ArrayToBase64 as uint8ArrayToBase642
 } from "@langfuse/core";
 import { hrTimeToMilliseconds } from "@opentelemetry/core";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
@@ -60,6 +61,20 @@ function getSha256HashFromBytes(data) {
 // src/media.ts
 import { getGlobalLogger as getGlobalLogger2 } from "@langfuse/core";
 var LangfuseMedia = class {
+  /**
+   * 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) {
     const { source } = params;
     this._source = source;
@@ -74,6 +89,13 @@ var LangfuseMedia = class {
       this._contentType = params.contentType;
     }
   }
+  /**
+   * 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
+   */
   parseBase64DataUri(data) {
     try {
       if (!data || typeof data !== "string") {
@@ -103,15 +125,42 @@ var LangfuseMedia = class {
       return [void 0, void 0];
     }
   }
+  /**
+   * 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() {
     if (!this.contentSha256Hash) return null;
     const urlSafeContentHash = this.contentSha256Hash.replaceAll("+", "-").replaceAll("/", "_");
     return urlSafeContentHash.slice(0, 22);
   }
+  /**
+   * Gets the length of the media content in bytes.
+   *
+   * @returns The content length in bytes, or undefined if no content is available
+   */
   get contentLength() {
     var _a2;
     return (_a2 = this._contentBytes) == null ? void 0 : _a2.length;
   }
+  /**
+   * 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() {
     if (!this._contentBytes || !isCryptoAvailable) {
       return void 0;
@@ -126,14 +175,47 @@ var LangfuseMedia = class {
       return void 0;
     }
   }
+  /**
+   * 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() {
     if (!this._contentType || !this._source || !this.id) return null;
     return `@@@langfuseMedia:type=${this._contentType}|id=${this.id}|source=${this._source}@@@`;
   }
+  /**
+   * 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() {
     if (!this._contentBytes) return null;
     return `data:${this._contentType};base64,${Buffer.from(this._contentBytes).toString("base64")}`;
   }
+  /**
+   * Serializes the media to JSON (returns the base64 data URI).
+   *
+   * @returns The base64 data URI, or null if no content is available
+   */
   toJSON() {
     return this.base64DataUri;
   }
@@ -141,6 +223,32 @@ var LangfuseMedia = class {
 
 // src/span-processor.ts
 var LangfuseSpanProcessor = class extends BatchSpanProcessor {
+  /**
+   * 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) {
     var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
     const logger = getGlobalLogger3();
@@ -162,8 +270,8 @@ var LangfuseSpanProcessor = class extends BatchSpanProcessor {
     }
     const flushAt = (_f = params == null ? void 0 : params.flushAt) != null ? _f : getEnv("LANGFUSE_FLUSH_AT");
     const flushIntervalSeconds = (_g = params == null ? void 0 : params.flushInterval) != null ? _g : getEnv("LANGFUSE_FLUSH_INTERVAL");
-    const authHeaderValue = Buffer.from(`${publicKey}:${secretKey}`).toString(
-      "base64"
+    const authHeaderValue = uint8ArrayToBase642(
+      new TextEncoder().encode(`${publicKey}:${secretKey}`)
     );
     const timeoutSeconds = (_i = params == null ? void 0 : params.timeout) != null ? _i : Number((_h = getEnv("LANGFUSE_TIMEOUT")) != null ? _h : 5);
     const exporter = (_j = params == null ? void 0 : params.exporter) != null ? _j : new OTLPTraceExporter({
@@ -217,6 +325,14 @@ var LangfuseSpanProcessor = class extends BatchSpanProcessor {
   get logger() {
     return getGlobalLogger3();
   }
+  /**
+   * 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, parentContext) {
     span.setAttributes({
       [LangfuseOtelSpanAttributes.ENVIRONMENT]: this.environment,
@@ -224,6 +340,20 @@ var LangfuseSpanProcessor = class extends BatchSpanProcessor {
     });
     return super.onStart(span, parentContext);
   }
+  /**
+   * 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) {
     var _a2, _b;
     if (this.shouldExportSpan) {
@@ -269,10 +399,24 @@ ${JSON.stringify(
       );
     });
   }
+  /**
+   * Forces an immediate flush of all pending spans and media uploads.
+   *
+   * @returns Promise that resolves when all pending operations are complete
+   *
+   * @override
+   */
   async forceFlush() {
     await this.flush();
     return super.forceFlush();
   }
+  /**
+   * Gracefully shuts down the processor, ensuring all pending operations are completed.
+   *
+   * @returns Promise that resolves when shutdown is complete
+   *
+   * @override
+   */
   async shutdown() {
     await this.flush();
     return super.shutdown();