@langfuse/core 4.4.10 → 4.5.1

package/dist/index.cjs

@@ -81,8 +81,10 @@ __export(index_exports, {
   logger: () => LoggerSingleton,
   media: () => media_exports,
   metrics: () => metrics_exports,
+  metricsV2: () => metricsV2_exports,
   models: () => models_exports,
   observations: () => observations_exports,
+  observationsV2: () => observationsV2_exports,
   opentelemetry: () => opentelemetry_exports,
   organizations: () => organizations_exports,
   projects: () => projects_exports,
@@ -351,7 +353,7 @@ var resetGlobalLogger = () => {
 // package.json
 var package_default = {
   name: "@langfuse/core",
-  version: "4.4.10-alpha.3",
+  version: "4.5.0",
   description: "Core functions and utilities for Langfuse packages",
   type: "module",
   sideEffects: false,
@@ -808,12 +810,18 @@ var MediaContentType = {
   ApplicationX7ZCompressed: "application/x-7z-compressed"
 };
 
+// src/api/api/resources/metricsV2/index.ts
+var metricsV2_exports = {};
+
 // src/api/api/resources/metrics/index.ts
 var metrics_exports = {};
 
 // src/api/api/resources/models/index.ts
 var models_exports = {};
 
+// src/api/api/resources/observationsV2/index.ts
+var observationsV2_exports = {};
+
 // src/api/api/resources/observations/index.ts
 var observations_exports = {};
 
@@ -5686,6 +5694,232 @@ var Media = class {
   }
 };
 
+// src/api/api/resources/metricsV2/client/Client.ts
+var MetricsV2 = class {
+  constructor(_options) {
+    this._options = _options;
+  }
+  /**
+   * Get metrics from the Langfuse project using a query object. V2 endpoint with optimized performance.
+   *
+   * ## V2 Differences
+   * - Supports `observations`, `scores-numeric`, and `scores-categorical` views only (traces view not supported)
+   * - Direct access to tags and release fields on observations
+   * - Backwards-compatible: traceName, traceRelease, traceVersion dimensions are still available on observations view
+   * - High cardinality dimensions are not supported and will return a 400 error (see below)
+   *
+   * For more details, see the [Metrics API documentation](https://langfuse.com/docs/metrics/features/metrics-api).
+   *
+   * ## Available Views
+   *
+   * ### observations
+   * Query observation-level data (spans, generations, events).
+   *
+   * **Dimensions:**
+   * - `environment` - Deployment environment (e.g., production, staging)
+   * - `type` - Type of observation (SPAN, GENERATION, EVENT)
+   * - `name` - Name of the observation
+   * - `level` - Logging level of the observation
+   * - `version` - Version of the observation
+   * - `tags` - User-defined tags
+   * - `release` - Release version
+   * - `traceName` - Name of the parent trace (backwards-compatible)
+   * - `traceRelease` - Release version of the parent trace (backwards-compatible, maps to release)
+   * - `traceVersion` - Version of the parent trace (backwards-compatible, maps to version)
+   * - `providedModelName` - Name of the model used
+   * - `promptName` - Name of the prompt used
+   * - `promptVersion` - Version of the prompt used
+   * - `startTimeMonth` - Month of start_time in YYYY-MM format
+   *
+   * **Measures:**
+   * - `count` - Total number of observations
+   * - `latency` - Observation latency (milliseconds)
+   * - `streamingLatency` - Generation latency from completion start to end (milliseconds)
+   * - `inputTokens` - Sum of input tokens consumed
+   * - `outputTokens` - Sum of output tokens produced
+   * - `totalTokens` - Sum of all tokens consumed
+   * - `outputTokensPerSecond` - Output tokens per second
+   * - `tokensPerSecond` - Total tokens per second
+   * - `inputCost` - Input cost (USD)
+   * - `outputCost` - Output cost (USD)
+   * - `totalCost` - Total cost (USD)
+   * - `timeToFirstToken` - Time to first token (milliseconds)
+   * - `countScores` - Number of scores attached to the observation
+   *
+   * ### scores-numeric
+   * Query numeric and boolean score data.
+   *
+   * **Dimensions:**
+   * - `environment` - Deployment environment
+   * - `name` - Name of the score (e.g., accuracy, toxicity)
+   * - `source` - Origin of the score (API, ANNOTATION, EVAL)
+   * - `dataType` - Data type (NUMERIC, BOOLEAN)
+   * - `configId` - Identifier of the score config
+   * - `timestampMonth` - Month in YYYY-MM format
+   * - `timestampDay` - Day in YYYY-MM-DD format
+   * - `value` - Numeric value of the score
+   * - `traceName` - Name of the parent trace
+   * - `tags` - Tags
+   * - `traceRelease` - Release version
+   * - `traceVersion` - Version
+   * - `observationName` - Name of the associated observation
+   * - `observationModelName` - Model name of the associated observation
+   * - `observationPromptName` - Prompt name of the associated observation
+   * - `observationPromptVersion` - Prompt version of the associated observation
+   *
+   * **Measures:**
+   * - `count` - Total number of scores
+   * - `value` - Score value (for aggregations)
+   *
+   * ### scores-categorical
+   * Query categorical score data. Same dimensions as scores-numeric except uses `stringValue` instead of `value`.
+   *
+   * **Measures:**
+   * - `count` - Total number of scores
+   *
+   * ## High Cardinality Dimensions
+   * The following dimensions cannot be used as grouping dimensions in v2 metrics API as they can cause performance issues.
+   * Use them in filters instead.
+   *
+   * **observations view:**
+   * - `id` - Use traceId filter to narrow down results
+   * - `traceId` - Use traceId filter instead
+   * - `userId` - Use userId filter instead
+   * - `sessionId` - Use sessionId filter instead
+   * - `parentObservationId` - Use parentObservationId filter instead
+   *
+   * **scores-numeric / scores-categorical views:**
+   * - `id` - Use specific filters to narrow down results
+   * - `traceId` - Use traceId filter instead
+   * - `userId` - Use userId filter instead
+   * - `sessionId` - Use sessionId filter instead
+   * - `observationId` - Use observationId filter instead
+   *
+   * ## Aggregations
+   * Available aggregation functions: `sum`, `avg`, `count`, `max`, `min`, `p50`, `p75`, `p90`, `p95`, `p99`, `histogram`
+   *
+   * ## Time Granularities
+   * Available granularities for timeDimension: `auto`, `minute`, `hour`, `day`, `week`, `month`
+   * - `auto` bins the data into approximately 50 buckets based on the time range
+   *
+   * @param {LangfuseAPI.GetMetricsV2Request} request
+   * @param {MetricsV2.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link LangfuseAPI.Error}
+   * @throws {@link LangfuseAPI.UnauthorizedError}
+   * @throws {@link LangfuseAPI.AccessDeniedError}
+   * @throws {@link LangfuseAPI.MethodNotAllowedError}
+   * @throws {@link LangfuseAPI.NotFoundError}
+   *
+   * @example
+   *     await client.metricsV2.metrics({
+   *         query: "query"
+   *     })
+   */
+  metrics(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(
+      this.__metrics(request, requestOptions)
+    );
+  }
+  async __metrics(request, requestOptions) {
+    var _a2, _b, _c, _d, _e, _f, _g, _h;
+    const { query } = request;
+    const _queryParams = {};
+    _queryParams["query"] = query;
+    let _headers = mergeHeaders(
+      (_a2 = this._options) == null ? void 0 : _a2.headers,
+      mergeOnlyDefinedHeaders({
+        Authorization: await this._getAuthorizationHeader(),
+        "X-Langfuse-Sdk-Name": (_c = requestOptions == null ? void 0 : requestOptions.xLangfuseSdkName) != null ? _c : (_b = this._options) == null ? void 0 : _b.xLangfuseSdkName,
+        "X-Langfuse-Sdk-Version": (_e = requestOptions == null ? void 0 : requestOptions.xLangfuseSdkVersion) != null ? _e : (_d = this._options) == null ? void 0 : _d.xLangfuseSdkVersion,
+        "X-Langfuse-Public-Key": (_g = requestOptions == null ? void 0 : requestOptions.xLangfusePublicKey) != null ? _g : (_f = this._options) == null ? void 0 : _f.xLangfusePublicKey
+      }),
+      requestOptions == null ? void 0 : requestOptions.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        (_h = await Supplier.get(this._options.baseUrl)) != null ? _h : await Supplier.get(this._options.environment),
+        "/api/public/v2/metrics"
+      ),
+      method: "GET",
+      headers: _headers,
+      queryParameters: { ..._queryParams, ...requestOptions == null ? void 0 : requestOptions.queryParams },
+      timeoutMs: (requestOptions == null ? void 0 : requestOptions.timeoutInSeconds) != null ? requestOptions.timeoutInSeconds * 1e3 : 6e4,
+      maxRetries: requestOptions == null ? void 0 : requestOptions.maxRetries,
+      abortSignal: requestOptions == null ? void 0 : requestOptions.abortSignal
+    });
+    if (_response.ok) {
+      return {
+        data: _response.body,
+        rawResponse: _response.rawResponse
+      };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new Error2(
+            _response.error.body,
+            _response.rawResponse
+          );
+        case 401:
+          throw new UnauthorizedError(
+            _response.error.body,
+            _response.rawResponse
+          );
+        case 403:
+          throw new AccessDeniedError(
+            _response.error.body,
+            _response.rawResponse
+          );
+        case 405:
+          throw new MethodNotAllowedError(
+            _response.error.body,
+            _response.rawResponse
+          );
+        case 404:
+          throw new NotFoundError(
+            _response.error.body,
+            _response.rawResponse
+          );
+        default:
+          throw new LangfuseAPIError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    switch (_response.error.reason) {
+      case "non-json":
+        throw new LangfuseAPIError({
+          statusCode: _response.error.statusCode,
+          body: _response.error.rawBody,
+          rawResponse: _response.rawResponse
+        });
+      case "timeout":
+        throw new LangfuseAPITimeoutError(
+          "Timeout exceeded when calling GET /api/public/v2/metrics."
+        );
+      case "unknown":
+        throw new LangfuseAPIError({
+          message: _response.error.errorMessage,
+          rawResponse: _response.rawResponse
+        });
+    }
+  }
+  async _getAuthorizationHeader() {
+    const username = await Supplier.get(this._options.username);
+    const password = await Supplier.get(this._options.password);
+    if (username != null && password != null) {
+      return BasicAuth.toAuthorizationHeader({
+        username,
+        password
+      });
+    }
+    return void 0;
+  }
+};
+
 // src/api/api/resources/metrics/client/Client.ts
 var Metrics = class {
   constructor(_options) {
@@ -6261,6 +6495,217 @@ var Models = class {
   }
 };
 
+// src/api/api/resources/observationsV2/client/Client.ts
+var ObservationsV2 = class {
+  constructor(_options) {
+    this._options = _options;
+  }
+  /**
+   * Get a list of observations with cursor-based pagination and flexible field selection.
+   *
+   * ## Cursor-based Pagination
+   * This endpoint uses cursor-based pagination for efficient traversal of large datasets.
+   * The cursor is returned in the response metadata and should be passed in subsequent requests
+   * to retrieve the next page of results.
+   *
+   * ## Field Selection
+   * Use the `fields` parameter to control which observation fields are returned:
+   * - `core` - Always included: id, traceId, startTime, endTime, projectId, parentObservationId, type
+   * - `basic` - name, level, statusMessage, version, environment, bookmarked, public, userId, sessionId
+   * - `time` - completionStartTime, createdAt, updatedAt
+   * - `io` - input, output
+   * - `metadata` - metadata
+   * - `model` - providedModelName, internalModelId, modelParameters
+   * - `usage` - usageDetails, costDetails, totalCost
+   * - `prompt` - promptId, promptName, promptVersion
+   * - `metrics` - latency, timeToFirstToken
+   *
+   * If not specified, `core` and `basic` field groups are returned.
+   *
+   * ## Filters
+   * Multiple filtering options are available via query parameters or the structured `filter` parameter.
+   * When using the `filter` parameter, it takes precedence over individual query parameter filters.
+   *
+   * @param {LangfuseAPI.GetObservationsV2Request} request
+   * @param {ObservationsV2.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link LangfuseAPI.Error}
+   * @throws {@link LangfuseAPI.UnauthorizedError}
+   * @throws {@link LangfuseAPI.AccessDeniedError}
+   * @throws {@link LangfuseAPI.MethodNotAllowedError}
+   * @throws {@link LangfuseAPI.NotFoundError}
+   *
+   * @example
+   *     await client.observationsV2.getMany()
+   */
+  getMany(request = {}, requestOptions) {
+    return HttpResponsePromise.fromPromise(
+      this.__getMany(request, requestOptions)
+    );
+  }
+  async __getMany(request = {}, requestOptions) {
+    var _a2, _b, _c, _d, _e, _f, _g, _h;
+    const {
+      fields,
+      limit,
+      cursor,
+      parseIoAsJson,
+      name,
+      userId,
+      type: type_,
+      traceId,
+      level,
+      parentObservationId,
+      environment,
+      fromStartTime,
+      toStartTime,
+      version,
+      filter
+    } = request;
+    const _queryParams = {};
+    if (fields != null) {
+      _queryParams["fields"] = fields;
+    }
+    if (limit != null) {
+      _queryParams["limit"] = limit.toString();
+    }
+    if (cursor != null) {
+      _queryParams["cursor"] = cursor;
+    }
+    if (parseIoAsJson != null) {
+      _queryParams["parseIoAsJson"] = parseIoAsJson.toString();
+    }
+    if (name != null) {
+      _queryParams["name"] = name;
+    }
+    if (userId != null) {
+      _queryParams["userId"] = userId;
+    }
+    if (type_ != null) {
+      _queryParams["type"] = type_;
+    }
+    if (traceId != null) {
+      _queryParams["traceId"] = traceId;
+    }
+    if (level != null) {
+      _queryParams["level"] = level;
+    }
+    if (parentObservationId != null) {
+      _queryParams["parentObservationId"] = parentObservationId;
+    }
+    if (environment != null) {
+      if (Array.isArray(environment)) {
+        _queryParams["environment"] = environment.map((item) => item);
+      } else {
+        _queryParams["environment"] = environment;
+      }
+    }
+    if (fromStartTime != null) {
+      _queryParams["fromStartTime"] = fromStartTime;
+    }
+    if (toStartTime != null) {
+      _queryParams["toStartTime"] = toStartTime;
+    }
+    if (version != null) {
+      _queryParams["version"] = version;
+    }
+    if (filter != null) {
+      _queryParams["filter"] = filter;
+    }
+    let _headers = mergeHeaders(
+      (_a2 = this._options) == null ? void 0 : _a2.headers,
+      mergeOnlyDefinedHeaders({
+        Authorization: await this._getAuthorizationHeader(),
+        "X-Langfuse-Sdk-Name": (_c = requestOptions == null ? void 0 : requestOptions.xLangfuseSdkName) != null ? _c : (_b = this._options) == null ? void 0 : _b.xLangfuseSdkName,
+        "X-Langfuse-Sdk-Version": (_e = requestOptions == null ? void 0 : requestOptions.xLangfuseSdkVersion) != null ? _e : (_d = this._options) == null ? void 0 : _d.xLangfuseSdkVersion,
+        "X-Langfuse-Public-Key": (_g = requestOptions == null ? void 0 : requestOptions.xLangfusePublicKey) != null ? _g : (_f = this._options) == null ? void 0 : _f.xLangfusePublicKey
+      }),
+      requestOptions == null ? void 0 : requestOptions.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        (_h = await Supplier.get(this._options.baseUrl)) != null ? _h : await Supplier.get(this._options.environment),
+        "/api/public/v2/observations"
+      ),
+      method: "GET",
+      headers: _headers,
+      queryParameters: { ..._queryParams, ...requestOptions == null ? void 0 : requestOptions.queryParams },
+      timeoutMs: (requestOptions == null ? void 0 : requestOptions.timeoutInSeconds) != null ? requestOptions.timeoutInSeconds * 1e3 : 6e4,
+      maxRetries: requestOptions == null ? void 0 : requestOptions.maxRetries,
+      abortSignal: requestOptions == null ? void 0 : requestOptions.abortSignal
+    });
+    if (_response.ok) {
+      return {
+        data: _response.body,
+        rawResponse: _response.rawResponse
+      };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new Error2(
+            _response.error.body,
+            _response.rawResponse
+          );
+        case 401:
+          throw new UnauthorizedError(
+            _response.error.body,
+            _response.rawResponse
+          );
+        case 403:
+          throw new AccessDeniedError(
+            _response.error.body,
+            _response.rawResponse
+          );
+        case 405:
+          throw new MethodNotAllowedError(
+            _response.error.body,
+            _response.rawResponse
+          );
+        case 404:
+          throw new NotFoundError(
+            _response.error.body,
+            _response.rawResponse
+          );
+        default:
+          throw new LangfuseAPIError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    switch (_response.error.reason) {
+      case "non-json":
+        throw new LangfuseAPIError({
+          statusCode: _response.error.statusCode,
+          body: _response.error.rawBody,
+          rawResponse: _response.rawResponse
+        });
+      case "timeout":
+        throw new LangfuseAPITimeoutError(
+          "Timeout exceeded when calling GET /api/public/v2/observations."
+        );
+      case "unknown":
+        throw new LangfuseAPIError({
+          message: _response.error.errorMessage,
+          rawResponse: _response.rawResponse
+        });
+    }
+  }
+  async _getAuthorizationHeader() {
+    const username = await Supplier.get(this._options.username);
+    const password = await Supplier.get(this._options.password);
+    if (username != null && password != null) {
+      return BasicAuth.toAuthorizationHeader({
+        username,
+        password
+      });
+    }
+    return void 0;
+  }
+};
+
 // src/api/api/resources/observations/client/Client.ts
 var Observations = class {
   constructor(_options) {
@@ -11526,6 +11971,10 @@ var LangfuseAPIClient = class {
     var _a2;
     return (_a2 = this._media) != null ? _a2 : this._media = new Media(this._options);
   }
+  get metricsV2() {
+    var _a2;
+    return (_a2 = this._metricsV2) != null ? _a2 : this._metricsV2 = new MetricsV2(this._options);
+  }
   get metrics() {
     var _a2;
     return (_a2 = this._metrics) != null ? _a2 : this._metrics = new Metrics(this._options);
@@ -11534,6 +11983,10 @@ var LangfuseAPIClient = class {
     var _a2;
     return (_a2 = this._models) != null ? _a2 : this._models = new Models(this._options);
   }
+  get observationsV2() {
+    var _a2;
+    return (_a2 = this._observationsV2) != null ? _a2 : this._observationsV2 = new ObservationsV2(this._options);
+  }
   get observations() {
     var _a2;
     return (_a2 = this._observations) != null ? _a2 : this._observations = new Observations(this._options);
@@ -11763,6 +12216,7 @@ var LangfuseOtelContextKeys = {
   metadata: (0, import_api.createContextKey)("langfuse_metadata"),
   version: (0, import_api.createContextKey)("langfuse_version"),
   tags: (0, import_api.createContextKey)("langfuse_tags"),
+  traceName: (0, import_api.createContextKey)("langfuse_trace_name"),
   // Experiments
   experimentId: (0, import_api.createContextKey)("langfuse_experiment_id"),
   experimentName: (0, import_api.createContextKey)("langfuse_experiment_name"),
@@ -11781,7 +12235,15 @@ function propagateAttributes(params, fn) {
   let context = import_api.context.active();
   const span = import_api.trace.getActiveSpan();
   const asBaggage = (_a2 = params.asBaggage) != null ? _a2 : false;
-  const { userId, sessionId, metadata, version, tags, _internalExperiment } = params;
+  const {
+    userId,
+    sessionId,
+    metadata,
+    version,
+    tags,
+    traceName,
+    _internalExperiment
+  } = params;
   if (userId) {
     if (isValidPropagatedString({ value: userId, attributeName: "userId" })) {
       context = setPropagatedAttribute({
@@ -11821,6 +12283,20 @@ function propagateAttributes(params, fn) {
       });
     }
   }
+  if (traceName) {
+    if (isValidPropagatedString({
+      value: traceName,
+      attributeName: "traceName"
+    })) {
+      context = setPropagatedAttribute({
+        key: "traceName",
+        value: traceName,
+        context,
+        span,
+        asBaggage
+      });
+    }
+  }
   if (tags && tags.length > 0) {
     const validTags = tags.filter(
       (tag) => isValidPropagatedString({
@@ -11902,6 +12378,11 @@ function getPropagatedAttributesFromContext(context) {
     const spanKey = getSpanKeyForPropagatedKey("version");
     propagatedAttributes[spanKey] = version;
   }
+  const traceName = context.getValue(LangfuseOtelContextKeys["traceName"]);
+  if (traceName && typeof traceName === "string") {
+    const spanKey = getSpanKeyForPropagatedKey("traceName");
+    propagatedAttributes[spanKey] = traceName;
+  }
   const tags = context.getValue(LangfuseOtelContextKeys["tags"]);
   if (tags && Array.isArray(tags)) {
     const spanKey = getSpanKeyForPropagatedKey("tags");
@@ -12020,6 +12501,8 @@ function getSpanKeyForPropagatedKey(key) {
       return "session.id" /* TRACE_SESSION_ID */;
     case "version":
       return "langfuse.version" /* VERSION */;
+    case "traceName":
+      return "langfuse.trace.name" /* TRACE_NAME */;
     case "metadata":
       return "langfuse.trace.metadata" /* TRACE_METADATA */;
     case "tags":
@@ -12052,6 +12535,8 @@ function getBaggageKeyForPropagatedKey(key) {
       return `${LANGFUSE_BAGGAGE_PREFIX}session_id`;
     case "version":
       return `${LANGFUSE_BAGGAGE_PREFIX}version`;
+    case "traceName":
+      return `${LANGFUSE_BAGGAGE_PREFIX}trace_name`;
     case "metadata":
       return `${LANGFUSE_BAGGAGE_PREFIX}metadata`;
     case "tags":
@@ -12090,6 +12575,8 @@ function getSpanKeyFromBaggageKey(baggageKey) {
       return getSpanKeyForPropagatedKey("sessionId");
     case "version":
       return getSpanKeyForPropagatedKey("version");
+    case "trace_name":
+      return getSpanKeyForPropagatedKey("traceName");
     case "tags":
       return getSpanKeyForPropagatedKey("tags");
     case "experiment_id":
@@ -12171,8 +12658,10 @@ function getSpanKeyFromBaggageKey(baggageKey) {
   logger,
   media,
   metrics,
+  metricsV2,
   models,
   observations,
+  observationsV2,
   opentelemetry,
   organizations,
   projects,