@langfuse/otel 4.0.0-alpha.0

package/dist/media.js

@@ -0,0 +1,91 @@
+import { getGlobalLogger } from "@langfuse/core";
+import { getSha256HashFromBytes, isCryptoAvailable } from "./hash.js";
+/**
+ * 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.
+ */
+class LangfuseMedia {
+    constructor(params) {
+        const { source } = params;
+        this._source = source;
+        if (source === "base64_data_uri") {
+            const [contentBytesParsed, contentTypeParsed] = this.parseBase64DataUri(params.base64DataUri);
+            this._contentBytes = contentBytesParsed;
+            this._contentType = contentTypeParsed;
+        }
+        else {
+            this._contentBytes = params.contentBytes;
+            this._contentType = params.contentType;
+        }
+    }
+    parseBase64DataUri(data) {
+        try {
+            if (!data || typeof data !== "string") {
+                throw new Error("Data URI is not a string");
+            }
+            if (!data.startsWith("data:")) {
+                throw new Error("Data URI does not start with 'data:'");
+            }
+            const [header, actualData] = data.slice(5).split(",", 2);
+            if (!header || !actualData) {
+                throw new Error("Invalid URI");
+            }
+            const headerParts = header.split(";");
+            if (!headerParts.includes("base64")) {
+                throw new Error("Data is not base64 encoded");
+            }
+            const contentType = headerParts[0];
+            if (!contentType) {
+                throw new Error("Content type is empty");
+            }
+            return [
+                Buffer.from(actualData, "base64"),
+                contentType,
+            ];
+        }
+        catch (error) {
+            getGlobalLogger().error("Error parsing base64 data URI", error);
+            return [undefined, undefined];
+        }
+    }
+    get id() {
+        if (!this.contentSha256Hash)
+            return null;
+        const urlSafeContentHash = this.contentSha256Hash
+            .replaceAll("+", "-")
+            .replaceAll("/", "_");
+        return urlSafeContentHash.slice(0, 22);
+    }
+    get contentLength() {
+        var _a;
+        return (_a = this._contentBytes) === null || _a === void 0 ? void 0 : _a.length;
+    }
+    get contentSha256Hash() {
+        if (!this._contentBytes || !isCryptoAvailable) {
+            return undefined;
+        }
+        try {
+            return getSha256HashFromBytes(this._contentBytes);
+        }
+        catch (error) {
+            getGlobalLogger().warn("[Langfuse] Failed to generate SHA-256 hash for media content:", error);
+            return undefined;
+        }
+    }
+    get tag() {
+        if (!this._contentType || !this._source || !this.id)
+            return null;
+        return `@@@langfuseMedia:type=${this._contentType}|id=${this.id}|source=${this._source}@@@`;
+    }
+    get base64DataUri() {
+        if (!this._contentBytes)
+            return null;
+        return `data:${this._contentType};base64,${Buffer.from(this._contentBytes).toString("base64")}`;
+    }
+    toJSON() {
+        return this.base64DataUri;
+    }
+}
+export { LangfuseMedia };

package/dist/span-processor.d.ts

@@ -0,0 +1,44 @@
+import { Span, BatchSpanProcessor, SpanExporter, ReadableSpan } from "@opentelemetry/sdk-trace-base";
+export type MaskFunction = (params: {
+    data: any;
+}) => any;
+export type ShouldExportSpan = (params: {
+    otelSpan: ReadableSpan;
+}) => boolean;
+export interface LangfuseSpanProcessorParams {
+    exporter?: SpanExporter;
+    publicKey?: string;
+    secretKey?: string;
+    baseUrl?: string;
+    flushAt?: number;
+    flushInterval?: number;
+    mask?: MaskFunction;
+    shouldExportSpan?: ShouldExportSpan;
+    environment?: string;
+    release?: string;
+    timeout?: number;
+    additionalHeaders?: Record<string, string>;
+}
+export declare class LangfuseSpanProcessor extends BatchSpanProcessor {
+    private pendingMediaUploads;
+    private publicKey?;
+    private baseUrl?;
+    private environment?;
+    private release?;
+    private mask?;
+    private shouldExportSpan?;
+    private apiClient;
+    constructor(params: LangfuseSpanProcessorParams);
+    private get logger();
+    onStart(span: Span, parentContext: any): void;
+    onEnd(span: ReadableSpan): void;
+    private flush;
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private handleMediaInPlace;
+    private applyMaskInPlace;
+    private applyMask;
+    private processMediaItem;
+    private uploadMediaWithBackoff;
+}
+//# sourceMappingURL=span-processor.d.ts.map

package/dist/span-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-processor.d.ts","sourceRoot":"","sources":["../src/span-processor.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,IAAI,EACJ,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACb,MAAM,+BAA+B,CAAC;AAKvC,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,GAAG,CAAA;CAAE,KAAK,GAAG,CAAC;AAC1D,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,YAAY,CAAA;CAAE,KAAK,OAAO,CAAC;AAE/E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,qBAAa,qBAAsB,SAAQ,kBAAkB;IAC3D,OAAO,CAAC,mBAAmB,CAAoC;IAE/D,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,IAAI,CAAC,CAAe;IAC5B,OAAO,CAAC,gBAAgB,CAAC,CAAmB;IAC5C,OAAO,CAAC,SAAS,CAAoB;gBAEzB,MAAM,EAAE,2BAA2B;IAyF/C,OAAO,KAAK,MAAM,GAEjB;IAEM,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,GAAG,IAAI;IAS7C,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;YAyCxB,KAAK;IAQN,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtC,OAAO,CAAC,kBAAkB;IAsF1B,OAAO,CAAC,gBAAgB;IAmBxB,OAAO,CAAC,SAAS;YAcH,gBAAgB;YA4EhB,sBAAsB;CAkDrC"}

package/dist/span-processor.js

@@ -0,0 +1,293 @@
+import { getGlobalLogger, generateUUID, LangfuseAPIClient, LANGFUSE_SDK_VERSION, LangfuseOtelSpanAttributes, getEnv, } from "@langfuse/core";
+import { hrTimeToMilliseconds } from "@opentelemetry/core";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace-base";
+import { isCryptoAvailable } from "./hash.js";
+import { LangfuseMedia } from "./media.js";
+export class LangfuseSpanProcessor extends BatchSpanProcessor {
+    constructor(params) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+        const logger = getGlobalLogger();
+        const publicKey = (_a = params.publicKey) !== null && _a !== void 0 ? _a : getEnv("LANGFUSE_PUBLIC_KEY");
+        const secretKey = (_b = params.secretKey) !== null && _b !== void 0 ? _b : getEnv("LANGFUSE_SECRET_KEY");
+        const baseUrl = (_e = (_d = (_c = params.baseUrl) !== null && _c !== void 0 ? _c : getEnv("LANGFUSE_BASE_URL")) !== null && _d !== void 0 ? _d : getEnv("LANGFUSE_BASEURL")) !== null && _e !== void 0 ? _e : "https://cloud.langfuse.com";
+        if (!params.exporter && !publicKey) {
+            logger.warn("No exporter configured and no public key provided in constructor or as LANGFUSE_PUBLIC_KEY env var. Span exports will fail.");
+        }
+        if (!params.exporter && !secretKey) {
+            logger.warn("No exporter configured and no secret key provided in constructor or as LANGFUSE_SECRET_KEY env var. Span exports will fail.");
+        }
+        const flushAt = (_f = params.flushAt) !== null && _f !== void 0 ? _f : getEnv("LANGFUSE_FLUSH_AT");
+        const flushIntervalSeconds = (_g = params.flushInterval) !== null && _g !== void 0 ? _g : getEnv("LANGFUSE_FLUSH_INTERVAL");
+        const authHeaderValue = Buffer.from(`${publicKey}:${secretKey}`).toString("base64");
+        const timeoutSeconds = (_h = params.timeout) !== null && _h !== void 0 ? _h : Number((_j = getEnv("LANGFUSE_TIMEOUT")) !== null && _j !== void 0 ? _j : 5);
+        const exporter = (_k = params.exporter) !== null && _k !== void 0 ? _k : new OTLPTraceExporter({
+            url: `${baseUrl}/api/public/otel/v1/traces`,
+            headers: {
+                Authorization: `Basic ${authHeaderValue}`,
+                x_langfuse_sdk_name: "javascript",
+                x_langfuse_sdk_version: LANGFUSE_SDK_VERSION,
+                x_langfuse_public_key: publicKey !== null && publicKey !== void 0 ? publicKey : "<missing>",
+                ...params.additionalHeaders,
+            },
+            timeoutMillis: timeoutSeconds * 1000,
+        });
+        super(exporter, {
+            maxExportBatchSize: flushAt ? Number(flushAt) : undefined,
+            scheduledDelayMillis: flushIntervalSeconds
+                ? Number(flushIntervalSeconds) * 1000
+                : undefined,
+        });
+        this.pendingMediaUploads = {};
+        this.publicKey = publicKey;
+        this.baseUrl = baseUrl;
+        this.environment =
+            (_l = params.environment) !== null && _l !== void 0 ? _l : getEnv("LANGFUSE_TRACING_ENVIRONMENT");
+        this.release = (_m = params.release) !== null && _m !== void 0 ? _m : getEnv("LANGFUSE_RELEASE");
+        this.mask = params.mask;
+        this.shouldExportSpan = params.shouldExportSpan;
+        this.apiClient = new LangfuseAPIClient({
+            baseUrl: this.baseUrl,
+            username: this.publicKey,
+            password: secretKey,
+            xLangfusePublicKey: this.publicKey,
+            xLangfuseSdkVersion: LANGFUSE_SDK_VERSION,
+            xLangfuseSdkName: "javascript",
+            environment: "", // noop as baseUrl is set
+            headers: params.additionalHeaders,
+        });
+        logger.debug("Initialized LangfuseSpanProcessor with params:", {
+            publicKey,
+            baseUrl,
+            environment: this.environment,
+            release: this.release,
+            timeoutSeconds,
+            flushAt,
+            flushIntervalSeconds,
+        });
+        // Warn if crypto is not available
+        if (!isCryptoAvailable) {
+            logger.warn("[Langfuse] Crypto module not available in this runtime. Media upload functionality will be disabled. " +
+                "Spans will still be processed normally, but any media content in base64 data URIs will not be uploaded to Langfuse.");
+        }
+    }
+    get logger() {
+        return getGlobalLogger();
+    }
+    onStart(span, parentContext) {
+        span.setAttributes({
+            [LangfuseOtelSpanAttributes.ENVIRONMENT]: this.environment,
+            [LangfuseOtelSpanAttributes.RELEASE]: this.release,
+        });
+        return super.onStart(span, parentContext);
+    }
+    onEnd(span) {
+        var _a, _b;
+        if (this.shouldExportSpan) {
+            try {
+                if (this.shouldExportSpan({ otelSpan: span }) === false)
+                    return;
+            }
+            catch (err) {
+                this.logger.error("ShouldExportSpan failed with error. Excluding span. Error: ", err);
+                return;
+            }
+        }
+        this.applyMaskInPlace(span);
+        this.handleMediaInPlace(span);
+        this.logger.debug(`Processed span:\n${JSON.stringify({
+            name: span.name,
+            traceId: span.spanContext().traceId,
+            spanId: span.spanContext().spanId,
+            parentSpanId: (_b = (_a = span.parentSpanContext) === null || _a === void 0 ? void 0 : _a.spanId) !== null && _b !== void 0 ? _b : null,
+            attributes: span.attributes,
+            startTime: new Date(hrTimeToMilliseconds(span.startTime)),
+            endTime: new Date(hrTimeToMilliseconds(span.endTime)),
+            durationMs: hrTimeToMilliseconds(span.duration),
+            kind: span.kind,
+            status: span.status,
+            resource: span.resource.attributes,
+            instrumentationScope: span.instrumentationScope,
+        }, null, 2)}`);
+        super.onEnd(span);
+    }
+    async flush() {
+        await Promise.all(Object.values(this.pendingMediaUploads)).catch((e) => {
+            this.logger.error(e instanceof Error ? e.message : "Unhandled media upload error");
+        });
+    }
+    async forceFlush() {
+        await this.flush();
+        return super.forceFlush();
+    }
+    async shutdown() {
+        await this.flush();
+        return super.shutdown();
+    }
+    handleMediaInPlace(span) {
+        var _a;
+        // Skip media handling if crypto is not available
+        if (!isCryptoAvailable) {
+            this.logger.debug("[Langfuse] Crypto not available, skipping media processing");
+            return;
+        }
+        const mediaAttributes = [
+            LangfuseOtelSpanAttributes.OBSERVATION_INPUT,
+            LangfuseOtelSpanAttributes.TRACE_INPUT,
+            LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT,
+            LangfuseOtelSpanAttributes.TRACE_OUTPUT,
+            LangfuseOtelSpanAttributes.OBSERVATION_METADATA,
+            LangfuseOtelSpanAttributes.TRACE_METADATA,
+        ];
+        for (const mediaAttribute of mediaAttributes) {
+            const mediaRelevantAttributeKeys = Object.keys(span.attributes).filter((attributeName) => attributeName.startsWith(mediaAttribute));
+            for (const key of mediaRelevantAttributeKeys) {
+                const value = span.attributes[key];
+                if (typeof value !== "string") {
+                    this.logger.warn(`Span attribute ${mediaAttribute} is not a stringified object. Skipping media handling.`);
+                    continue;
+                }
+                // Find media base64 data URI
+                let mediaReplacedValue = value;
+                const regex = /data:[^;]+;base64,[A-Za-z0-9+/]+=*/g;
+                const foundMedia = [...new Set((_a = value.match(regex)) !== null && _a !== void 0 ? _a : [])];
+                if (foundMedia.length === 0)
+                    continue;
+                for (const mediaDataUri of foundMedia) {
+                    // For each media, create media tag and initiate upload
+                    const media = new LangfuseMedia({
+                        base64DataUri: mediaDataUri,
+                        source: "base64_data_uri",
+                    });
+                    if (!media.tag) {
+                        this.logger.warn("Failed to create Langfuse media tag. Skipping media item.");
+                        continue;
+                    }
+                    const uploadPromise = this.processMediaItem({
+                        media,
+                        traceId: span.spanContext().traceId,
+                        observationId: span.spanContext().spanId,
+                        field: mediaAttribute.includes("input")
+                            ? "input"
+                            : mediaAttribute.includes("output")
+                                ? "output"
+                                : "metadata", // todo: make more robust
+                    });
+                    const promiseId = generateUUID();
+                    this.pendingMediaUploads[promiseId] = uploadPromise;
+                    uploadPromise.finally(() => {
+                        delete this.pendingMediaUploads[promiseId];
+                    });
+                    // Replace original attribute with media escaped attribute
+                    mediaReplacedValue = mediaReplacedValue.replaceAll(mediaDataUri, media.tag);
+                }
+                span.attributes[key] = mediaReplacedValue;
+            }
+        }
+    }
+    applyMaskInPlace(span) {
+        const maskCandidates = [
+            LangfuseOtelSpanAttributes.OBSERVATION_INPUT,
+            LangfuseOtelSpanAttributes.TRACE_INPUT,
+            LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT,
+            LangfuseOtelSpanAttributes.TRACE_OUTPUT,
+            LangfuseOtelSpanAttributes.OBSERVATION_METADATA,
+            LangfuseOtelSpanAttributes.TRACE_METADATA,
+        ];
+        for (const maskCandidate of maskCandidates) {
+            if (maskCandidate in span.attributes) {
+                span.attributes[maskCandidate] = this.applyMask(span.attributes[maskCandidate]);
+            }
+        }
+    }
+    applyMask(data) {
+        if (!this.mask)
+            return data;
+        try {
+            return this.mask({ data });
+        }
+        catch (err) {
+            this.logger.warn(`Applying mask function failed due to error, fully masking property. Error: ${err}`);
+            return "<fully masked due to failed mask function>";
+        }
+    }
+    async processMediaItem({ media, traceId, observationId, field, }) {
+        try {
+            if (!media.contentLength ||
+                !media._contentType ||
+                !media.contentSha256Hash ||
+                !media._contentBytes) {
+                return;
+            }
+            const { uploadUrl, mediaId } = await this.apiClient.media.getUploadUrl({
+                contentLength: media.contentLength,
+                traceId,
+                observationId,
+                field,
+                contentType: media._contentType,
+                sha256Hash: media.contentSha256Hash,
+            });
+            if (!uploadUrl) {
+                this.logger.debug(`Media status: Media with ID ${media.id} already uploaded. Skipping duplicate upload.`);
+                return;
+            }
+            if (media.id !== mediaId) {
+                this.logger.error(`Media integrity error: Media ID mismatch between SDK (${media.id}) and Server (${mediaId}). Upload cancelled. Please check media ID generation logic.`);
+                return;
+            }
+            this.logger.debug(`Uploading media ${mediaId}...`);
+            const startTime = Date.now();
+            const uploadResponse = await this.uploadMediaWithBackoff({
+                uploadUrl,
+                contentBytes: media._contentBytes,
+                contentType: media._contentType,
+                contentSha256Hash: media.contentSha256Hash,
+                maxRetries: 3,
+                baseDelay: 1000,
+            });
+            if (!uploadResponse) {
+                throw Error("Media upload process failed");
+            }
+            await this.apiClient.media.patch(mediaId, {
+                uploadedAt: new Date().toISOString(),
+                uploadHttpStatus: uploadResponse.status,
+                uploadHttpError: await uploadResponse.text(),
+                uploadTimeMs: Date.now() - startTime,
+            });
+            this.logger.debug(`Media upload status reported for ${mediaId}`);
+        }
+        catch (err) {
+            this.logger.error(`Error processing media item: ${err}`);
+        }
+    }
+    async uploadMediaWithBackoff(params) {
+        const { uploadUrl, contentType, contentSha256Hash, contentBytes, maxRetries, baseDelay, } = params;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const uploadResponse = await fetch(uploadUrl, {
+                    method: "PUT",
+                    body: contentBytes,
+                    headers: {
+                        "Content-Type": contentType,
+                        "x-amz-checksum-sha256": contentSha256Hash,
+                        "x-ms-blob-type": "BlockBlob",
+                    },
+                });
+                if (attempt < maxRetries &&
+                    uploadResponse.status !== 200 &&
+                    uploadResponse.status !== 201) {
+                    throw new Error(`Upload failed with status ${uploadResponse.status}`);
+                }
+                return uploadResponse;
+            }
+            catch (e) {
+                if (attempt === maxRetries) {
+                    throw e;
+                }
+                const delay = baseDelay * Math.pow(2, attempt);
+                const jitter = Math.random() * 1000;
+                await new Promise((resolve) => setTimeout(resolve, delay + jitter));
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@langfuse/otel",
+  "version": "4.0.0-alpha.0",
+  "author": "Langfuse",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "description": "Langfuse OpenTelemetry export helpers",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@langfuse/core": "^4.0.0-alpha.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^2.0.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.202.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "clean": "rm -rf dist"
+  }
+}