pi-langfuse 1.5.14 → 1.5.16

package/README.md

@@ -136,6 +136,19 @@ defaults shown above. To capture a very large system prompt or big tool
 payloads in full, raise or disable the relevant limit (e.g.
 `PI_LANGFUSE_MAX_STRING_LENGTH=off`).
 
+The REST fallback ingestion is chunked so each request body stays well below
+the Langfuse gateway's payload limit (~4.5MB). These knobs control the chunk
+budget and a hard ceiling for the whole fallback payload:
+
+```bash
+export PI_LANGFUSE_MAX_INGESTION_BATCH_BYTES=4194304  # per-request body budget, default 4MB
+
+export PI_LANGFUSE_MAX_FALLBACK_TOTAL_BYTES=33554432  # whole-payload ceiling, default 32MB
+```
+
+When the accumulated fallback payload exceeds the 32MB ceiling, ingestion is
+skipped with a warning instead of attempting an unrecoverably large upload.
+
 ### Method 3: Persistent `config.json`
 
 Create or update `~/.pi/agent/pi-langfuse/config.json`:

package/README_CN.md

@@ -115,6 +115,34 @@ export LANGFUSE_CAPTURE_SOURCE_METADATA=false
 
 所有被采集的负载在上传前仍会脱敏。扩展会隐藏常见 API key、Bearer token、密码、Cookie、私钥、Langfuse key、GitHub/npm/AWS 风格 token，并对本地绝对路径做 hash。
 
+### 负载上限
+
+上传前会对负载做整形：字符串会被截断，过深或过宽的结构会被裁剪。这些上限让 trace 保持精简，同时保护
+Langfuse 摄取管线。任何一项都可以覆盖（无需重新构建）：
+
+```bash
+export PI_LANGFUSE_MAX_STRING_LENGTH=12000       # 单字符串字符数（system prompt、输入）
+export PI_LANGFUSE_MAX_TOOL_PAYLOAD_LENGTH=24000 # 工具输入/输出字符数
+export PI_LANGFUSE_MAX_DEPTH=6                    # 最大嵌套深度
+export PI_LANGFUSE_MAX_ARRAY_ITEMS=50            # 数组保留的最大元素数
+export PI_LANGFUSE_MAX_OBJECT_KEYS=80            # 对象保留的最大键数
+export PI_LANGFUSE_MAX_PAYLOAD_NODES=2000        # 单个负载的最大总节点数
+```
+
+任意上限设置为 `0`、`off`、`none` 或 `unlimited` 即表示关闭该限制（采集完整值）；未设置或非法值回退到上方默认值。
+若想完整采集很大的 system prompt 或工具负载，可以调高或关闭相关限制（例如 `PI_LANGFUSE_MAX_STRING_LENGTH=off`）。
+
+REST 回退摄取会按字节切分，保证每个请求体都远低于 Langfuse 网关的负载限制（约 4.5MB）。以下变量控制切分预算
+与整个回退负载的硬上限：
+
+```bash
+export PI_LANGFUSE_MAX_INGESTION_BATCH_BYTES=4194304  # 单次请求体预算，默认 4MB
+
+export PI_LANGFUSE_MAX_FALLBACK_TOTAL_BYTES=33554432  # 整体负载上限，默认 32MB
+```
+
+当累积的回退负载超过 32MB 上限时，会跳过摄取并给出告警，而不是尝试一次注定失败的超大上传。
+
 ### 方式 3：持久化 `config.json`
 
 创建或更新 `~/.pi/agent/pi-langfuse/config.json`：

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-langfuse",
-	"version": "1.5.14",
+	"version": "1.5.16",
 	"description": "Langfuse extension for Pi coding agent",
 	"repository": {
 		"type": "git",

package/src/langfuse.ts

@@ -69,6 +69,13 @@ const DEFAULT_SCORE_FLUSH_AT = 10;
 const DEFAULT_SCORE_FLUSH_INTERVAL_MS = 1_000;
 const MAX_SCORE_QUEUE_SIZE = 100_000;
 const MAX_SCORE_BATCH_SIZE = 100;
+// Langfuse gateways (incl. langfuse-dx.wair.ac.cn) reject ingestion bodies above
+// ~4.5MB with HTTP 413. Keep the default chunk budget safely below that limit.
+const DEFAULT_MAX_INGESTION_BATCH_BYTES = 4 * 1024 * 1024;
+// Hard ceiling for the whole REST fallback payload. Above this the fallback is
+// pointless (it would need dozens of requests during a bounded shutdown) and is
+// skipped with a warning.
+const DEFAULT_MAX_FALLBACK_TOTAL_BYTES = 32 * 1024 * 1024;
 
 let shutdownStepTimeoutMs = DEFAULT_SHUTDOWN_STEP_TIMEOUT_MS;
 
@@ -91,6 +98,22 @@ function getScoreShutdownTimeoutMs(): number {
   ) * 1_000;
 }
 
+function getMaxIngestionBatchBytes(): number {
+  return resolvePositiveEnvNumber(
+    "PI_LANGFUSE_MAX_INGESTION_BATCH_BYTES",
+    DEFAULT_MAX_INGESTION_BATCH_BYTES,
+    true,
+  );
+}
+
+function getMaxFallbackTotalBytes(): number {
+  return resolvePositiveEnvNumber(
+    "PI_LANGFUSE_MAX_FALLBACK_TOTAL_BYTES",
+    DEFAULT_MAX_FALLBACK_TOTAL_BYTES,
+    true,
+  );
+}
+
 function delay(ms: number, signal?: AbortSignal) {
   return new Promise<void>((resolve, reject) => {
     if (signal?.aborted) {
@@ -244,6 +267,41 @@ async function ingestBatch(rt: LangfuseRuntime, batch: unknown[], signal: AbortS
   return Array.isArray(responseBody.errors) ? responseBody.errors : [];
 }
 
+function serializedBytes(value: unknown): number {
+  return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+
+/**
+ * Split an ingestion event list into chunks whose serialized request bodies each
+ * stay under `maxBytes`. Each chunk, when wrapped as `{ batch: chunk }`, matches
+ * the measurement exactly because entries are serialized individually and joined
+ * with single commas inside the `{"batch":[...]}` envelope.
+ */
+export function splitIngestionBatch(entries: unknown[], maxBytes: number): unknown[][] {
+  const serialized = entries.map((entry) => JSON.stringify(entry));
+  const envelopeBytes = Buffer.byteLength('{"batch":[]}');
+  const chunks: unknown[][] = [];
+  let chunk: unknown[] = [];
+  let chunkBytes = envelopeBytes;
+
+  for (let index = 0; index < serialized.length; index++) {
+    const entryBytes = Buffer.byteLength(serialized[index], "utf8");
+    const separators = chunk.length > 0 ? 1 : 0;
+    const projectedBytes = chunkBytes + entryBytes + separators;
+    if (chunk.length > 0 && projectedBytes > maxBytes) {
+      chunks.push(chunk);
+      chunk = [];
+      chunkBytes = envelopeBytes;
+    }
+    chunk.push(entries[index]);
+    chunkBytes += entryBytes + (chunk.length > 1 ? 1 : 0);
+  }
+  if (chunk.length > 0) {
+    chunks.push(chunk);
+  }
+  return chunks;
+}
+
 async function flushPendingScores(rt: LangfuseRuntime, signal: AbortSignal): Promise<void> {
   const pendingScores = rt.pendingScores;
   if (!pendingScores || pendingScores.length === 0) {
@@ -400,6 +458,32 @@ function observationType(asType?: string): FallbackObservationType {
   return asType === "generation" ? "GENERATION" : "SPAN";
 }
 
+/**
+ * Langfuse stamps propagated attributes onto a span in
+ * `LangfuseSpanProcessor.onStart(span, parentContext)`, reading them from the
+ * OTel context that was active when the span was created. `propagateAttributes`
+ * only seeds that context for the duration of its callback, so a child created
+ * later — from a separate event handler, outside the callback — is written with
+ * an empty `session.id`.
+ *
+ * That is invisible in the legacy data model, where the session lives on the
+ * trace, but Langfuse v4 stores `session_id` per event row and aggregates a
+ * session with `WHERE session_id != ''`. Unstamped children drop out of
+ * `sumMap(cost_details)` and `sumMap(usage_details)`, which is why such
+ * sessions report their trace count correctly but no cost and no usage at all.
+ *
+ * Re-entering the propagated context for every child keeps the whole tree in
+ * the session. The id is read back off the parent span rather than from
+ * `state.currentSessionId`, so a child created outside an active session scope
+ * still inherits whatever its parent was actually stamped with.
+ */
+const OTEL_SESSION_ID_ATTRIBUTE = "session.id";
+
+function readSessionId(observation: any): string | undefined {
+  const value = observation?.otelSpan?.attributes?.[OTEL_SESSION_ID_ATTRIBUTE];
+  return typeof value === "string" && value ? value : undefined;
+}
+
 function wrapObservation(
   observation: any,
   store: RestFallbackStore,
@@ -459,7 +543,12 @@ function wrapObservation(
       return observation.end();
     },
     startObservation(childName: string, childBody?: Record<string, unknown>, options?: { asType?: string }) {
-      const child = observation.startObservation(childName, childBody, options);
+      const inheritedSessionId = readSessionId(observation) ?? state.currentSessionId ?? undefined;
+      const propagate = runtime?.propagateAttributes;
+      const createChild = () => observation.startObservation(childName, childBody, options);
+      const child = inheritedSessionId && propagate
+        ? propagate({ sessionId: inheritedSessionId.slice(0, 200) }, createChild)
+        : createChild();
       return wrapObservation(child, store, childName, childBody, options?.asType, id);
     },
     setTraceIO(traceBody?: { input?: unknown; output?: unknown }) {
@@ -587,7 +676,7 @@ async function fallbackToRestIngestion(rt: LangfuseRuntime, signal: AbortSignal)
   }
 
   const trace = store.trace;
-  const batch: any[] = [
+  const entries: any[] = [
     {
       type: "trace-create",
       id: randomUUID(),
@@ -627,7 +716,7 @@ async function fallbackToRestIngestion(rt: LangfuseRuntime, signal: AbortSignal)
           }
         : {}),
     };
-    batch.push({
+    entries.push({
       type: observation.type === "GENERATION" ? "generation-create" : "span-create",
       id: randomUUID(),
       timestamp: eventTimestamp(observation),
@@ -635,12 +724,39 @@ async function fallbackToRestIngestion(rt: LangfuseRuntime, signal: AbortSignal)
     });
   }
 
-  const errors = await ingestBatch(rt, batch, signal);
+  const maxTotalBytes = getMaxFallbackTotalBytes();
+  const totalBytes = serializedBytes({ batch: entries });
+  if (totalBytes > maxTotalBytes) {
+    const message = `REST fallback payload is ${(totalBytes / 1024 / 1024).toFixed(1)}MB, above the ${(maxTotalBytes / 1024 / 1024).toFixed(1)}MB ceiling; skipping fallback ingestion`;
+    rememberRuntimeError("REST fallback ingestion", new Error(message));
+    console.warn(`📊 Langfuse: ${message}`);
+    return;
+  }
+
+  const chunks = splitIngestionBatch(entries, getMaxIngestionBatchBytes());
+  const errors: unknown[] = [];
+  for (const chunk of chunks) {
+    if (signal.aborted) {
+      break;
+    }
+    try {
+      errors.push(...(await ingestBatch(rt, chunk, signal)));
+    } catch (error) {
+      if (signal.aborted && isAbortError(error)) {
+        break;
+      }
+      rememberRuntimeError("REST fallback ingestion", error);
+      console.warn("📊 Langfuse: REST fallback ingestion chunk failed", error);
+      errors.push(error instanceof Error ? error.message : String(error));
+    }
+  }
   if (errors.length > 0) {
     rememberRuntimeError("REST fallback ingestion", new Error(JSON.stringify(errors)));
     console.warn("📊 Langfuse: REST fallback ingestion reported errors", errors);
   } else {
-    debugLog(`📊 Langfuse: OTel trace ${trace.id} was not visible; wrote fallback trace via REST ingestion`);
+    debugLog(
+      `📊 Langfuse: OTel trace ${trace.id} was not visible; wrote fallback trace via REST ingestion (${chunks.length} chunk(s))`,
+    );
   }
 }