fix Langfuse trace correlation ids

Author: Siri-Ray

apps/daemon/src/langfuse-trace.ts

@@ -55,6 +55,10 @@ const DEFAULT_FETCH_RETRIES = 1;
 const PROMPT_STACK_BLAME_MAX_SECTIONS = 8;
 let missingTelemetrySinkWarned = false;
 
+export function langfuseTraceIdForRun(runId: string): string {
+  return createHash('sha256').update(runId).digest('hex').slice(0, 32);
+}
+
 export interface LangfuseConfig {
   authHeader: string;
   baseUrl: string;
@@ -1540,7 +1544,7 @@ export function buildTracePayload(ctx: ReportContext): unknown[] {
   const performanceDiagnostics = buildPerformanceDiagnostics(ctx);
 
   const success = ctx.run.status === 'succeeded';
-  const traceId = ctx.run.runId;
+  const traceId = langfuseTraceIdForRun(ctx.run.runId);
   const langfuseDelivery =
     ctx.langfuse ??
     deriveLangfuseDeliveryState(ctx.prefs, readRunTelemetrySinkConfig());
@@ -1577,6 +1581,7 @@ export function buildTracePayload(ctx: ReportContext): unknown[] {
     status: ctx.run.status,
     error: safeRunError,
     error_code: ctx.run.errorCode,
+    run_id: ctx.run.runId,
     langfuse_trace_id: traceId,
     ...langfuseDelivery,
     ...(ctx.run.failure ?? {}),
@@ -2478,7 +2483,7 @@ export async function reportRunCompleted(
 // thread `removedReasonCodes` through and emit overwriting "cleared"
 // scores for them; not done here to keep this PR scoped to the bridge.
 export function buildFeedbackPayload(ctx: FeedbackReportContext): unknown[] {
-  const traceId = ctx.runId;
+  const traceId = langfuseTraceIdForRun(ctx.runId);
   const nowIso = new Date().toISOString();
   const batch: unknown[] = [];
 

apps/daemon/src/routes/runs.ts

@@ -45,6 +45,7 @@ import { readVelaLoginStatus } from '../integrations/vela.js';
 import { getDetectedRuntimeVersions } from '../runtimes/detection.js';
 import {
   deriveLangfuseDeliveryState,
+  langfuseTraceIdForRun,
   readTelemetrySinkConfig,
 } from '../langfuse-trace.js';
 import { parseMediaExecutionPolicyInput } from '../media/policy.js';
@@ -1979,7 +1980,7 @@ export function registerRunRoutes(app: Express, ctx: RegisterRunRoutesDeps) {
             ...(typeof run.lastAgentActivityAt === 'number'
               ? { last_progress_age_ms: Math.max(0, analyticsCapturedAt - run.lastAgentActivityAt) }
               : {}),
-            langfuse_trace_id: run.id,
+            langfuse_trace_id: langfuseTraceIdForRun(run.id),
             ...langfuseDeliveryForAnalytics,
             ...(errorCode ? { error_code: errorCode } : {}),
             ...(failure ?? {}),

apps/daemon/src/runtimes/run-terminal-reconciliation.ts

@@ -5,6 +5,7 @@ import { randomUUID } from 'node:crypto';
 import type Database from 'better-sqlite3';
 
 import { appendMessageStatusEvent } from '../db.js';
+import { langfuseTraceIdForRun } from '../langfuse-trace.js';
 import { classifyRunFailure } from '../run-failure-classification.js';
 import { deriveRunErrorCode, runResultFromStatus } from '../run-result.js';
 import { runAskedUserQuestion } from './run-artifacts.js';
@@ -281,7 +282,7 @@ export async function reconcileDurableRunTerminals(
           artifact_count: state.artifactCount ?? 0,
           asked_user_question: runAskedUserQuestion(events),
           total_duration_ms: Math.max(0, state.updatedAt - state.createdAt),
-          langfuse_trace_id: state.id,
+          langfuse_trace_id: langfuseTraceIdForRun(state.id),
           terminal_reconciled: true,
           terminal_recovery_reason: recoveryReason,
           ...(errorCode ? { error_code: errorCode } : {}),

apps/daemon/src/server.ts

@@ -411,6 +411,7 @@ import {
   snapshotAiHtmlVersionsForRun,
 } from './run-html-version-snapshots.js';
 import { reportRunCompletedFromDaemon } from './langfuse-bridge.js';
+import { langfuseTraceIdForRun } from './langfuse-trace.js';
 import { reconcileDurableRunTerminals } from './runtimes/run-terminal-reconciliation.js';
 import { buildPromptStackTelemetry } from './prompt-telemetry.js';
 import { readAnalyticsContext } from './analytics.js';
@@ -1540,7 +1541,7 @@ export function createFinalizedMessageTelemetryReporter({
         project_id: run?.projectId ?? projectId ?? null,
         conversation_id: run?.conversationId ?? conversationId ?? null,
         run_id: runId,
-        langfuse_trace_id: runId,
+        langfuse_trace_id: langfuseTraceIdForRun(runId),
         langfuse_expected: delivery.langfuse_expected,
         langfuse_delivery_status: delivery.langfuse_delivery_status,
         ...(delivery.langfuse_drop_reason

apps/daemon/tests/langfuse-trace.test.ts

@@ -3,6 +3,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import {
   buildFeedbackPayload,
   buildTracePayload,
+  langfuseTraceIdForRun,
   deriveLangfuseDeliveryState,
   isContentToolName,
   isPartialRedactToolName,
@@ -371,9 +372,18 @@ describe('shouldFullyRedactToolPayload (fail-closed)', () => {
   });
 });
 
+describe('langfuseTraceIdForRun', () => {
+  it('derives the Langfuse-compliant trace id deterministically from the Open Design run id', () => {
+    expect(langfuseTraceIdForRun('run-1')).toBe(
+      '4e65d3fbe8ad6535681b021b30785b12',
+    );
+  });
+});
+
 describe('buildTracePayload', () => {
   it('emits a trace with nested agent + generation observations', () => {
     const batch = buildTracePayload(makeCtx());
+    const traceId = langfuseTraceIdForRun('run-1');
     const types = (batch as Array<{ type: string }>).map((e) => e.type);
     expect(types).toEqual([
       'trace-create',
@@ -386,9 +396,13 @@ describe('buildTracePayload', () => {
     const gen = bodyOf(batch, 'generation-create', 'llm');
     const bash = bodyOf(batch, 'span-create', 'tool:Bash');
     const write = bodyOf(batch, 'span-create', 'tool:Write');
+    const trace = (batch[0] as any).body;
+    expect(trace.id).toBe(traceId);
+    expect(trace.metadata.run_id).toBe('run-1');
+    expect(trace.metadata.langfuse_trace_id).toBe(traceId);
     expect(span.id).toBe('run-1-agent');
-    expect(span.traceId).toBe('run-1');
-    expect(gen.traceId).toBe('run-1');
+    expect(span.traceId).toBe(traceId);
+    expect(gen.traceId).toBe(traceId);
     expect(gen.parentObservationId).toBe('run-1-agent');
     expect(bash.parentObservationId).toBe('run-1-agent');
     expect(bash.input).toBeUndefined();
@@ -1278,7 +1292,10 @@ describe('buildTracePayload', () => {
     );
     const metadata = (batch[0] as any).body.metadata;
     expect(metadata.error_code).toBe('RATE_LIMITED');
-    expect(metadata.langfuse_trace_id).toBe('run-rate-limit');
+    expect(metadata.run_id).toBe('run-rate-limit');
+    expect(metadata.langfuse_trace_id).toBe(
+      langfuseTraceIdForRun('run-rate-limit'),
+    );
     expect(metadata.langfuse_expected).toBe(false);
     expect(metadata.langfuse_delivery_status).toBe('not_expected');
     expect(metadata.langfuse_drop_reason).toBe('content_consent_off');
@@ -2528,8 +2545,9 @@ describe('buildFeedbackPayload', () => {
     ) as Array<Record<string, any>>;
     expect(batch).toHaveLength(3);
     const ratingScore = batch[0]!;
+    const traceId = langfuseTraceIdForRun('run-feedback-1');
     expect(ratingScore.type).toBe('score-create');
-    expect(ratingScore.body.traceId).toBe('run-feedback-1');
+    expect(ratingScore.body.traceId).toBe(traceId);
     expect(ratingScore.body.name).toBe('user_rating');
     expect(ratingScore.body.value).toBe(-1);
     expect(ratingScore.body.dataType).toBe('NUMERIC');
@@ -2543,7 +2561,7 @@ describe('buildFeedbackPayload', () => {
       expect(reasonScore.body.name).toBe('user_rating_reason');
       expect(reasonScore.body.dataType).toBe('CATEGORICAL');
       expect(reasonScore.body.comment).toBe('negative');
-      expect(reasonScore.body.traceId).toBe('run-feedback-1');
+      expect(reasonScore.body.traceId).toBe(traceId);
     }
     expect(batch[1]!.body.value).toBe('missed_request');
     expect(batch[2]!.body.value).toBe('weak_visual');
@@ -2611,14 +2629,14 @@ describe('reportRunFeedback', () => {
       'score',
     ]);
     expect(envelope.events[0].data).toMatchObject({
-      id: 'run-feedback-1-rating',
-      traceId: 'run-feedback-1',
+      id: '908d98293a13a7b7811f44a271aa3b5b-rating',
+      traceId: '908d98293a13a7b7811f44a271aa3b5b',
       name: 'user_rating',
       value: 1,
     });
     expect(envelope.events[1].data).toMatchObject({
-      id: 'run-feedback-1-reason-matched_request',
-      traceId: 'run-feedback-1',
+      id: '908d98293a13a7b7811f44a271aa3b5b-reason-matched_request',
+      traceId: '908d98293a13a7b7811f44a271aa3b5b',
       name: 'user_rating_reason',
       value: 'matched_request',
     });

apps/daemon/tests/runtimes/run-terminal-reconciliation.test.ts

@@ -106,6 +106,7 @@ describe('durable run terminal reconciliation', () => {
         failure_stage: 'finalize',
         retryable: true,
         user_action: 'retry',
+        langfuse_trace_id: '109f933ded33d54c42a3faba33818f1e',
         terminal_reconciled: true,
         terminal_recovery_reason: 'daemon_restart',
       }),

apps/daemon/tests/telemetry-message-finalization.test.ts

@@ -453,7 +453,7 @@ describe('Langfuse message finalization gate', () => {
         insertId: 'run-accepted-langfuse-report-terminal_fallback-accepted',
         properties: expect.objectContaining({
           run_id: 'run-accepted',
-          langfuse_trace_id: 'run-accepted',
+          langfuse_trace_id: '7d63aa20a8824b5b21fda43b3a7cfbc9',
           langfuse_expected: true,
           langfuse_delivery_status: 'accepted',
           langfuse_report_result: 'accepted',

specs/current/ai-native-observability-loop.md

@@ -17,7 +17,9 @@ Issue: [#3713](https://github.com/nexu-io/open-design/issues/3713)
 Open Design already reports completed runs to Langfuse and PostHog. The current
 implementation captures useful operational facts:
 
-- trace identity: `run_id == langfuse_trace_id == traceId`;
+- trace identity: `run_id` is the Open Design external identifier, while
+  `langfuse_trace_id == traceId == sha256(run_id).slice(0, 32)`; Langfuse
+  metadata retains `run_id` for external correlation;
 - run status, error code, failure category, failure detail, retryability, and
   user action;
 - timing fields for queue, prompt build, spawn, first token, generation, tool

specs/current/run-reliability-optimization-plan.md

@@ -55,8 +55,10 @@ observability slice:
   `failure_category`, `failure_detail`, `failure_stage`, `retryable`, and
   `user_action`;
 - failed runs preserve the non-empty `error_code` invariant;
-- `langfuse_trace_id` makes PostHog and Langfuse correlate by
-  `run_id == langfuse_trace_id == traceId`;
+- `langfuse_trace_id` makes PostHog and Langfuse correlate by storing the
+  actual Langfuse trace ID, deterministically derived as
+  `sha256(run_id).slice(0, 32) == traceId`; Langfuse metadata retains `run_id`
+  for the reverse join;
 - Langfuse trace metadata mirrors failure, timing, and token/cache fields;
 - `run_finished` emits main-path timing fields for queue, spawn, first token,
   generation, tool aggregate, finalization, and total duration;