improvement(logs): expose trace spans on log detail

Author: TheodoreSpeaks

apps/docs/openapi-v2-logs.json

@@ -291,7 +291,7 @@
       "get": {
         "operationId": "getLog",
         "summary": "Get Log",
-        "description": "Retrieve a single log entry by its ID, including the workflow metadata captured at execution time, the materialized execution data, and the cost summary. Returns `{ data }`.",
+        "description": "Retrieve a single log entry by its ID, including workflow metadata, materialized execution data, a top-level `traceSpans` array, and the cost summary. Returns `{ data }`.",
         "tags": ["Logs"],
         "x-codeSamples": [
           {
@@ -315,7 +315,7 @@
         ],
         "responses": {
           "200": {
-            "description": "The requested log entry with full execution data and cost summary.",
+            "description": "The requested log entry with full execution data, trace spans, and cost summary.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -366,6 +366,7 @@
                         "result": "Hello, world!"
                       }
                     },
+                    "traceSpans": [],
                     "cost": {
                       "total": 0.0032
                     },
@@ -733,7 +734,7 @@
       },
       "LogDetail": {
         "type": "object",
-        "description": "Detailed log entry with full workflow metadata, materialized execution data, and cost summary.",
+        "description": "Detailed log entry with full workflow metadata, materialized execution data, top-level trace spans, and cost summary.",
         "required": [
           "id",
           "workflowId",
@@ -746,6 +747,7 @@
           "files",
           "workflow",
           "executionData",
+          "traceSpans",
           "cost",
           "createdAt"
         ],
@@ -823,6 +825,14 @@
               }
             }
           },
+          "traceSpans": {
+            "type": "array",
+            "description": "Materialized block-level execution trace spans with timing, inputs, and outputs. Empty when the run has no spans.",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
           "cost": {
             "$ref": "#/components/schemas/Cost"
           },

apps/sim/app/api/v2/logs/[id]/route.test.ts

@@ -0,0 +1,122 @@
+/**
+ * @vitest-environment node
+ */
+
+import { dbChainMockFns, resetDbChainMock } from '@sim/testing'
+import { NextRequest } from 'next/server'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const {
+  mockCheckRateLimit,
+  mockResolveWorkspaceAccess,
+  mockLoadActiveFolderPathIndex,
+  mockMaterializeExecutionData,
+} = vi.hoisted(() => ({
+  mockCheckRateLimit: vi.fn(),
+  mockResolveWorkspaceAccess: vi.fn(),
+  mockLoadActiveFolderPathIndex: vi.fn(),
+  mockMaterializeExecutionData: vi.fn(),
+}))
+
+vi.mock('@/app/api/v1/middleware', () => ({
+  checkRateLimit: mockCheckRateLimit,
+  resolveWorkspaceAccess: mockResolveWorkspaceAccess,
+}))
+
+vi.mock('@/app/api/v2/lib/gate', () => ({
+  v2ApiGateError: vi.fn().mockResolvedValue(null),
+}))
+
+vi.mock('@/lib/folders/queries', () => ({
+  loadActiveFolderPathIndex: mockLoadActiveFolderPathIndex,
+}))
+
+vi.mock('@/lib/logs/execution/trace-store', () => ({
+  materializeExecutionData: mockMaterializeExecutionData,
+}))
+
+import { GET } from '@/app/api/v2/logs/[id]/route'
+
+const RATE_LIMIT_OK = {
+  allowed: true,
+  userId: 'user-1',
+  keyType: 'workspace',
+  limit: 100,
+  remaining: 99,
+  resetAt: new Date('2024-01-01T01:00:00Z'),
+}
+
+const LOG_ROW = {
+  id: 'log-1',
+  workflowId: 'workflow-1',
+  workspaceId: 'workspace-1',
+  executionId: 'execution-1',
+  level: 'info',
+  trigger: 'api',
+  startedAt: new Date('2024-01-01T00:00:00Z'),
+  endedAt: new Date('2024-01-01T00:00:01Z'),
+  totalDurationMs: 1000,
+  executionData: { stored: true },
+  costTotal: '0.01',
+  files: null,
+  createdAt: new Date('2024-01-01T00:00:00Z'),
+  workflowName: 'Support Agent',
+  workflowDescription: 'Handles support requests',
+  workflowFolderId: null,
+  workflowUserId: 'user-1',
+  workflowWorkspaceId: 'workspace-1',
+  workflowCreatedAt: new Date('2023-12-01T00:00:00Z'),
+  workflowUpdatedAt: new Date('2023-12-02T00:00:00Z'),
+  workflowArchivedAt: null,
+}
+
+const routeContext = () => ({ params: Promise.resolve({ id: 'log-1' }) })
+
+function callGet() {
+  return GET(new NextRequest('http://localhost:3000/api/v2/logs/log-1'), routeContext())
+}
+
+describe('GET /api/v2/logs/[id]', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    resetDbChainMock()
+    mockCheckRateLimit.mockResolvedValue(RATE_LIMIT_OK)
+    mockResolveWorkspaceAccess.mockResolvedValue(null)
+    mockLoadActiveFolderPathIndex.mockResolvedValue({ pathById: new Map() })
+    dbChainMockFns.limit.mockResolvedValue([LOG_ROW])
+  })
+
+  it('returns materialized trace spans as a first-class log detail field', async () => {
+    const traceSpans = [
+      {
+        id: 'span-1',
+        name: 'Agent',
+        type: 'agent',
+        durationMs: 1000,
+        status: 'success',
+        output: { answer: 'done' },
+      },
+    ]
+    mockMaterializeExecutionData.mockResolvedValue({
+      traceSpans,
+      finalOutput: { answer: 'done' },
+    })
+
+    const response = await callGet()
+    const body = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(body.data.traceSpans).toEqual(traceSpans)
+    expect(body.data.executionData.traceSpans).toEqual(traceSpans)
+  })
+
+  it('returns an empty trace span array when the execution has no spans', async () => {
+    mockMaterializeExecutionData.mockResolvedValue({ finalOutput: { answer: 'done' } })
+
+    const response = await callGet()
+    const body = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(body.data.traceSpans).toEqual([])
+  })
+})

apps/sim/app/api/v2/logs/[id]/route.ts

@@ -5,6 +5,7 @@ import { getErrorMessage } from '@sim/utils/errors'
 import { generateId } from '@sim/utils/id'
 import { eq } from 'drizzle-orm'
 import type { NextRequest } from 'next/server'
+import { traceSpansSchema } from '@/lib/api/contracts/logs'
 import { type V2LogDetail, v2GetLogContract } from '@/lib/api/contracts/v2/logs'
 import { parseRequest } from '@/lib/api/server'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
@@ -80,6 +81,7 @@ export const GET = withRouteHandler(
         log.executionData as Record<string, unknown> | null,
         { workspaceId: log.workspaceId, workflowId: log.workflowId, executionId: log.executionId }
       )
+      const traceSpans = traceSpansSchema.parse(executionData.traceSpans ?? [])
 
       const detail: V2LogDetail = {
         id: log.id,
@@ -105,6 +107,7 @@ export const GET = withRouteHandler(
           deleted: !log.workflowName || log.workflowArchivedAt !== null,
         },
         executionData,
+        traceSpans,
         cost: log.costTotal != null ? { total: Number(log.costTotal) } : null,
         createdAt: log.createdAt.toISOString(),
       }

apps/sim/lib/api/contracts/logs.ts

@@ -161,7 +161,7 @@ const toolCallSchema = z
   })
   .passthrough()
 
-type TraceSpan = {
+export type LogTraceSpan = {
   id: string
   name: string
   type: string
@@ -176,10 +176,10 @@ type TraceSpan = {
   tokens?: number | { total?: number; input?: number; output?: number }
   relativeStartMs?: number
   toolCalls?: Array<z.output<typeof toolCallSchema>>
-  children?: TraceSpan[]
+  children?: LogTraceSpan[]
 }
 
-const traceSpanSchema: z.ZodType<TraceSpan> = z.lazy(() =>
+export const traceSpanSchema: z.ZodType<LogTraceSpan> = z.lazy(() =>
   z
     .object({
       id: z.string(),
@@ -212,11 +212,13 @@ const traceSpanSchema: z.ZodType<TraceSpan> = z.lazy(() =>
     .passthrough()
 )
 
+export const traceSpansSchema = z.array(traceSpanSchema)
+
 const executionDataDetailSchema = z
   .object({
     totalDuration: z.number().nullable().optional(),
     enhanced: z.literal(true).optional(),
-    traceSpans: z.array(traceSpanSchema).optional(),
+    traceSpans: traceSpansSchema.optional(),
     blockExecutions: z.array(blockExecutionSchema).optional(),
     finalOutput: z.unknown().optional(),
     workflowInput: z.unknown().optional(),

apps/sim/lib/api/contracts/v2/logs.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { traceSpansSchema } from '@/lib/api/contracts/logs'
 import { defineRouteContract } from '@/lib/api/contracts/types'
 import {
   v1ExecutionParamsSchema,
@@ -47,7 +48,7 @@ export const v2LogListItemSchema = z.object({
   /** Present only when `details=full` and `includeFinalOutput=true`. */
   finalOutput: z.unknown().optional(),
   /** Present only when `details=full` and `includeTraceSpans=true`. */
-  traceSpans: z.unknown().optional(),
+  traceSpans: traceSpansSchema.optional(),
 })
 
 export type V2LogListItem = z.output<typeof v2LogListItemSchema>
@@ -75,6 +76,8 @@ export const v2LogDetailSchema = z.object({
   }),
   /** Materialized execution trace (block states, trace spans). */
   executionData: z.unknown(),
+  /** Materialized block-level execution trace spans. */
+  traceSpans: traceSpansSchema,
   cost: v2LogCostSchema,
   createdAt: z.string(),
 })