@langfuse/core 4.3.0 → 4.4.0

package/dist/index.mjs

@@ -59,6 +59,24 @@ function base64Decode(input) {
   const bytes = base64ToBytes(input);
   return new TextDecoder().decode(bytes);
 }
+async function createExperimentId() {
+  const randomBytes = new Uint8Array(8);
+  crypto.getRandomValues(randomBytes);
+  return Array.from(randomBytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function createExperimentItemId(input) {
+  const serialized = serializeValue(input);
+  const data = new TextEncoder().encode(serialized);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  return hashHex.slice(0, 16);
+}
+function serializeValue(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}
 
 // src/logger/index.ts
 var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
@@ -235,7 +253,7 @@ var resetGlobalLogger = () => {
 // package.json
 var package_default = {
   name: "@langfuse/core",
-  version: "4.3.0",
+  version: "4.4.0",
   description: "Core functions and utilities for Langfuse packages",
   type: "module",
   sideEffects: false,
@@ -262,6 +280,9 @@ var package_default = {
   files: [
     "dist"
   ],
+  peerDependencies: {
+    "@opentelemetry/api": "^1.9.0"
+  },
   devDependencies: {
     "@types/node": "^24.1.0"
   }
@@ -271,6 +292,7 @@ var package_default = {
 var LANGFUSE_TRACER_NAME = "langfuse-sdk";
 var LANGFUSE_SDK_VERSION = package_default.version;
 var LANGFUSE_SDK_NAME = "javascript";
+var LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT = "sdk-experiment";
 var LangfuseOtelSpanAttributes = /* @__PURE__ */ ((LangfuseOtelSpanAttributes2) => {
   LangfuseOtelSpanAttributes2["TRACE_NAME"] = "langfuse.trace.name";
   LangfuseOtelSpanAttributes2["TRACE_USER_ID"] = "user.id";
@@ -297,6 +319,15 @@ var LangfuseOtelSpanAttributes = /* @__PURE__ */ ((LangfuseOtelSpanAttributes2)
   LangfuseOtelSpanAttributes2["RELEASE"] = "langfuse.release";
   LangfuseOtelSpanAttributes2["VERSION"] = "langfuse.version";
   LangfuseOtelSpanAttributes2["AS_ROOT"] = "langfuse.internal.as_root";
+  LangfuseOtelSpanAttributes2["EXPERIMENT_ID"] = "langfuse.experiment.id";
+  LangfuseOtelSpanAttributes2["EXPERIMENT_NAME"] = "langfuse.experiment.name";
+  LangfuseOtelSpanAttributes2["EXPERIMENT_DESCRIPTION"] = "langfuse.experiment.description";
+  LangfuseOtelSpanAttributes2["EXPERIMENT_METADATA"] = "langfuse.experiment.metadata";
+  LangfuseOtelSpanAttributes2["EXPERIMENT_DATASET_ID"] = "langfuse.experiment.dataset.id";
+  LangfuseOtelSpanAttributes2["EXPERIMENT_ITEM_ID"] = "langfuse.experiment.item.id";
+  LangfuseOtelSpanAttributes2["EXPERIMENT_ITEM_EXPECTED_OUTPUT"] = "langfuse.experiment.item.expected_output";
+  LangfuseOtelSpanAttributes2["EXPERIMENT_ITEM_METADATA"] = "langfuse.experiment.item.metadata";
+  LangfuseOtelSpanAttributes2["EXPERIMENT_ITEM_ROOT_OBSERVATION_ID"] = "langfuse.experiment.item.root_observation_id";
   LangfuseOtelSpanAttributes2["TRACE_COMPAT_USER_ID"] = "langfuse.user.id";
   LangfuseOtelSpanAttributes2["TRACE_COMPAT_SESSION_ID"] = "langfuse.session.id";
   return LangfuseOtelSpanAttributes2;
@@ -11352,6 +11383,374 @@ var LangfuseMedia = class {
     return this.base64DataUri;
   }
 };
+
+// src/propagation.ts
+import {
+  context as otelContextApi,
+  trace as otelTraceApi,
+  propagation,
+  createContextKey
+} from "@opentelemetry/api";
+var experimentKeys = [
+  "experimentId",
+  "experimentName",
+  "experimentMetadata",
+  "experimentDatasetId",
+  "experimentItemId",
+  "experimentItemMetadata",
+  "experimentItemRootObservationId"
+];
+var LangfuseOtelContextKeys = {
+  userId: createContextKey("langfuse_user_id"),
+  sessionId: createContextKey("langfuse_session_id"),
+  metadata: createContextKey("langfuse_metadata"),
+  version: createContextKey("langfuse_version"),
+  tags: createContextKey("langfuse_tags"),
+  // Experiments
+  experimentId: createContextKey("langfuse_experiment_id"),
+  experimentName: createContextKey("langfuse_experiment_name"),
+  experimentMetadata: createContextKey("langfuse_experiment_metadata"),
+  experimentDatasetId: createContextKey("langfuse_experiment_dataset_id"),
+  experimentItemId: createContextKey("langfuse_experiment_item_id"),
+  experimentItemMetadata: createContextKey("langfuse_experiment_item_metadata"),
+  experimentItemRootObservationId: createContextKey(
+    "langfuse_experiment_item_root_observation_id"
+  )
+};
+var LANGFUSE_BAGGAGE_PREFIX = "langfuse_";
+var LANGFUSE_BAGGAGE_TAGS_SEPARATOR = ",";
+function propagateAttributes(params, fn) {
+  var _a2;
+  let context = otelContextApi.active();
+  const span = otelTraceApi.getActiveSpan();
+  const asBaggage = (_a2 = params.asBaggage) != null ? _a2 : false;
+  const { userId, sessionId, metadata, version, tags, _internalExperiment } = params;
+  if (userId) {
+    if (isValidPropagatedString({ value: userId, attributeName: "userId" })) {
+      context = setPropagatedAttribute({
+        key: "userId",
+        value: userId,
+        context,
+        span,
+        asBaggage
+      });
+    }
+  }
+  if (sessionId) {
+    if (isValidPropagatedString({
+      value: sessionId,
+      attributeName: "sessionId"
+    })) {
+      context = setPropagatedAttribute({
+        key: "sessionId",
+        value: sessionId,
+        context,
+        span,
+        asBaggage
+      });
+    }
+  }
+  if (version) {
+    if (isValidPropagatedString({
+      value: version,
+      attributeName: "version"
+    })) {
+      context = setPropagatedAttribute({
+        key: "version",
+        value: version,
+        context,
+        span,
+        asBaggage
+      });
+    }
+  }
+  if (tags && tags.length > 0) {
+    const validTags = tags.filter(
+      (tag) => isValidPropagatedString({
+        value: tag,
+        attributeName: "tag"
+      })
+    );
+    if (validTags.length > 0) {
+      context = setPropagatedAttribute({
+        key: "tags",
+        value: validTags,
+        context,
+        span,
+        asBaggage
+      });
+    }
+  }
+  if (metadata) {
+    const validatedMetadata = {};
+    for (const [key, value] of Object.entries(metadata)) {
+      if (isValidPropagatedString({
+        value,
+        attributeName: `metadata.${key}`
+      })) {
+        validatedMetadata[key] = value;
+      }
+    }
+    if (Object.keys(validatedMetadata).length > 0) {
+      context = setPropagatedAttribute({
+        key: "metadata",
+        value: validatedMetadata,
+        context,
+        span,
+        asBaggage
+      });
+    }
+  }
+  if (_internalExperiment) {
+    for (const [key, value] of Object.entries(_internalExperiment)) {
+      if (value !== void 0) {
+        context = setPropagatedAttribute({
+          key,
+          value,
+          context,
+          span,
+          asBaggage
+        });
+      }
+    }
+  }
+  return otelContextApi.with(context, fn);
+}
+function getPropagatedAttributesFromContext(context) {
+  const propagatedAttributes = {};
+  const baggage = propagation.getBaggage(context);
+  if (baggage) {
+    baggage.getAllEntries().forEach(([baggageKey, baggageEntry]) => {
+      if (baggageKey.startsWith(LANGFUSE_BAGGAGE_PREFIX)) {
+        const spanKey = getSpanKeyFromBaggageKey(baggageKey);
+        if (spanKey) {
+          const isMergedTags = baggageKey == getBaggageKeyForPropagatedKey("tags");
+          propagatedAttributes[spanKey] = isMergedTags ? baggageEntry.value.split(LANGFUSE_BAGGAGE_TAGS_SEPARATOR) : baggageEntry.value;
+        }
+      }
+    });
+  }
+  const userId = context.getValue(LangfuseOtelContextKeys["userId"]);
+  if (userId && typeof userId === "string") {
+    const spanKey = getSpanKeyForPropagatedKey("userId");
+    propagatedAttributes[spanKey] = userId;
+  }
+  const sessionId = context.getValue(LangfuseOtelContextKeys["sessionId"]);
+  if (sessionId && typeof sessionId === "string") {
+    const spanKey = getSpanKeyForPropagatedKey("sessionId");
+    propagatedAttributes[spanKey] = sessionId;
+  }
+  const version = context.getValue(LangfuseOtelContextKeys["version"]);
+  if (version && typeof version === "string") {
+    const spanKey = getSpanKeyForPropagatedKey("version");
+    propagatedAttributes[spanKey] = version;
+  }
+  const tags = context.getValue(LangfuseOtelContextKeys["tags"]);
+  if (tags && Array.isArray(tags)) {
+    const spanKey = getSpanKeyForPropagatedKey("tags");
+    propagatedAttributes[spanKey] = tags;
+  }
+  const metadata = context.getValue(LangfuseOtelContextKeys["metadata"]);
+  if (metadata && typeof metadata === "object" && metadata !== null) {
+    for (const [k, v] of Object.entries(metadata)) {
+      const spanKey = `${"langfuse.trace.metadata" /* TRACE_METADATA */}.${k}`;
+      propagatedAttributes[spanKey] = String(v);
+    }
+  }
+  for (const key of experimentKeys) {
+    const contextKey = LangfuseOtelContextKeys[key];
+    const value = context.getValue(contextKey);
+    if (value && typeof value === "string") {
+      const spanKey = getSpanKeyForPropagatedKey(key);
+      propagatedAttributes[spanKey] = value;
+    }
+  }
+  if (propagatedAttributes[getSpanKeyForPropagatedKey("experimentItemRootObservationId")]) {
+    propagatedAttributes["langfuse.environment" /* ENVIRONMENT */] = LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT;
+  }
+  return propagatedAttributes;
+}
+function setPropagatedAttribute(params) {
+  const { key, value, span, asBaggage } = params;
+  let context = params.context;
+  let mergedMetadata = key === "metadata" ? getContextMergedMetadata(context, value) : {};
+  let mergedTags = key === "tags" ? getContextMergedTags(context, value) : [];
+  const contextKey = getContextKeyForPropagatedKey(key);
+  if (key === "metadata") {
+    context = context.setValue(contextKey, mergedMetadata);
+  } else if (key === "tags") {
+    context = context.setValue(contextKey, mergedTags);
+  } else {
+    context = context.setValue(contextKey, value);
+  }
+  if (span && span.isRecording()) {
+    if (key === "metadata") {
+      for (const [k, v] of Object.entries(mergedMetadata)) {
+        span.setAttribute(
+          `${"langfuse.trace.metadata" /* TRACE_METADATA */}.${k}`,
+          v
+        );
+      }
+    } else if (key === "tags") {
+      const spanKey = getSpanKeyForPropagatedKey(key);
+      span.setAttribute(spanKey, mergedTags);
+    } else {
+      const spanKey = getSpanKeyForPropagatedKey(key);
+      span.setAttribute(spanKey, value);
+    }
+  }
+  if (asBaggage) {
+    const baggageKey = getBaggageKeyForPropagatedKey(key);
+    let baggage = propagation.getBaggage(context) || propagation.createBaggage();
+    if (key === "metadata") {
+      for (const [k, v] of Object.entries(mergedMetadata)) {
+        baggage = baggage.setEntry(`${baggageKey}_${k}`, { value: v });
+      }
+    } else if (key === "tags") {
+      baggage = baggage.setEntry(baggageKey, {
+        value: mergedTags.join(LANGFUSE_BAGGAGE_TAGS_SEPARATOR)
+      });
+    } else {
+      baggage = baggage.setEntry(baggageKey, { value });
+    }
+    context = propagation.setBaggage(context, baggage);
+  }
+  return context;
+}
+function getContextMergedTags(context, newTags) {
+  const existingTags = context.getValue(LangfuseOtelContextKeys["tags"]);
+  if (existingTags && Array.isArray(existingTags)) {
+    return [.../* @__PURE__ */ new Set([...existingTags, ...newTags])];
+  } else {
+    return newTags;
+  }
+}
+function getContextMergedMetadata(context, newMetadata) {
+  const existingMetadata = context.getValue(
+    LangfuseOtelContextKeys["metadata"]
+  );
+  if (existingMetadata && typeof existingMetadata === "object" && existingMetadata !== null && !Array.isArray(existingMetadata)) {
+    return { ...existingMetadata, ...newMetadata };
+  } else {
+    return newMetadata;
+  }
+}
+function isValidPropagatedString(params) {
+  const logger = getGlobalLogger();
+  const { value, attributeName } = params;
+  if (typeof value !== "string") {
+    logger.warn(
+      `Propagated attribute '${attributeName}' must be a string. Dropping value.`
+    );
+    return false;
+  }
+  if (value.length > 200) {
+    logger.warn(
+      `Propagated attribute '${attributeName}' value is over 200 characters (${value.length} chars). Dropping value.`
+    );
+    return false;
+  }
+  return true;
+}
+function getContextKeyForPropagatedKey(key) {
+  return LangfuseOtelContextKeys[key];
+}
+function getSpanKeyForPropagatedKey(key) {
+  switch (key) {
+    case "userId":
+      return "user.id" /* TRACE_USER_ID */;
+    case "sessionId":
+      return "session.id" /* TRACE_SESSION_ID */;
+    case "version":
+      return "langfuse.version" /* VERSION */;
+    case "metadata":
+      return "langfuse.trace.metadata" /* TRACE_METADATA */;
+    case "tags":
+      return "langfuse.trace.tags" /* TRACE_TAGS */;
+    case "experimentId":
+      return "langfuse.experiment.id" /* EXPERIMENT_ID */;
+    case "experimentName":
+      return "langfuse.experiment.name" /* EXPERIMENT_NAME */;
+    case "experimentMetadata":
+      return "langfuse.experiment.metadata" /* EXPERIMENT_METADATA */;
+    case "experimentDatasetId":
+      return "langfuse.experiment.dataset.id" /* EXPERIMENT_DATASET_ID */;
+    case "experimentItemId":
+      return "langfuse.experiment.item.id" /* EXPERIMENT_ITEM_ID */;
+    case "experimentItemMetadata":
+      return "langfuse.experiment.item.metadata" /* EXPERIMENT_ITEM_METADATA */;
+    case "experimentItemRootObservationId":
+      return "langfuse.experiment.item.root_observation_id" /* EXPERIMENT_ITEM_ROOT_OBSERVATION_ID */;
+    default: {
+      const fallback = key;
+      throw Error("Unhandled propagated key", fallback);
+    }
+  }
+}
+function getBaggageKeyForPropagatedKey(key) {
+  switch (key) {
+    case "userId":
+      return `${LANGFUSE_BAGGAGE_PREFIX}user_id`;
+    case "sessionId":
+      return `${LANGFUSE_BAGGAGE_PREFIX}session_id`;
+    case "version":
+      return `${LANGFUSE_BAGGAGE_PREFIX}version`;
+    case "metadata":
+      return `${LANGFUSE_BAGGAGE_PREFIX}metadata`;
+    case "tags":
+      return `${LANGFUSE_BAGGAGE_PREFIX}tags`;
+    case "experimentId":
+      return `${LANGFUSE_BAGGAGE_PREFIX}experiment_id`;
+    case "experimentName":
+      return `${LANGFUSE_BAGGAGE_PREFIX}experiment_name`;
+    case "experimentMetadata":
+      return `${LANGFUSE_BAGGAGE_PREFIX}experiment_metadata`;
+    case "experimentDatasetId":
+      return `${LANGFUSE_BAGGAGE_PREFIX}experiment_dataset_id`;
+    case "experimentItemId":
+      return `${LANGFUSE_BAGGAGE_PREFIX}experiment_item_id`;
+    case "experimentItemMetadata":
+      return `${LANGFUSE_BAGGAGE_PREFIX}experiment_item_metadata`;
+    case "experimentItemRootObservationId":
+      return `${LANGFUSE_BAGGAGE_PREFIX}experiment_item_root_observation_id`;
+    default: {
+      const fallback = key;
+      throw Error("Unhandled propagated key", fallback);
+    }
+  }
+}
+function getSpanKeyFromBaggageKey(baggageKey) {
+  if (!baggageKey.startsWith(LANGFUSE_BAGGAGE_PREFIX)) return;
+  const suffix = baggageKey.slice(LANGFUSE_BAGGAGE_PREFIX.length);
+  if (suffix.startsWith("metadata_")) {
+    const metadataKey = suffix.slice("metadata_".length);
+    return `${"langfuse.trace.metadata" /* TRACE_METADATA */}.${metadataKey}`;
+  }
+  switch (suffix) {
+    case "user_id":
+      return getSpanKeyForPropagatedKey("userId");
+    case "session_id":
+      return getSpanKeyForPropagatedKey("sessionId");
+    case "version":
+      return getSpanKeyForPropagatedKey("version");
+    case "tags":
+      return getSpanKeyForPropagatedKey("tags");
+    case "experiment_id":
+      return getSpanKeyForPropagatedKey("experimentId");
+    case "experiment_name":
+      return getSpanKeyForPropagatedKey("experimentName");
+    case "experiment_metadata":
+      return getSpanKeyForPropagatedKey("experimentMetadata");
+    case "experiment_dataset_id":
+      return getSpanKeyForPropagatedKey("experimentDatasetId");
+    case "experiment_item_id":
+      return getSpanKeyForPropagatedKey("experimentItemId");
+    case "experiment_item_metadata":
+      return getSpanKeyForPropagatedKey("experimentItemMetadata");
+    case "experiment_item_root_observation_id":
+      return getSpanKeyForPropagatedKey("experimentItemRootObservationId");
+  }
+}
 export {
   AccessDeniedError,
   AnnotationQueueObjectType,
@@ -11363,6 +11762,7 @@ export {
   CommentObjectType,
   DatasetStatus,
   Error2 as Error,
+  LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT,
   LANGFUSE_SDK_NAME,
   LANGFUSE_SDK_VERSION,
   LANGFUSE_TRACER_NAME,
@@ -11370,6 +11770,7 @@ export {
   LangfuseAPIError,
   LangfuseAPITimeoutError,
   LangfuseMedia,
+  LangfuseOtelContextKeys,
   LangfuseOtelSpanAttributes,
   LlmAdapter,
   LogLevel,
@@ -11395,6 +11796,8 @@ export {
   comments_exports as comments,
   commons_exports as commons,
   configureGlobalLogger,
+  createExperimentId,
+  createExperimentItemId,
   createLogger,
   datasetItems_exports as datasetItems,
   datasetRunItems_exports as datasetRunItems,
@@ -11402,6 +11805,7 @@ export {
   generateUUID,
   getEnv,
   getGlobalLogger,
+  getPropagatedAttributesFromContext,
   health_exports as health,
   ingestion_exports as ingestion,
   llmConnections_exports as llmConnections,
@@ -11415,12 +11819,14 @@ export {
   projects_exports as projects,
   promptVersion_exports as promptVersion,
   prompts_exports as prompts,
+  propagateAttributes,
   resetGlobalLogger,
   safeSetTimeout,
   scim_exports as scim,
   score_exports as score,
   scoreConfigs_exports as scoreConfigs,
   scoreV2_exports as scoreV2,
+  serializeValue,
   sessions_exports as sessions,
   trace_exports as trace,
   utils_exports as utils