From 7f24c3fc205648791e69428d8d7704ee61ff79e7 Mon Sep 17 00:00:00 2001 From: Anurag Ojha Date: Sun, 15 Nov 2026 13:55:56 +0530 Subject: [PATCH 1/8] test(observability): cover model spans when onStepFinish is slow The agent loop starts the next model call before the output stream reads the last step-finish. Both tests fail on main: the third call is recorded under the second step with its tokens counted twice, and a failed call gets an extra step. --- .../src/slow-step-callback-tracing.test.ts | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 observability/mastra/src/slow-step-callback-tracing.test.ts diff --git a/observability/mastra/src/slow-step-callback-tracing.test.ts b/observability/mastra/src/slow-step-callback-tracing.test.ts new file mode 100644 index 00000000000..b0317400877 --- /dev/null +++ b/observability/mastra/src/slow-step-callback-tracing.test.ts @@ -0,0 +1,107 @@ +import { setTimeout as sleep } from 'node:timers/promises'; +import { MockLanguageModelV2, convertArrayToReadableStream } from '@internal/ai-sdk-v5/test'; +import { Agent } from '@mastra/core/agent'; +import { Mastra } from '@mastra/core/mastra'; +import { SpanType } from '@mastra/core/observability'; +import { createTool } from '@mastra/core/tools'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import { z } from 'zod/v4'; +import { Observability } from './default'; +import { TestExporter } from './exporters'; + +type Reply = 'tool-call' | 'text' | 'error'; + +function createModel(replies: Reply[]) { + let call = 0; + return new MockLanguageModelV2({ + doStream: async () => { + const reply = replies[call++]; + if (reply === 'error') throw new Error('provider unavailable'); + const usage = { inputTokens: call * 10, outputTokens: 1, totalTokens: call * 10 + 1 }; + return { + rawCall: { rawPrompt: null, rawSettings: {} }, + warnings: [], + stream: convertArrayToReadableStream( + reply === 'tool-call' + ? [ + { type: 'stream-start', warnings: [] }, + { type: 'tool-call', toolCallId: `call-${call}`, toolName: 'lookup', input: '{}' }, + { type: 'finish', finishReason: 'tool-calls', usage }, + ] + : [ + { type: 'stream-start', warnings: [] }, + { type: 'text-start', id: 'text-1' }, + { type: 'text-delta', id: 'text-1', delta: 'done' }, + { type: 'text-end', id: 'text-1' }, + { type: 'finish', finishReason: 'stop', usage }, + ], + ), + }; + }, + }); +} + +describe('model spans when onStepFinish is slow', () => { + let exporter: TestExporter; + let observability: Observability; + + beforeEach(() => { + exporter = new TestExporter(); + }); + + afterEach(async () => { + await observability?.shutdown(); + }); + + async function run(replies: Reply[]) { + const lookup = createTool({ + id: 'lookup', + description: 'Look something up', + inputSchema: z.object({}), + execute: async () => 'found', + }); + observability = new Observability({ + configs: { default: { serviceName: 'slow-step-callback', exporters: [exporter] } }, + }); + const agent = new Agent({ + id: 'slow-callback-agent', + name: 'Slow Callback Agent', + instructions: 'Test', + model: createModel(replies), + tools: { lookup }, + }); + const mastra = new Mastra({ logger: false, agents: { agent }, observability }); + + const output = await mastra.getAgent('agent').stream('question', { + maxSteps: 5, + errorProcessors: [], + onStepFinish: () => sleep(50), + }); + for await (const _ of output.fullStream) { + } + + const steps = exporter.getSpansByType(SpanType.MODEL_STEP); + const inferences = exporter.getSpansByType(SpanType.MODEL_INFERENCE); + return steps.map(step => ({ + step, + inferences: inferences.filter(inference => inference.parentSpanId === step.id), + })); + } + + it('records one step and one inference with its own tokens for each model call', async () => { + const steps = await run(['tool-call', 'tool-call', 'text']); + + expect( + steps.map(({ inferences }) => inferences.map(inference => inference.attributes?.usage?.inputTokens)), + ).toEqual([[10], [20], [30]]); + }); + + it('records a failed model call once', async () => { + const steps = await run(['tool-call', 'error']); + + expect(steps.map(({ step, inferences }) => [Boolean(step.errorInfo), inferences.length])).toEqual([ + [false, 1], + [true, 1], + ]); + }); +}); From 8f92b3dec803213bca035c2e93697b6065459c93 Mon Sep 17 00:00:00 2001 From: Anurag Ojha Date: Sun, 15 Nov 2026 13:55:58 +0530 Subject: [PATCH 2/8] fix(core): trace agent stream chunks when the loop writes them The span tracker got step events from the agent loop and from the output stream. The stream reads chunks later when onStepFinish is slow, so the two sources ran out of order. Record each chunk at the loop's enqueue point instead, like durable agents do. Trackers without recordChunk keep the old path. --- .changeset/yellow-berries-cut.md | 5 +++++ packages/core/src/loop/loop.ts | 6 ++++-- packages/core/src/loop/workflows/stream.ts | 3 ++- packages/core/src/observability/types/tracing.ts | 2 +- 4 files changed, 12 insertions(+), 4 deletions(-) create mode 100644 .changeset/yellow-berries-cut.md diff --git a/.changeset/yellow-berries-cut.md b/.changeset/yellow-berries-cut.md new file mode 100644 index 00000000000..7b2b9e7e398 --- /dev/null +++ b/.changeset/yellow-berries-cut.md @@ -0,0 +1,5 @@ +--- +'@mastra/core': patch +--- + +Fixed extra model step and model inference spans in traces when `onStepFinish` takes time to finish. Each model call now has one step span and one inference span with its own token usage, so exporters such as PostHog and Langfuse no longer count a model call twice. diff --git a/packages/core/src/loop/loop.ts b/packages/core/src/loop/loop.ts index 1417df64995..e2d639f1d0f 100644 --- a/packages/core/src/loop/loop.ts +++ b/packages/core/src/loop/loop.ts @@ -152,8 +152,10 @@ export function loop({ }, }); - // Apply chunk tracing transform to track MODEL_STEP and MODEL_CHUNK spans - const stream = rest.modelSpanTracker?.wrapStream(baseStream) ?? baseStream; + // Trackers without recordChunk trace chunks as the consumer reads them. + const stream = rest.modelSpanTracker?.recordChunk + ? baseStream + : (rest.modelSpanTracker?.wrapStream(baseStream) ?? baseStream); // Build observability context from modelSpanTracker if tracing context is available const observabilityContext = createObservabilityContext(rest.modelSpanTracker?.getTracingContext()); diff --git a/packages/core/src/loop/workflows/stream.ts b/packages/core/src/loop/workflows/stream.ts index 0e3b2594d32..811c81b24fa 100644 --- a/packages/core/src/loop/workflows/stream.ts +++ b/packages/core/src/loop/workflows/stream.ts @@ -57,7 +57,7 @@ export function workflowLoopStream>) => { let totalTimeoutSignal: AbortSignal | undefined; - // Stamp chunks when the loop produces them; consumers may read them much later. + // Stamp and trace chunks when the loop produces them; consumers may read them much later. const controller: ReadableStreamDefaultController> = { enqueue: chunk => { // The total deadline ends the run with a timeout error after the tool grace window. @@ -71,6 +71,7 @@ export function workflowLoopStream(stream: T): T; /** @internal Record a chunk after the runtime has applied output processors. */ - recordChunk?(chunk: ChunkType): void; + recordChunk?(chunk: ChunkType): void; startStep(payload?: StepStartPayload): void; updateStep?(payload?: StepStartPayload): void; From cf10ebdf71831208f43ec3640ca43e419570e51a Mon Sep 17 00:00:00 2001 From: Anurag Ojha Date: Tue, 17 Nov 2026 13:05:06 +0530 Subject: [PATCH 3/8] fix(core): trace a chunk only after the stream accepts it A background tool result can arrive after the run's stream has closed. The loop traced that chunk before the closed stream rejected it, so the trace got a model step and a model inference span that never ended. Enqueue the chunk first, so a rejected chunk is not traced. --- packages/core/src/loop/workflows/stream.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/core/src/loop/workflows/stream.ts b/packages/core/src/loop/workflows/stream.ts index 811c81b24fa..551a3829a31 100644 --- a/packages/core/src/loop/workflows/stream.ts +++ b/packages/core/src/loop/workflows/stream.ts @@ -71,8 +71,8 @@ export function workflowLoopStream { From 4985b71a20bf569a55dc1fcf1b461a5d8d2e4362 Mon Sep 17 00:00:00 2001 From: "mastra-platform[bot]" <284800079+mastra-platform[bot]@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:51:12 -0800 Subject: [PATCH 4/8] fix(playground-ui): run CodeDiff lines flush under the file header (#30668) > Opened by @damien-schneider ## What When the Factory changes panel stacks file diffs, a blank band shows below each file's last line and above the next file's first line. `@pierre/diffs` adds 8px of padding above the code, and by default it always keeps room for a horizontal scrollbar under it. The design system's `CodeDiff` places that code on the card fill, so both show up as empty strips. When a `CodeDiff` has a file header, it now sets a `data-header` attribute. A matching rule in `code-diff.css`, next to the other `--diffs-*` overrides, sets two of pierre's variables. pierre doesn't set these itself, so the values reach the diff's shadow DOM: - `--diffs-gap-block: 0px`: no padding above the first line or below the last, and the "N unmodified lines" separators between hunks sit flush too. - `--diffs-overflow-override: auto`: the horizontal scrollbar only takes room when lines overflow. Platforms with overlay scrollbars, like macOS, reserve no room for it. A `CodeDiff` without a header keeps its padding. That case is the standalone diff in the observation detail view. ## Test plan - [x] `vitest run src/ds/components/CodeDiff`: 6/6 pass - [x] `oxlint` and `prettier --check` pass on the changed files - [x] Storybook `Elements/CodeDiff` in Chromium with real scrollbars. File list: 0px top and bottom padding and no scrollbar strip, where before there was 8px of padding plus a 15px strip under every file. A multi-hunk diff with overflowing lines: flush lines and separators, with a scrollbar only on the diff that overflows. A diff without a header keeps its 8px padding. - [ ] Full `tsc` for `playground-ui` didn't finish in the sandbox. The TSX change only adds a `data-header` attribute. ELI5: When a code diff has a file name bar on top, the diff used to have empty gaps. This change removes the gap under the bar. It also makes the horizontal scrollbar appear only when the code is too wide. ## Summary This change adjusts `CodeDiff` layout when a file header is present. The outer container gets a `data-header` attribute. A CSS rule for that attribute sets the block gap to `0px` and sets overflow to `auto`. Diffs without a header are unchanged. A patch changeset for `@mastra/playground-ui` documents the change. ## Changes - `packages/playground-ui/src/ds/components/CodeDiff/code-diff.tsx` (+5/-1): The root `div` sets `data-header` to an empty string when `header` is provided. It sets the attribute to `undefined` otherwise. The `ref` and class names are unchanged. - `packages/playground-ui/src/ds/components/CodeDiff/code-diff.css` (+7): Adds a comment and a `.code-diff[data-header]` rule. The rule sets `--diffs-gap-block: 0px` and `--diffs-overflow-override: auto`. - `.changeset/flush-diff-lines.md` (+5): Adds a patch entry for `@mastra/playground-ui`. It states that headered diffs have no blank band above the first line or below the last. It also states that the horizontal scrollbar takes space only when lines overflow. ## Notes - The diff does not set `padding-block: 0`, `scrollbar-width: thin`, or any shadow-root selector. The PR objectives describe these, but the diff does not contain them. This summary follows the diff. - No exported or public declarations changed. - Totals: 3 files changed, 17 lines added, 1 line removed. - The PR objectives report that `vitest run src/ds/components/CodeDiff` passed (6/6) and that `oxlint` and `prettier --check` passed. They also report that full `tsc` did not finish. These results come from the PR description. They were not re-run here. --------- Co-authored-by: mastra-platform[bot] Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com> --- .changeset/flush-diff-lines.md | 5 +++++ .../playground-ui/src/ds/components/CodeDiff/code-diff.css | 7 +++++++ .../playground-ui/src/ds/components/CodeDiff/code-diff.tsx | 6 +++++- 3 files changed, 17 insertions(+), 1 deletion(-) create mode 100644 .changeset/flush-diff-lines.md diff --git a/.changeset/flush-diff-lines.md b/.changeset/flush-diff-lines.md new file mode 100644 index 00000000000..c4411d48629 --- /dev/null +++ b/.changeset/flush-diff-lines.md @@ -0,0 +1,5 @@ +--- +'@mastra/playground-ui': patch +--- + +`CodeDiff` with a file header now shows its lines flush against the header and the card's bottom edge, so stacked diffs in a `CodeDiffList` read like a pull request with no blank band above the first line or below the last. The horizontal scrollbar only takes room when lines overflow, and none on platforms with overlay scrollbars. Diffs without a header keep their padding. diff --git a/packages/playground-ui/src/ds/components/CodeDiff/code-diff.css b/packages/playground-ui/src/ds/components/CodeDiff/code-diff.css index f7ddb710e59..e1a83211f0d 100644 --- a/packages/playground-ui/src/ds/components/CodeDiff/code-diff.css +++ b/packages/playground-ui/src/ds/components/CodeDiff/code-diff.css @@ -12,3 +12,10 @@ --diffs-bg-separator-override: var(--muted); --diffs-fg-number-override: var(--placeholder); } + +/* Under a file header the lines run flush from the header to the card's bottom edge, like a pull request. + The horizontal scrollbar only takes room when lines overflow. */ +.code-diff[data-header] { + --diffs-gap-block: 0px; + --diffs-overflow-override: auto; +} diff --git a/packages/playground-ui/src/ds/components/CodeDiff/code-diff.tsx b/packages/playground-ui/src/ds/components/CodeDiff/code-diff.tsx index 69ebe8f8d51..f469a21ce05 100644 --- a/packages/playground-ui/src/ds/components/CodeDiff/code-diff.tsx +++ b/packages/playground-ui/src/ds/components/CodeDiff/code-diff.tsx @@ -97,7 +97,11 @@ export function CodeDiff({ className, layout, overflow = 'wrap', header, ref, .. }; return ( -
+
{header ? ( Date: Mon, 16 Nov 2026 23:52:44 -0800 Subject: [PATCH 5/8] fix(factory-ui): show notification summaries as a readable inline line (#30662) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit > Opened by @damien-schneider ## Description When pending notifications are rolled into a summary, Factory chat showed them as a row labeled "Notification summary" followed by the raw summary text, e.g. `factory-session: 1`. The row also used the padded, caption-sized activity style. It sat between inline signal lines like "Factory sessions snapshot", so it looked out of place and read like debug output. The summary now renders like those inline lines and is built from the structured fields every summary carries (`pending`, `bySource`, `byPriority`): - **Label and count:** "Notifications" followed by "1 new" / "4 new". - **Sources:** one badge per source. With a single source it shows just the name (`Factory session`). With several, each badge has its count (`GitHub 3`, `My webhook 1`). - **Source names:** a small map gives readable names for known sources (`factory-session`, `github`, `gitlab`, `linear`, `jira`, `slack`). Any other source shows its id in sentence case (`my-webhook` → "My webhook"), so new sources need no code change. - **Priority:** the bell is tinted only when something high or urgent is pending. - **Fallback:** a summary with no counts shows its original text. The change is limited to `NotificationSummaryCard` in factory-ui. The shared `NotificationActivity` component and individual notification rows are unchanged. ## Test plan - `TranscriptNotifications.msw.test.tsx` covers a single Factory session summary (no raw `factory-session: 1` text), several sources including an unmapped one, and the fallback with no counts. - `pnpm typecheck`, oxlint and prettier pass on factory-ui. ELI5: When many alerts are waiting, the app used to show a plain block of raw text. Now it shows one short line that says how many are new and where they came from. ## Summary This PR changes how `NotificationSummaryCard` renders notification summaries in factory-ui. The card now shows an inline activity line instead of a padded row with raw summary text. ### Changes **`TranscriptNotifications.tsx`** (+47/-2) - Replaces the `NotificationActivity` call in `NotificationSummaryCard` with an `Activity` line. The line contains a bell icon, a "Notifications" label, and a status label. - Shows `" new"` when `pending > 0` and at least one source has a count above zero. Otherwise, shows `entry.message`. - Adds one `Badge` per source with a positive count. With one source, the badge shows the source name. With several sources, the badge shows the name and count, for example `GitHub 3`. - Tints the bell only when `byPriority` has an `urgent` or `high` count above zero. - Adds a `NOTIFICATION_SOURCE_NAMES` map for `factory-session`, `github`, `gitlab`, `linear`, `jira`, and `slack`. - Adds exported `notificationSourceName(source: string): string`. It returns the mapped name for a known source. For an unknown source, it replaces `-` and `_` with spaces and applies sentence case. An empty ID is returned unchanged. - Adds an own-key check when it looks up source names. IDs such as `__proto__` do not match inherited object properties. These IDs use the sentence-case fallback, so the component does not render an invalid React child. - Imports the `Activity`, `ActivityHeader`, `ActivityIcon`, and `ActivityLabel` primitives and `Badge`. **`TranscriptNotifications.msw.test.tsx`** (+67/-9) - Replaces the test that checked for the summary under its own label. - Adds a test for one pending `factory-session` notification. It checks for `Notifications`, `1 new`, and `Factory session`. It checks that the raw `factory-session: 1` text and any button are absent. - Adds a test for multiple sources, including an unnamed source. It checks the total and the per-source counts. - Adds a test for a summary with no counts. It checks that the summary message is shown. - Adds a test that a source named `__proto__` displays as `Proto`. ### Scope - The shared `NotificationActivity` component is not changed by this diff. - Individual notification rows are not changed by this diff. - The diff touches only these two files under `mastracode/factory-ui/`. ### Verification - The PR author reports that `pnpm typecheck`, oxlint, and prettier pass on factory-ui. These results were not re-run for this summary. - The new tests exist in the diff. Their pass or fail status was not checked. --------- Co-authored-by: mastra-platform[bot] Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com> --- .../components/TranscriptNotifications.tsx | 49 +++++++++++- .../TranscriptNotifications.msw.test.tsx | 76 ++++++++++++++++--- 2 files changed, 114 insertions(+), 11 deletions(-) diff --git a/mastracode/factory-ui/src/ui/domains/chat/components/TranscriptNotifications.tsx b/mastracode/factory-ui/src/ui/domains/chat/components/TranscriptNotifications.tsx index 4e3daecbbb1..3797602c7b4 100644 --- a/mastracode/factory-ui/src/ui/domains/chat/components/TranscriptNotifications.tsx +++ b/mastracode/factory-ui/src/ui/domains/chat/components/TranscriptNotifications.tsx @@ -1,4 +1,11 @@ -import { NotificationActivity } from '@mastra/playground-ui/components/ai/activity'; +import { + Activity, + ActivityHeader, + ActivityIcon, + ActivityLabel, + NotificationActivity, +} from '@mastra/playground-ui/components/ai/activity'; +import { Badge } from '@mastra/playground-ui/components/Badge'; import { Button } from '@mastra/playground-ui/components/Button'; import { Txt } from '@mastra/playground-ui/components/Txt'; import { cn } from '@mastra/playground-ui/utils/cn'; @@ -162,8 +169,46 @@ function WaitingSessionActions({ factoryId, waiting }: { factoryId: string; wait ); } +const NOTIFICATION_SOURCE_NAMES: Record = { + 'factory-session': 'Factory session', + github: 'GitHub', + gitlab: 'GitLab', + linear: 'Linear', + jira: 'Jira', + slack: 'Slack', +}; + +/** A readable name for a notification source; unknown sources fall back to their id in sentence case. */ +export function notificationSourceName(source: string): string { + if (Object.hasOwn(NOTIFICATION_SOURCE_NAMES, source)) return NOTIFICATION_SOURCE_NAMES[source]; + const words = source.replace(/[-_]+/g, ' ').trim(); + return words ? words.charAt(0).toUpperCase() + words.slice(1) : source; +} + export function NotificationSummaryCard({ entry }: { entry: NotificationSummaryEntry }) { - return ; + const sources = Object.entries(entry.bySource).filter(([, count]) => count > 0); + const counted = entry.pending > 0 && sources.length > 0; + const urgent = (entry.byPriority.urgent ?? 0) > 0 || (entry.byPriority.high ?? 0) > 0; + + return ( + + + + + + Notifications + + {counted ? `${entry.pending} new` : entry.message} + + {counted && + sources.map(([source, count]) => ( + + {sources.length > 1 ? `${notificationSourceName(source)} ${count}` : notificationSourceName(source)} + + ))} + + + ); } export function notificationMetadata(entry: MessageEntry): Array { diff --git a/mastracode/factory-ui/src/ui/domains/chat/components/__tests__/TranscriptNotifications.msw.test.tsx b/mastracode/factory-ui/src/ui/domains/chat/components/__tests__/TranscriptNotifications.msw.test.tsx index f84f8327594..7196cd9da9e 100644 --- a/mastracode/factory-ui/src/ui/domains/chat/components/__tests__/TranscriptNotifications.msw.test.tsx +++ b/mastracode/factory-ui/src/ui/domains/chat/components/__tests__/TranscriptNotifications.msw.test.tsx @@ -56,22 +56,80 @@ describe('Transcript notifications', () => { }); describe('when pending notifications are summarized', () => { - it('puts the summary in the transcript under its own label', () => { + it('says how many are new and names their source', () => { renderEntries([ { kind: 'notification_summary', id: 'summary', - message: '2 pull requests and 1 issue need attention.', - pending: 3, - bySource: { github: 3 }, - byPriority: { high: 3 }, - notificationIds: ['1', '2', '3'], + message: 'factory-session: 1', + pending: 1, + bySource: { 'factory-session': 1 }, + byPriority: { low: 1 }, + notificationIds: ['1'], }, ]); - const notification = within(screen.getByRole('group', { name: 'Notification: Notification summary' })); - expect(notification.getByText('2 pull requests and 1 issue need attention.')).toBeVisible(); - expect(notification.queryByRole('button')).not.toBeInTheDocument(); + const summary = screen.getByRole('group', { name: 'Notification summary' }); + expect(summary).toHaveAttribute('data-notification-state', 'summary'); + expect(within(summary).getByText('Notifications')).toBeVisible(); + expect(within(summary).getByText('1 new')).toBeVisible(); + expect(within(summary).getByText('Factory session')).toBeVisible(); + expect(within(summary).queryByText('factory-session: 1')).not.toBeInTheDocument(); + expect(within(summary).queryByRole('button')).not.toBeInTheDocument(); + }); + + it('counts each source when several are pending, including ones it has no name for', () => { + renderEntries([ + { + kind: 'notification_summary', + id: 'summary', + message: 'github: 3, my-webhook: 1', + pending: 4, + bySource: { github: 3, 'my-webhook': 1 }, + byPriority: { high: 3, low: 1 }, + notificationIds: ['1', '2', '3', '4'], + }, + ]); + + const summary = within(screen.getByRole('group', { name: 'Notification summary' })); + expect(summary.getByText('4 new')).toBeVisible(); + expect(summary.getByText('GitHub 3')).toBeVisible(); + expect(summary.getByText('My webhook 1')).toBeVisible(); + }); + + it('falls back to the summary text when it carries no counts', () => { + renderEntries([ + { + kind: 'notification_summary', + id: 'summary', + message: 'No pending notifications', + pending: 0, + bySource: {}, + byPriority: {}, + notificationIds: [], + }, + ]); + + const summary = within(screen.getByRole('group', { name: 'Notification summary' })); + expect(summary.getByText('No pending notifications')).toBeVisible(); + }); + + it('names a source that collides with a built-in object key from its id', () => { + renderEntries([ + { + kind: 'notification_summary', + id: 'summary', + message: '__proto__: 1', + pending: 1, + bySource: JSON.parse('{"__proto__": 1}') as Record, + byPriority: { low: 1 }, + notificationIds: ['1'], + }, + ]); + + const summary = within(screen.getByRole('group', { name: 'Notification summary' })); + expect(summary.getByText('1 new')).toBeVisible(); + expect(summary.getByText('Proto')).toBeVisible(); }); }); }); From cf6f1b04595c8ab3f899cdbbd615d92c3a68e04b Mon Sep 17 00:00:00 2001 From: "mastra-platform[bot]" <284800079+mastra-platform[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 08:58:25 +0100 Subject: [PATCH 6/8] docs(otel): sort vendors alphabetically on OpenTelemetry integration page (#30670) --- .../observability/opentelemetry.mdx | 516 +++++++++--------- 1 file changed, 258 insertions(+), 258 deletions(-) diff --git a/docs/src/content/en/integrations/observability/opentelemetry.mdx b/docs/src/content/en/integrations/observability/opentelemetry.mdx index d2527be1ca8..3c72c571eda 100644 --- a/docs/src/content/en/integrations/observability/opentelemetry.mdx +++ b/docs/src/content/en/integrations/observability/opentelemetry.mdx @@ -13,13 +13,13 @@ Mastra supports OpenTelemetry (OTEL) through an exporter for sending traces and ## Exporter -The OpenTelemetry exporter sends your traces and logs using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, Sentry, SigNoz, MLflow, Latitude, Dash0, Traceloop, Laminar, telemetry.dev, Sazabi, Agnost AI, and more. +The OpenTelemetry exporter sends your traces and logs using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Agnost AI, Dash0, Datadog, Laminar, Latitude, MLflow, New Relic, Sazabi, Sentry, SigNoz, telemetry.dev, Traceloop, and more. ### Installation Each provider requires specific protocol packages. Install the base exporter plus the protocol package for your provider: -#### For HTTP/Protobuf providers (SigNoz, New Relic, Sentry, Laminar, MLflow, Latitude, telemetry.dev, Agnost AI) +#### For HTTP/Protobuf providers (Agnost AI, Laminar, Latitude, MLflow, New Relic, Sentry, SigNoz, telemetry.dev) ```bash npm2yarn npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto @@ -31,7 +31,7 @@ npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-prot npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js ``` -#### For HTTP/JSON providers (Traceloop, Sazabi) +#### For HTTP/JSON providers (Sazabi, Traceloop) ```bash npm2yarn npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http @@ -44,129 +44,13 @@ All providers support zero-config setup via environment variables. Set the appro | Provider | Environment Variables | | - | - | | Dash0 | `DASH0_API_KEY` (required), `DASH0_ENDPOINT` (required), `DASH0_DATASET` (optional) | -| SigNoz | `SIGNOZ_API_KEY` (required), `SIGNOZ_REGION` (optional), `SIGNOZ_ENDPOINT` (optional) | -| New Relic | `NEW_RELIC_LICENSE_KEY` (required), `NEW_RELIC_ENDPOINT` (optional) | -| Traceloop | `TRACELOOP_API_KEY` (required), `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT` (optional) | | Laminar | `LMNR_PROJECT_API_KEY` (required), `LAMINAR_ENDPOINT` (optional) | +| New Relic | `NEW_RELIC_LICENSE_KEY` (required), `NEW_RELIC_ENDPOINT` (optional) | +| SigNoz | `SIGNOZ_API_KEY` (required), `SIGNOZ_REGION` (optional), `SIGNOZ_ENDPOINT` (optional) | +| Traceloop | `TRACELOOP_API_KEY` (required), `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT` (optional) | ### Provider configurations -#### Sentry - -[Sentry](https://sentry.io/) accepts OpenTelemetry traces and logs through its OTLP endpoints. In Sentry, open [**Project Settings** > **Client Keys (DSN)**](https://sentry.io/settings/projects/) and copy the OTLP traces endpoint and authentication header. Add both values to your environment: - -```bash title=".env" -SENTRY_OTLP_ENDPOINT=https://o000000.ingest.sentry.io/api/0000000/integration/otlp/v1/traces -SENTRY_OTLP_AUTH_HEADER="sentry sentry_key=..." -``` - -Use the `custom` provider with HTTP/Protobuf: - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - custom: { - endpoint: process.env.SENTRY_OTLP_ENDPOINT!, - protocol: 'http/protobuf', - headers: { - 'x-sentry-auth': process.env.SENTRY_OTLP_AUTH_HEADER!, - }, - }, - }, -}) -``` - -See [Sentry's OTLP documentation](https://docs.sentry.io/concepts/otlp/) for endpoint setup, supported signals, and current ingestion limits. - -Choose an exporter based on your setup: - -- `OtelExporter`: Sends vendor-neutral traces and logs over OTLP. Use it with an existing OpenTelemetry pipeline or when you want backend portability. -- [`SentryExporter`](/integrations/observability/sentry): Uses the Sentry SDK to map Mastra span types to Sentry operations, add AI monitoring attributes, and capture span errors as Sentry issues. - -#### MLflow - -[MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) supports native Mastra tracing through its OTLP endpoint at `/v1/traces`. Use the `custom` provider with HTTP/Protobuf and include the experiment header so traces are routed to the correct MLflow experiment: - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - custom: { - endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`, - protocol: 'http/protobuf', - headers: { - 'x-mlflow-experiment-id': process.env.MLFLOW_EXPERIMENT_ID, - }, - }, - }, -}) -``` - -#### Latitude - -[Latitude](https://latitude.so) is an open-source LLM observability and evaluation platform that ingests OTLP traces. Use the `custom` provider with HTTP/Protobuf, pointing at Latitude's ingestion endpoint and authenticating with your API key and project slug: - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - custom: { - endpoint: 'https://ingest.latitude.so/v1/traces', - protocol: 'http/protobuf', - headers: { - Authorization: `Bearer ${process.env.LATITUDE_API_KEY}`, - 'X-Latitude-Project': process.env.LATITUDE_PROJECT, - }, - }, - }, -}) -``` - -Sign up at [console.latitude.so](https://console.latitude.so/login), or self-host and point the endpoint at your own ingestion host. - -#### telemetry.dev - -[telemetry.dev](https://telemetry.dev) ingests OTLP/HTTP protobuf traces and normalizes OpenTelemetry GenAI semantic conventions into model, provider, token, latency, and cost fields. Use the `custom` provider with your project API key: - -```bash title=".env" -TELEMETRY_DEV_API_KEY=td_live_... -``` - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - custom: { - endpoint: 'https://ingest.telemetry.dev/v1/traces', - protocol: 'http/protobuf', - headers: { - Authorization: `Bearer ${process.env.TELEMETRY_DEV_API_KEY}`, - }, - }, - }, -}) -``` - -#### Sazabi - -[Sazabi](https://sazabi.com) is an AI-native observability platform that ingests OTLP traces. In Sazabi, add a Mastra log source and copy its intake URL. The URL carries your project key, so no auth header is needed: - -```bash title=".env" -SAZABI_INTAKE_URL=https://... -``` - -Use the `custom` provider with HTTP/JSON: - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - custom: { - endpoint: process.env.SAZABI_INTAKE_URL!, - protocol: 'http/json', - }, - }, -}) -``` - -See [Sazabi's Mastra guide](https://docs.sazabi.com/catalogs/log-sources/send-to-an-endpoint/mastra) for the full setup. - #### Agnost AI [Agnost AI](https://agnost.ai) ingests OTLP/HTTP protobuf traces and groups them into conversations and users for production agent monitoring. Use the `custom` provider with your organization ID: @@ -265,138 +149,6 @@ Get your Dash0 endpoint from your dashboard. It should be in the format `ingress ::: -#### `SigNoz` - -[SigNoz](https://signoz.io/) is an open-source APM alternative with built-in Tracing support. - -##### Zero-Config Setup - -```bash title=".env" -# Required -SIGNOZ_API_KEY=your-api-key - -# Optional -SIGNOZ_REGION=us # 'us' | 'eu' | 'in' -SIGNOZ_ENDPOINT=https://my-signoz.example.com # For self-hosted -``` - -```typescript title="src/mastra/index.ts" -new OtelExporter({ provider: { signoz: {} } }) -``` - -##### Explicit Configuration - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - signoz: { - apiKey: process.env.SIGNOZ_API_KEY, - region: 'us', // 'us' | 'eu' | 'in' - // endpoint: 'https://my-signoz.example.com', // For self-hosted - }, - }, -}) -``` - -#### New Relic - -[New Relic](https://newrelic.com/) provides complete observability with AI monitoring capabilities. - -##### Zero-Config Setup - -```bash title=".env" -# Required -NEW_RELIC_LICENSE_KEY=your-license-key - -# Optional -NEW_RELIC_ENDPOINT=https://otlp.eu01.nr-data.net # For EU region -``` - -```typescript title="src/mastra/index.ts" -new OtelExporter({ provider: { newrelic: {} } }) -``` - -##### Explicit Configuration - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - newrelic: { - apiKey: process.env.NEW_RELIC_LICENSE_KEY, - // endpoint: 'https://otlp.eu01.nr-data.net', // For EU region - }, - }, -}) -``` - -#### Traceloop - -[Traceloop](https://www.traceloop.com/) specializes in LLM observability with automatic prompt tracking. - -##### Zero-Config Setup - -```bash title=".env" -# Required -TRACELOOP_API_KEY=your-api-key - -# Optional -TRACELOOP_DESTINATION_ID=my-destination -TRACELOOP_ENDPOINT=https://custom.traceloop.com -``` - -```typescript title="src/mastra/index.ts" -new OtelExporter({ provider: { traceloop: {} } }) -``` - -##### Explicit Configuration - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - traceloop: { - apiKey: process.env.TRACELOOP_API_KEY, - destinationId: 'my-destination', // Optional - }, - }, -}) -``` - -#### Laminar - -[Laminar](https://laminar.sh/) provides specialized LLM observability and analytics. - -##### Zero-Config Setup - -```bash title=".env" -# Required -LMNR_PROJECT_API_KEY=your-api-key - -# Optional -LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces -``` - -```typescript title="src/mastra/index.ts" -new OtelExporter({ provider: { laminar: {} } }) -``` - -##### Explicit Configuration - -```typescript title="src/mastra/index.ts" -new OtelExporter({ - provider: { - laminar: { - apiKey: process.env.LMNR_PROJECT_API_KEY, - }, - }, -}) -``` - -:::tip Laminar-Native Exporter - -For Laminar-specific features like native span paths, metadata, and tags rendering in the Laminar dashboard, consider using the dedicated [`@mastra/laminar`](/integrations/observability/laminar) exporter instead. It provides optimized integration with Laminar's platform. - -::: - #### Datadog [Datadog](https://www.datadoghq.com/) APM provides application performance monitoring with distributed tracing. To send traces to Datadog via OTLP, you need the Datadog Agent running with OTLP ingestion enabled. @@ -465,6 +217,254 @@ For Datadog-specific features like automatic span type mapping, LLM span categor ::: +#### Laminar + +[Laminar](https://laminar.sh/) provides specialized LLM observability and analytics. + +##### Zero-Config Setup + +```bash title=".env" +# Required +LMNR_PROJECT_API_KEY=your-api-key + +# Optional +LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces +``` + +```typescript title="src/mastra/index.ts" +new OtelExporter({ provider: { laminar: {} } }) +``` + +##### Explicit Configuration + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + laminar: { + apiKey: process.env.LMNR_PROJECT_API_KEY, + }, + }, +}) +``` + +:::tip Laminar-Native Exporter + +For Laminar-specific features like native span paths, metadata, and tags rendering in the Laminar dashboard, consider using the dedicated [`@mastra/laminar`](/integrations/observability/laminar) exporter instead. It provides optimized integration with Laminar's platform. + +::: + +#### Latitude + +[Latitude](https://latitude.so) is an open-source LLM observability and evaluation platform that ingests OTLP traces. Use the `custom` provider with HTTP/Protobuf, pointing at Latitude's ingestion endpoint and authenticating with your API key and project slug: + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + custom: { + endpoint: 'https://ingest.latitude.so/v1/traces', + protocol: 'http/protobuf', + headers: { + Authorization: `Bearer ${process.env.LATITUDE_API_KEY}`, + 'X-Latitude-Project': process.env.LATITUDE_PROJECT, + }, + }, + }, +}) +``` + +Sign up at [console.latitude.so](https://console.latitude.so/login), or self-host and point the endpoint at your own ingestion host. + +#### MLflow + +[MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) supports native Mastra tracing through its OTLP endpoint at `/v1/traces`. Use the `custom` provider with HTTP/Protobuf and include the experiment header so traces are routed to the correct MLflow experiment: + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + custom: { + endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`, + protocol: 'http/protobuf', + headers: { + 'x-mlflow-experiment-id': process.env.MLFLOW_EXPERIMENT_ID, + }, + }, + }, +}) +``` + +#### New Relic + +[New Relic](https://newrelic.com/) provides complete observability with AI monitoring capabilities. + +##### Zero-Config Setup + +```bash title=".env" +# Required +NEW_RELIC_LICENSE_KEY=your-license-key + +# Optional +NEW_RELIC_ENDPOINT=https://otlp.eu01.nr-data.net # For EU region +``` + +```typescript title="src/mastra/index.ts" +new OtelExporter({ provider: { newrelic: {} } }) +``` + +##### Explicit Configuration + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + newrelic: { + apiKey: process.env.NEW_RELIC_LICENSE_KEY, + // endpoint: 'https://otlp.eu01.nr-data.net', // For EU region + }, + }, +}) +``` + +#### Sazabi + +[Sazabi](https://sazabi.com) is an AI-native observability platform that ingests OTLP traces. In Sazabi, add a Mastra log source and copy its intake URL. The URL carries your project key, so no auth header is needed: + +```bash title=".env" +SAZABI_INTAKE_URL=https://... +``` + +Use the `custom` provider with HTTP/JSON: + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + custom: { + endpoint: process.env.SAZABI_INTAKE_URL!, + protocol: 'http/json', + }, + }, +}) +``` + +See [Sazabi's Mastra guide](https://docs.sazabi.com/catalogs/log-sources/send-to-an-endpoint/mastra) for the full setup. + +#### Sentry + +[Sentry](https://sentry.io/) accepts OpenTelemetry traces and logs through its OTLP endpoints. In Sentry, open [**Project Settings** > **Client Keys (DSN)**](https://sentry.io/settings/projects/) and copy the OTLP traces endpoint and authentication header. Add both values to your environment: + +```bash title=".env" +SENTRY_OTLP_ENDPOINT=https://o000000.ingest.sentry.io/api/0000000/integration/otlp/v1/traces +SENTRY_OTLP_AUTH_HEADER="sentry sentry_key=..." +``` + +Use the `custom` provider with HTTP/Protobuf: + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + custom: { + endpoint: process.env.SENTRY_OTLP_ENDPOINT!, + protocol: 'http/protobuf', + headers: { + 'x-sentry-auth': process.env.SENTRY_OTLP_AUTH_HEADER!, + }, + }, + }, +}) +``` + +See [Sentry's OTLP documentation](https://docs.sentry.io/concepts/otlp/) for endpoint setup, supported signals, and current ingestion limits. + +Choose an exporter based on your setup: + +- `OtelExporter`: Sends vendor-neutral traces and logs over OTLP. Use it with an existing OpenTelemetry pipeline or when you want backend portability. +- [`SentryExporter`](/integrations/observability/sentry): Uses the Sentry SDK to map Mastra span types to Sentry operations, add AI monitoring attributes, and capture span errors as Sentry issues. + +#### SigNoz + +[SigNoz](https://signoz.io/) is an open-source APM alternative with built-in Tracing support. + +##### Zero-Config Setup + +```bash title=".env" +# Required +SIGNOZ_API_KEY=your-api-key + +# Optional +SIGNOZ_REGION=us # 'us' | 'eu' | 'in' +SIGNOZ_ENDPOINT=https://my-signoz.example.com # For self-hosted +``` + +```typescript title="src/mastra/index.ts" +new OtelExporter({ provider: { signoz: {} } }) +``` + +##### Explicit Configuration + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + signoz: { + apiKey: process.env.SIGNOZ_API_KEY, + region: 'us', // 'us' | 'eu' | 'in' + // endpoint: 'https://my-signoz.example.com', // For self-hosted + }, + }, +}) +``` + +#### telemetry.dev + +[telemetry.dev](https://telemetry.dev) ingests OTLP/HTTP protobuf traces and normalizes OpenTelemetry GenAI semantic conventions into model, provider, token, latency, and cost fields. Use the `custom` provider with your project API key: + +```bash title=".env" +TELEMETRY_DEV_API_KEY=td_live_... +``` + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + custom: { + endpoint: 'https://ingest.telemetry.dev/v1/traces', + protocol: 'http/protobuf', + headers: { + Authorization: `Bearer ${process.env.TELEMETRY_DEV_API_KEY}`, + }, + }, + }, +}) +``` + +#### Traceloop + +[Traceloop](https://www.traceloop.com/) specializes in LLM observability with automatic prompt tracking. + +##### Zero-Config Setup + +```bash title=".env" +# Required +TRACELOOP_API_KEY=your-api-key + +# Optional +TRACELOOP_DESTINATION_ID=my-destination +TRACELOOP_ENDPOINT=https://custom.traceloop.com +``` + +```typescript title="src/mastra/index.ts" +new OtelExporter({ provider: { traceloop: {} } }) +``` + +##### Explicit Configuration + +```typescript title="src/mastra/index.ts" +new OtelExporter({ + provider: { + traceloop: { + apiKey: process.env.TRACELOOP_API_KEY, + destinationId: 'my-destination', // Optional + }, + }, +}) +``` + #### Custom/Generic OTEL Endpoints For other OTEL-compatible platforms or custom collectors: @@ -525,7 +525,7 @@ If the matching log exporter package isn't installed, log export is silently dis new OtelExporter({ // Provider configuration (required) provider: { - // Use one of: dash0, signoz, newrelic, traceloop, laminar, custom + // Use one of: dash0, laminar, newrelic, signoz, traceloop, custom }, // Per-signal toggles. Both default to true. @@ -577,10 +577,10 @@ Choose the right protocol package based on your provider: | - | - | - | | Dash0 | gRPC | `@opentelemetry/exporter-trace-otlp-grpc` | | Datadog | gRPC | `@opentelemetry/exporter-trace-otlp-grpc` | -| SigNoz | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | -| New Relic | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | -| Traceloop | HTTP/JSON | `@opentelemetry/exporter-trace-otlp-http` | | Laminar | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | +| New Relic | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | +| SigNoz | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | +| Traceloop | HTTP/JSON | `@opentelemetry/exporter-trace-otlp-http` | | Custom | Varies | Depends on your collector | :::warning From 657d2e21275cc10d367e35038a31c94791fc8688 Mon Sep 17 00:00:00 2001 From: "mastra-platform[bot]" <284800079+mastra-platform[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 09:01:13 +0100 Subject: [PATCH 7/8] docs: clarify DurableAgent.abortThreadStream returns false while still forwarding the abort (#30439) --- docs/src/content/en/reference/agents/durable-agent.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/en/reference/agents/durable-agent.mdx b/docs/src/content/en/reference/agents/durable-agent.mdx index 5e7bf3a0aea..b381f2a9544 100644 --- a/docs/src/content/en/reference/agents/durable-agent.mdx +++ b/docs/src/content/en/reference/agents/durable-agent.mdx @@ -440,7 +440,7 @@ Returns: `boolean`. `true` when this process aborted the run locally or can see #### `abortThreadStream({ threadId, resourceId?, expectedRunId? })` -Aborts the active run on a memory thread with the same abort request as `abortRunStream()`. The run is resolved from this process's thread runtime, so it must have been started here or observed through `subscribeToThread()` on this process. The server route `POST /agents/:agentId/threads/abort` uses this method. +Aborts the active run on a memory thread with the same abort request as `abortRunStream()`. When this process runs the thread's active run, the abort applies here. When this process has observed the run through `subscribeToThread()`, the abort request is published to the process executing the run, and nothing stops in this process. When the process never saw the run, it looks the run up in the background through the thread's lease and asks the process executing it to stop, publishing the request over the shared PubSub. That lookup runs asynchronously. The method returns before the lookup finishes. The server route [`POST /agents/:agentId/threads/abort`](/reference/server/routes#thread-cancellation-routes) awaits the lookup when the abort wasn't resolved in this process, which is how it reports whether a run on another process was asked to stop. Pass `expectedRunId` when the request must only stop a specific run. If another queued run becomes active before the request is handled, the method returns `false` without aborting the successor. Omit `expectedRunId` to abort whichever run is active when the request is handled. @@ -452,7 +452,7 @@ const aborted = durableAgent.abortThreadStream({ }) ``` -Returns: `boolean`. `false` when this process has no active run recorded for the thread or the active run doesn't match `expectedRunId`. No abort request is sent in either case. +Returns: `boolean`. `true` when this process aborted the run, or when the abort request was published to the process executing it. A published request doesn't confirm that the other process stopped the run. `false` is this process's own result: it had no run of the thread's to stop, the active run didn't match `expectedRunId`, or `localOnly: true` kept the abort local and left a run owned by another process alone. An `expectedRunId` mismatch and `localOnly: true` leave the run running by design. Otherwise `false` doesn't rule out a forwarded abort: the background lookup still publishes an abort request to the process holding the lease when it finishes, or finds nothing to publish. A failed lookup or publish is logged as a warning through the Mastra logger. Use the thread-abort route above when you need the forwarded outcome reported. ### Recovery From 30852ab5fe4508bfac336e3c38037060e4dc8e25 Mon Sep 17 00:00:00 2001 From: "mastra-platform[bot]" <284800079+mastra-platform[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 09:22:33 +0100 Subject: [PATCH 8/8] docs(client-js): align retry docs with the write default (#30435) Co-authored-by: sdivyanshu90 <97019230+sdivyanshu90@users.noreply.github.com> --- docs/src/content/en/reference/client-js/mastra-client.mdx | 2 +- docs/src/content/en/reference/client-js/observability.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/en/reference/client-js/mastra-client.mdx b/docs/src/content/en/reference/client-js/mastra-client.mdx index 1c34280cd35..9de478a891e 100644 --- a/docs/src/content/en/reference/client-js/mastra-client.mdx +++ b/docs/src/content/en/reference/client-js/mastra-client.mdx @@ -56,7 +56,7 @@ You can also pass `requestContext` as a `Record`. name: 'retries', type: 'number', description: - "The number of times a request will be retried on failure before throwing an error. Retries apply to read requests (GET, HEAD, OPTIONS) by default, and to the observability queries that read server state even though they are sent as POST (aggregateTraces, aggregateSpans, queryTraceThreads, querySpans). Write requests (POST, PUT, PATCH, DELETE) are sent once unless you set this explicitly, so a server error can't repeat a state-changing request.", + "The number of times a request will be retried on failure before throwing an error. Retries apply to read requests (GET, HEAD, OPTIONS) by default, and to the observability queries that read server state even though they are sent as POST (aggregateTraces, aggregateSpans, queryTraceThreads, querySpans). Write requests (POST, PUT, PATCH, DELETE) are sent once unless you set `retries` here, so a server error can't repeat a state-changing request. Methods that accept request options, such as `createFeedback()` and `replaceFeedback()`, can also set `retries` per call, and that count takes precedence over this one. This count covers transport retries only: `createScore()`, `createFeedback()`, and `replaceFeedback()` also retry missing-trace and missing-span responses for up to 30 seconds unless you pass `anchorRetryTimeoutMs: 0`, as described in the observability reference under Signal write options.", isOptional: true, defaultValue: '3 for read requests, 0 for write requests', }, diff --git a/docs/src/content/en/reference/client-js/observability.mdx b/docs/src/content/en/reference/client-js/observability.mdx index e2d9ab0ce00..9940a39181c 100644 --- a/docs/src/content/en/reference/client-js/observability.mdx +++ b/docs/src/content/en/reference/client-js/observability.mdx @@ -520,7 +520,7 @@ await mastraClient.replaceFeedback({ }) ``` -Use the normalized timestamp from the create response's `data` when available. OSS rejects changes to the original trace or timestamp with `409`. Platform uses the timestamp as part of record identity, so preserve it there too. The client preserves the replacement body across retries, but each accepted PUT retry is a new replacement and can supersede another edit. Pass `{ retries: 0, anchorRetryTimeoutMs: 0 }` as the second argument to disable automatic retries. +Use the normalized timestamp from the create response's `data` when available. OSS rejects changes to the original trace or timestamp with `409`. Platform uses the timestamp as part of record identity, so preserve it there too. The client preserves the replacement body across retries, but each accepted PUT retry is a new replacement and can supersede another edit. PUT requests get no transport retries by default, but a client configured with `retries` applies that count here too, and anchor retries stay on unless you turn them off. Pass `{ retries: 0, anchorRetryTimeoutMs: 0 }` as the second argument to disable both transport and anchor retries. `retries: 0` is only redundant when the client has no `retries` configured. ### Deleting feedback and scores