Skip to content

An AI-powered search engine with a generative UI

fix(tracing): name the preparation stage an unclassified stream failure came from (#978)

Yoshiki Miura2e5677c769f3
diff --git a/lib/streaming/__tests__/create-chat-stream-response.test.ts b/lib/streaming/__tests__/create-chat-stream-response.test.ts
index d806567e..b63b3fbe 100644
--- a/lib/streaming/__tests__/create-chat-stream-response.test.ts
+++ b/lib/streaming/__tests__/create-chat-stream-response.test.ts
@@ -214,6 +214,7 @@ describe('createChatStreamResponse', () => {
statusMessage: describeStreamError(prepareError),
metadata: {
streamErrorPhase: 'preparation',
+ streamErrorStage: 'prepare-messages',
streamErrorShape: { name: 'TypeError' }
}
})
diff --git a/lib/streaming/__tests__/create-ephemeral-chat-stream-response.test.ts b/lib/streaming/__tests__/create-ephemeral-chat-stream-response.test.ts
index b41611f3..99030303 100644
--- a/lib/streaming/__tests__/create-ephemeral-chat-stream-response.test.ts
+++ b/lib/streaming/__tests__/create-ephemeral-chat-stream-response.test.ts
@@ -1,3 +1,4 @@
+import { convertToModelMessages } from 'ai'
import { beforeEach, describe, expect, it, vi } from 'vitest'
const mocks = vi.hoisted(() => ({
@@ -215,6 +216,26 @@ describe('createEphemeralChatStreamResponse', () => {
expect(mocks.forceFlush).toHaveBeenCalledOnce()
})
+ it('records the preparation stage when message conversion fails', async () => {
+ const convertError = new TypeError('private failure detail')
+ vi.mocked(convertToModelMessages).mockRejectedValueOnce(convertError)
+
+ await createEphemeralChatStreamResponse(createConfig())
+
+ expect(mocks.span.update).toHaveBeenCalledWith(
+ expect.objectContaining({
+ level: 'ERROR',
+ statusMessage: describeStreamError(convertError),
+ metadata: {
+ streamErrorPhase: 'preparation',
+ streamErrorStage: 'convert-messages',
+ streamErrorShape: { name: 'TypeError' }
+ }
+ })
+ )
+ expect(mocks.stream).not.toHaveBeenCalled()
+ })
+
it('omits the output when the answer is only whitespace', async () => {
mocks.stream.mockResolvedValue(
createFakeResult({ parts: [{ type: 'text', text: ' \n' }] })
diff --git a/lib/streaming/create-chat-stream-response.ts b/lib/streaming/create-chat-stream-response.ts
index 0262d9f9..270f14c2 100644
--- a/lib/streaming/create-chat-stream-response.ts
+++ b/lib/streaming/create-chat-stream-response.ts
@@ -41,7 +41,8 @@ import { persistStreamResults } from './helpers/persist-stream-results'
import { prepareMessages } from './helpers/prepare-messages'
import {
buildStreamErrorSpanUpdate,
- type StreamErrorPhase
+ type StreamErrorPhase,
+ type StreamErrorStage
} from './helpers/stream-error-diagnostics'
import { stripSpecFromMessages } from './helpers/strip-spec-from-messages'
import type { StreamContext } from './helpers/types'
@@ -103,6 +104,7 @@ export async function createChatStreamResponse(
let streamError: unknown
// The agent stream call is preparation until its first generation starts.
let streamErrorPhase: StreamErrorPhase = 'preparation'
+ let streamErrorStage: StreamErrorStage = 'prepare-messages'
// Sampled where the failure happens: the client can disconnect before the
// span is closed, and by then the signal no longer says whether the user
// cancelled this turn or the failure was the model's own.
@@ -115,11 +117,11 @@ export async function createChatStreamResponse(
const endTracing = async () => {
if (rootSpan) {
const failureUpdate = hasStreamError
- ? buildStreamErrorSpanUpdate(
- streamError,
- streamErrorWasCancelled,
- streamErrorPhase
- )
+ ? buildStreamErrorSpanUpdate(streamError, {
+ requestWasCancelled: streamErrorWasCancelled,
+ phase: streamErrorPhase,
+ stage: streamErrorStage
+ })
: hasEmptyResponse
? {
level: 'ERROR' as const,
@@ -173,6 +175,7 @@ export async function createChatStreamResponse(
}
// Get the researcher agent with search mode
+ streamErrorStage = 'build-agent'
const researchAgent = researcher({
model: context.modelId,
modelConfig: model,
@@ -180,6 +183,7 @@ export async function createChatStreamResponse(
searchMode
})
+ streamErrorStage = 'transform-messages'
const messagesWithNonces = assignDataPartNonces(messagesToModel)
const messagesWithoutSpec = stripSpecFromMessages(messagesWithNonces)
const messagesWithAttachmentSizes = await resolveAttachmentSizes(
@@ -193,10 +197,12 @@ export async function createChatStreamResponse(
)
// Convert to model messages and apply context window management
+ streamErrorStage = 'convert-messages'
let modelMessages = await convertToModelMessages(messagesToConvert, {
convertDataPart
})
+ streamErrorStage = 'truncate-messages'
if (shouldTruncateMessages(modelMessages, model)) {
const maxTokens = getMaxAllowedTokens(model)
const originalCount = modelMessages.length
@@ -210,6 +216,7 @@ export async function createChatStreamResponse(
}
// Start title generation in parallel if it's a new chat
+ streamErrorStage = 'start-title-generation'
if (!initialChat && message) {
const userContent = getTextFromParts(message.parts)
titlePromise = generateChatTitle({
@@ -226,6 +233,7 @@ export async function createChatStreamResponse(
perfLog(
`researchAgent.stream - Start: model=${context.modelId}, searchMode=${searchMode}`
)
+ streamErrorStage = 'start-stream'
// AgentStreamParameters omits onError, but it reaches streamText where only
// stream errors, not recoverable tool errors, invoke it.
const result = await researchAgent.stream({
diff --git a/lib/streaming/create-ephemeral-chat-stream-response.ts b/lib/streaming/create-ephemeral-chat-stream-response.ts
index dfccee59..11f2ba9e 100644
--- a/lib/streaming/create-ephemeral-chat-stream-response.ts
+++ b/lib/streaming/create-ephemeral-chat-stream-response.ts
@@ -35,7 +35,8 @@ import {
import { logAPICallErrorDiagnostics } from './helpers/log-api-call-error'
import {
buildStreamErrorSpanUpdate,
- type StreamErrorPhase
+ type StreamErrorPhase,
+ type StreamErrorStage
} from './helpers/stream-error-diagnostics'
import { stripSpecFromMessages } from './helpers/strip-spec-from-messages'
import { BaseStreamConfig } from './types'
@@ -71,6 +72,7 @@ export async function createEphemeralChatStreamResponse(
let streamError: unknown
// The agent stream call is preparation until its first generation starts.
let streamErrorPhase: StreamErrorPhase = 'preparation'
+ let streamErrorStage: StreamErrorStage = 'transform-messages'
// Sampled where the failure happens: the client can disconnect before the
// span is closed, and by then the signal no longer says whether the user
// cancelled this turn or the failure was the model's own.
@@ -85,11 +87,11 @@ export async function createEphemeralChatStreamResponse(
const endTracing = async () => {
if (rootSpan) {
const failureUpdate = hasStreamError
- ? buildStreamErrorSpanUpdate(
- streamError,
- streamErrorWasCancelled,
- streamErrorPhase
- )
+ ? buildStreamErrorSpanUpdate(streamError, {
+ requestWasCancelled: streamErrorWasCancelled,
+ phase: streamErrorPhase,
+ stage: streamErrorStage
+ })
: hasEmptyResponse
? {
level: 'ERROR' as const,
@@ -118,15 +120,18 @@ export async function createEphemeralChatStreamResponse(
capHistoricalAttachments(compactHistoricalMessages(messagesWithoutSpec))
)
+ streamErrorStage = 'convert-messages'
let modelMessages = await convertToModelMessages(messagesToConvert, {
convertDataPart
})
+ streamErrorStage = 'truncate-messages'
if (shouldTruncateMessages(modelMessages, model)) {
const maxTokens = getMaxAllowedTokens(model)
modelMessages = truncateMessages(modelMessages, maxTokens, model.id)
}
+ streamErrorStage = 'build-agent'
const researchAgent = researcher({
model: `${model.providerId}:${model.id}`,
modelConfig: model,
@@ -135,6 +140,7 @@ export async function createEphemeralChatStreamResponse(
})
const modelId = `${model.providerId}:${model.id}`
+ streamErrorStage = 'start-stream'
// AgentStreamParameters omits onError, but it reaches streamText where only
// stream errors, not recoverable tool errors, invoke it.
const result = await researchAgent.stream({
diff --git a/lib/streaming/helpers/__tests__/stream-error-diagnostics.test.ts b/lib/streaming/helpers/__tests__/stream-error-diagnostics.test.ts
index f2e6e842..d91018b6 100644
--- a/lib/streaming/helpers/__tests__/stream-error-diagnostics.test.ts
+++ b/lib/streaming/helpers/__tests__/stream-error-diagnostics.test.ts
@@ -90,7 +90,13 @@ describe('buildStreamErrorSpanUpdate', () => {
const error = new Error('request stopped')
error.name = 'AbortError'
- expect(buildStreamErrorSpanUpdate(error, true, phase)).toBeNull()
+ expect(
+ buildStreamErrorSpanUpdate(error, {
+ requestWasCancelled: true,
+ phase,
+ stage: 'start-stream'
+ })
+ ).toBeNull()
}
)
@@ -99,11 +105,21 @@ describe('buildStreamErrorSpanUpdate', () => {
phase => {
const update = buildStreamErrorSpanUpdate(
new Error('unclassified failure'),
- false,
- phase
+ {
+ requestWasCancelled: false,
+ phase,
+ stage: 'convert-messages'
+ }
)
expect(update?.metadata.streamErrorPhase).toBe(phase)
+ expect(update?.metadata).toEqual({
+ streamErrorPhase: phase,
+ ...(phase === 'preparation' && {
+ streamErrorStage: 'convert-messages'
+ }),
+ streamErrorShape: { name: 'Error' }
+ })
}
)
@@ -111,20 +127,30 @@ describe('buildStreamErrorSpanUpdate', () => {
const error = new Error('upstream timed out')
error.name = 'AbortError'
- expect(buildStreamErrorSpanUpdate(error, false, 'generation')?.level).toBe(
- 'ERROR'
- )
+ expect(
+ buildStreamErrorSpanUpdate(error, {
+ requestWasCancelled: false,
+ phase: 'generation',
+ stage: 'start-stream'
+ })?.level
+ ).toBe('ERROR')
})
it('records the phase when other diagnostics are absent', () => {
const update = buildStreamErrorSpanUpdate(
new Error('rate limit exceeded'),
- false,
- 'preparation'
+ {
+ requestWasCancelled: false,
+ phase: 'preparation',
+ stage: 'prepare-messages'
+ }
)
expect(update?.level).toBe('ERROR')
expect(update?.statusMessage).toContain('provider_rate_limit')
- expect(update?.metadata).toEqual({ streamErrorPhase: 'preparation' })
+ expect(update?.metadata).toEqual({
+ streamErrorPhase: 'preparation',
+ streamErrorStage: 'prepare-messages'
+ })
})
})
diff --git a/lib/streaming/helpers/stream-error-diagnostics.ts b/lib/streaming/helpers/stream-error-diagnostics.ts
index bb22d87f..abebea5d 100644
--- a/lib/streaming/helpers/stream-error-diagnostics.ts
+++ b/lib/streaming/helpers/stream-error-diagnostics.ts
@@ -6,6 +6,20 @@ import { buildAPICallErrorDiagnostics } from './log-api-call-error'
const MAX_IDENTIFIER_LENGTH = 128
export type StreamErrorPhase = 'preparation' | 'generation'
+export type StreamErrorStage =
+ | 'prepare-messages'
+ | 'build-agent'
+ | 'transform-messages'
+ | 'convert-messages'
+ | 'truncate-messages'
+ | 'start-title-generation'
+ | 'start-stream'
+
+type StreamErrorContext = {
+ requestWasCancelled: boolean
+ phase: StreamErrorPhase
+ stage: StreamErrorStage
+}
function isObject(value: unknown): value is object {
return typeof value === 'object' && value !== null
@@ -95,8 +109,7 @@ export function buildStreamErrorShape(
export function buildStreamErrorSpanUpdate(
error: unknown,
- requestWasCancelled: boolean,
- streamErrorPhase: StreamErrorPhase
+ { requestWasCancelled, phase, stage }: StreamErrorContext
) {
// A cancelled turn is the user walking away, not a failure. The name alone
// does not prove that: an internal timeout aborts its own signal and raises
@@ -111,7 +124,8 @@ export function buildStreamErrorSpanUpdate(
level: 'ERROR' as const,
statusMessage: describeStreamError(error),
metadata: {
- streamErrorPhase,
+ streamErrorPhase: phase,
+ ...(phase === 'preparation' && { streamErrorStage: stage }),
...(apiCallDiagnostics && { apiCallDiagnostics }),
...(streamErrorShape && { streamErrorShape })
}