diff --git a/docs/contributing/tool-responses.md b/docs/contributing/tool-responses.md index c136949702..b853fbe056 100644 --- a/docs/contributing/tool-responses.md +++ b/docs/contributing/tool-responses.md @@ -100,9 +100,11 @@ notes. Side quests are things that might help but may not matter for the current task, such as configuration issues or follow-ups. Source maps that failed to -apply are one. List each once, at the end under `## Concerns Identified`. When -one changes how to read the current data, add a one-line caveat where that data -appears. Raise one only when Sentry's own data shows it unambiguously. +apply are one. List each once, at the end under `## Concerns Identified`, as a +short tip that names the problem and its fix. When one changes how to read the +current data, say so in the tip: "Source maps weren't applied, so frames may be +minified." Raise one only when Sentry's own data shows it unambiguously. Build +them with `buildSideQuests` in `packages/mcp-core/src/internal/side-quests.ts`. ## Formatting Upstream Data diff --git a/packages/mcp-core/src/internal/formatting.ts b/packages/mcp-core/src/internal/formatting.ts index 2126578d31..7b8b2bd08a 100644 --- a/packages/mcp-core/src/internal/formatting.ts +++ b/packages/mcp-core/src/internal/formatting.ts @@ -33,13 +33,9 @@ import type { TraceSpan, } from "../api-client/types"; import { logIssue } from "../telem/logging"; -import { - buildConcerns, - formatConcernCaveats, - formatConcernsSection, - hasReadableStack, -} from "./concerns"; +import { buildIssueSideQuests, hasReadableStack } from "./issue-side-quests"; import { selectEventPackages } from "./event-packages"; +import { formatSideQuests } from "./side-quests"; import { formatUnknown } from "./unknown-formatting"; import { type CodeLocation, @@ -2377,13 +2373,16 @@ export function formatIssueOutput({ output += `**URL**: ${apiService.getIssueUrl(organizationSlug, issue.shortId)}\n`; output += "\n"; - const concerns = buildConcerns(event, { sourceMapDebug }); - // caveats go before the first data they affect: Code Location, or else the - // top of Event Details, above the stacktrace - const caveats = formatConcernCaveats(concerns); + const sideQuests = buildIssueSideQuests( + { event, sourceMapDebug }, + { + experimentalMode: experimentalMode ?? false, + availableToolNames, + directToolNames, + }, + ); if (codeLocation) { - output += caveats; output += formatCodeLocation(codeLocation); } @@ -2426,8 +2425,8 @@ export function formatIssueOutput({ output += ` and Sentry Event ID **${sentryEventId}**`; } output += " to help us add support for this event type.\n"; - if (concerns.length > 0) { - output += `\n${formatConcernsSection(concerns)}`; + if (sideQuests) { + output += `\n${formatSideQuests(sideQuests)}`; } if (aiConversations && aiConversations.length > 0) { @@ -2451,9 +2450,6 @@ export function formatIssueOutput({ return output; } - if (!codeLocation) { - output += caveats; - } output += `**Event ID**: ${event.id}\n`; output += `**Type**: ${formatUnknown(event.type)}\n`; // default: error without exception data, generic: performance/metric issue, csp: CSP violation @@ -2509,7 +2505,7 @@ export function formatIssueOutput({ output += "\n"; } - output += formatConcernsSection(concerns); + output += formatSideQuests(sideQuests); output += "## Response Notes\n\n"; for (const note of buildIssueResponseNotes({ diff --git a/packages/mcp-core/src/internal/issue-side-quests.test.ts b/packages/mcp-core/src/internal/issue-side-quests.test.ts new file mode 100644 index 0000000000..82184cba02 --- /dev/null +++ b/packages/mcp-core/src/internal/issue-side-quests.test.ts @@ -0,0 +1,84 @@ +import { eventFixture, sourceMapDebugFixture } from "@sentry/mcp-server-mocks"; +import { describe, expect, it } from "vitest"; +import { EventSchema, SourceMapDebugSchema } from "../api-client/schema"; +import { buildIssueSideQuests } from "./issue-side-quests"; + +const session = { experimentalMode: false }; +const files = ["/a.js", "/b.js", "/c.js"]; + +/** + * The fixture's three raw frames, each from its own bundle, with a source map + * error for each and one more for `/d.js`, which has no frame. + */ +function eventWithFourFiles() { + const fixture = structuredClone(eventFixture); + for (const entry of fixture.entries) { + if (entry.type !== "exception") { + continue; + } + for (const value of entry.data.values) { + value.rawStacktrace?.frames.forEach( + (frame: { absPath: string | null }, index: number) => { + frame.absPath = files[index] ?? frame.absPath; + }, + ); + } + } + return EventSchema.parse({ + ...fixture, + user: { ...fixture.user, id: "8f3c2a" }, + errors: [...files, "/d.js"].map((url) => ({ + type: "js_no_source", + message: "Source code was not found", + data: { url }, + })), + }); +} + +describe("buildIssueSideQuests", () => { + it("lists each file's cause when the causes differ", () => { + const event = eventWithFourFiles(); + const debug = SourceMapDebugSchema.parse(sourceMapDebugFixture); + // `/b.js` has a debug ID, but nothing was uploaded for it + debug.exceptions[0].frames[1].debug_id_process.debug_id = + "41f4b626-efd6-5847-915c-69f5d33361fb"; + + expect(buildIssueSideQuests({ event, sourceMapDebug: debug }, session)) + .toMatchInlineSnapshot(` + [ + { + "details": [ + "\`/a.js\` and \`/c.js\` have no debug ID, and the project has no debug ID uploads. Inject debug IDs with the bundler plugin or \`sentry-cli sourcemaps inject\`, deploy, then upload those same files.", + "\`/b.js\` has debug ID \`41f4b626-efd6-5847-915c-69f5d33361fb\`, but no source file or source map with it was uploaded. Upload the deployed build output after injecting debug IDs, with the bundler plugin or \`sentry-cli sourcemaps upload\`.", + "1 more file: the source file or its source map was not found. Upload source maps for this release from the same build that was deployed.", + ], + "docs": "https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/", + "id": "js_source_maps", + "tip": "Source maps weren't applied to 4 files, so frames may be minified; the cause differs by file.", + }, + ] + `); + }); + + it("keeps the remainder when three files have three causes", () => { + const event = eventWithFourFiles(); + const debug = SourceMapDebugSchema.parse(sourceMapDebugFixture); + // `/b.js` and `/c.js` each have their own debug ID, with nothing uploaded + debug.exceptions[0].frames[1].debug_id_process.debug_id = + "41f4b626-efd6-5847-915c-69f5d33361fb"; + debug.exceptions[0].frames[2].debug_id_process.debug_id = + "6f88580e-719d-56bb-81e1-afad5d3d78ac"; + + const [quest] = + buildIssueSideQuests({ event, sourceMapDebug: debug }, session) ?? []; + + // the third cause joins the remainder, so `/d.js` is still explained + expect(quest.details).toMatchInlineSnapshot(` + [ + "\`/a.js\` has no debug ID, and the project has no debug ID uploads. Inject debug IDs with the bundler plugin or \`sentry-cli sourcemaps inject\`, deploy, then upload those same files.", + "\`/b.js\` has debug ID \`41f4b626-efd6-5847-915c-69f5d33361fb\`, but no source file or source map with it was uploaded. Upload the deployed build output after injecting debug IDs, with the bundler plugin or \`sentry-cli sourcemaps upload\`.", + "\`/c.js\` and 1 more: the source file or its source map was not found. Upload source maps for this release from the same build that was deployed.", + ] + `); + }); +}); diff --git a/packages/mcp-core/src/internal/concerns.ts b/packages/mcp-core/src/internal/issue-side-quests.ts similarity index 71% rename from packages/mcp-core/src/internal/concerns.ts rename to packages/mcp-core/src/internal/issue-side-quests.ts index 33c2285770..7421ec2435 100644 --- a/packages/mcp-core/src/internal/concerns.ts +++ b/packages/mcp-core/src/internal/issue-side-quests.ts @@ -1,74 +1,32 @@ import { inlineCode } from "@sentry/toolkit-core/markdown"; -import { z } from "zod"; import type { Event, SourceMapDebug } from "../api-client/types"; -import { diagnoseSourceMaps } from "./source-map-diagnosis"; +import { + type SideQuest, + type SideQuestCandidate, + type SideQuestDetector, + MAX_DETAILS, + buildSideQuests, +} from "./side-quests"; +import { diagnoseSourceMaps, formatFileList } from "./source-map-diagnosis"; +import type { ToolSession } from "./tool-helpers/tool-call-formatting"; /** - * Concerns are problems with the project's Sentry setup, such as missing - * source maps, that are optional to fix but would make future issues easier to - * debug. Detectors read the event and the checks already fetched for it in - * `ConcernContext`, such as Sentry's source map debug result. When the problem - * also changes how to read this event, the concern carries a one-line `caveat` - * that renders next to the affected data. + * The side quests for an issue's event: setup problems, such as missing + * source maps, that would make future issues easier to debug. Detectors read + * the event and the checks already fetched for it, such as Sentry's source + * map debug result. * - * To add one, write a detector that returns a `Concern` or null and add it to - * `DETECTORS`. `buildConcerns` orders them by priority and keeps the first - * `MAX_CONCERNS`. + * To add one, write a detector that returns a quest or null and add it to + * `DETECTORS`. */ -export const concernSchema = z.object({ - code: z - .string() - .describe("Stable identifier of the problem, such as js_source_maps."), - title: z.string(), - message: z.string().describe("What is wrong and how to fix it."), - docsUrl: z.string(), - errorTypes: z - .array(z.string()) - .describe("The Sentry event processing error types behind it."), - files: z - .array(z.string()) - .describe("Affected files, capped; fileCount says how many there are."), - fileCount: z.number(), - diagnosis: z - .array( - z.object({ - problem: z.string(), - fix: z.string(), - files: z.array(z.string()), - }), - ) - .describe( - "Cause and fix for the affected files, from a Sentry check of this event. Empty when no check ran.", - ), - caveat: z - .string() - .nullable() - .describe("How the problem affects reading this event, when it does."), -}); - -export type Concern = z.output; - -const MAX_CONCERNS = 3; -const MAX_FILES = 3; - -interface PrioritizedConcern { - /** Lower comes first. */ - priority: number; - concern: Concern; -} - -/** Optional checks fetched for the event; a detector works without them. */ -export interface ConcernContext { +export interface IssueSideQuestInput { + event: Event; + /** Optional; a detector works without it. */ sourceMapDebug?: SourceMapDebug; } -type Detector = ( - event: Event, - context: ConcernContext, -) => PrioritizedConcern | null; +const MAX_FILES = 3; -const JS_SOURCE_MAPS_DOCS_URL = - "https://docs.sentry.io/platforms/javascript/sourcemaps/"; const JS_SOURCE_MAPS_TROUBLESHOOTING_URL = "https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/"; @@ -186,10 +144,18 @@ export function hasJsSourceMapErrors(event: Event): boolean { ); } -function detectJsSourceMapFailure( - event: Event, - { sourceMapDebug }: ConcernContext, -): PrioritizedConcern | null { +const NOT_APPLIED = "Source maps weren't applied"; +const MINIFIED = "so frames may be minified"; + +/** + * Warns when Sentry could not apply source maps. With Sentry's source map + * check, the tip names each file's cause and fix; when causes differ by file, + * `details` lists them. Otherwise the error types' problems and fixes apply. + */ +function detectJsSourceMapFailure({ + event, + sourceMapDebug, +}: IssueSideQuestInput): SideQuestCandidate | null { const errorTypes = new Set(); // each affected file with the error types reported for it const files = new Map>(); @@ -210,38 +176,57 @@ function detectJsSourceMapFailure( const matched = [...JS_SOURCE_MAP_ERRORS].filter(([type]) => errorTypes.has(type), ); - const problems = matched.map(([, detail]) => detail.problem).join("; "); + // what the error types imply, for files the check does not explain + const fallback = `${matched.map(([, detail]) => detail.problem).join("; ")}. ${[...new Set(matched.map(([, detail]) => detail.fix))].join(" ")}`; + const quest = (tip: string, details?: string[]): SideQuestCandidate => ({ + rank: 0, + id: "js_source_maps", + tip, + docs: JS_SOURCE_MAPS_TROUBLESHOOTING_URL, + details, + }); + const listed = new Map([...files].slice(0, MAX_FILES)); - const listedFiles = [...listed.keys()]; const diagnosis = sourceMapDebug ? diagnoseSourceMaps({ event, debug: sourceMapDebug, files: listed }) : []; - // a diagnosis names the exact fix for its files; the error types' fix - // covers the rest, and events whose errors name no file - const fix = - countDiagnosedFiles(diagnosis) === files.size && files.size > 0 - ? "" - : ` Fix: ${[...new Set(matched.map(([, detail]) => detail.fix))].join(" ")}`; - - return { - priority: 0, - concern: { - code: "js_source_maps", - title: "Fix JavaScript source maps", - message: `Sentry could not apply source maps to this event: ${problems}.${fix} Troubleshooting: ${JS_SOURCE_MAPS_TROUBLESHOOTING_URL}`, - docsUrl: JS_SOURCE_MAPS_DOCS_URL, - errorTypes: matched.map(([type]) => type), - files: listedFiles, - fileCount: files.size, - diagnosis, - caveat: - "Source maps were not applied to this event; frames may point to minified code. See Concerns Identified.", - }, - }; -} + const diagnosed = new Set(diagnosis.flatMap((finding) => finding.files)); + const undiagnosed = [...listed.keys()].filter((file) => !diagnosed.has(file)); + const unlisted = files.size - listed.size; + + if (diagnosis.length === 0) { + const where = + files.size > 0 + ? ` to ${formatFileList([...listed.keys()], unlisted)}` + : ""; + return quest(`${NOT_APPLIED}${where}, ${MINIFIED}: ${fallback}`); + } + const [only] = diagnosis; + if (diagnosis.length === 1 && diagnosed.size === files.size) { + return quest(`${NOT_APPLIED}, ${MINIFIED}: ${only.problem}. ${only.fix}`); + } -function countDiagnosedFiles(diagnosis: Concern["diagnosis"]): number { - return diagnosis.reduce((count, { files }) => count + files.length, 0); + // causes differ by file, or some files have no diagnosis. The remainder + // line takes the last slot under the details cap, so a cause past it joins + // the remainder instead of pushing the remainder out. + const hasRest = undiagnosed.length > 0 || unlisted > 0; + const shown = diagnosis.slice(0, hasRest ? MAX_DETAILS - 1 : MAX_DETAILS); + const details = shown.map(({ problem, fix }) => `${problem}. ${fix}`); + const restFiles = [ + ...diagnosis.slice(shown.length).flatMap((finding) => finding.files), + ...undiagnosed, + ]; + if (hasRest) { + const rest = + restFiles.length > 0 + ? formatFileList(restFiles, unlisted) + : `${unlisted} more ${unlisted === 1 ? "file" : "files"}`; + details.push(`${rest}: ${fallback}`); + } + return quest( + `${NOT_APPLIED} to ${files.size} files, ${MINIFIED}; the cause differs by file.`, + details, + ); } const JS_SET_USER = "Sentry.setUser({ id: user.id })"; @@ -294,7 +279,9 @@ function hasValue(value: string | null | undefined) { * (transactions), metric, cron, uptime, and other generic issues, and CSP * reports do not come from code that can identify a signed-in user. */ -function detectMissingUserIdentity(event: Event): PrioritizedConcern | null { +function detectMissingUserIdentity({ + event, +}: IssueSideQuestInput): SideQuestCandidate | null { if (event.type !== "error" && event.type !== "default") { return null; } @@ -309,29 +296,27 @@ function detectMissingUserIdentity(event: Event): PrioritizedConcern | null { const call = setUser ? inlineCode(setUser.call) : `${inlineCode(JS_SET_USER)} or your SDK's equivalent`; + + // the JavaScript identify-user pages redirect to the SDK APIs page + const page = + setUser?.call === JS_SET_USER + ? "configuration/apis" + : "enriching-events/identify-user"; // the generic page asks which platform to show - const docsUrl = setUser - ? `https://docs.sentry.io/platforms/${setUser.docs}/enriching-events/identify-user/` + const docs = setUser + ? `https://docs.sentry.io/platforms/${setUser.docs}/${page}/` : "https://docs.sentry.io/platform-redirect/?next=/enriching-events/identify-user/"; const problem = hasValue(user?.ip_address) || hasValue(user?.ip) - ? "This event identifies the user only by IP address, so Users Impacted is approximate and you can't tell which signed-in users hit it." - : "This event has no user, so it doesn't count toward Users Impacted."; + ? "The user is identified only by IP, so Users Impacted is approximate." + : "The event has no user, so it doesn't count toward Users Impacted."; return { - priority: 10, - concern: { - code: "missing_user_identity", - title: "Identify users in events", - message: `${problem} Call ${call} after sign-in; an opaque internal ID is enough.`, - docsUrl, - errorTypes: [], - files: [], - fileCount: 0, - diagnosis: [], - caveat: null, - }, + rank: 10, + id: "missing_user_identity", + tip: `${problem} Call ${call} after sign-in; an opaque ID is enough.`, + docs, }; } @@ -536,26 +521,8 @@ export function hasReadableStack(event: Event): boolean { return hasStackFrames(event) && !isCrossOriginScriptError(event); } -function missingStackTrace( - title: string, - message: string, - docsUrl: string, -): PrioritizedConcern { - return { - priority: 5, - concern: { - code: "missing_stack_trace", - title, - message, - docsUrl, - errorTypes: [], - files: [], - fileCount: 0, - diagnosis: [], - // the missing stack is already plain in Event Details - caveat: null, - }, - }; +function missingStackTrace(tip: string, docs: string): SideQuestCandidate { + return { rank: 5, id: "missing_stack_trace", tip, docs }; } /** @@ -569,13 +536,14 @@ function missingStackTrace( * * Only error and default (message) events are checked, as for user identity. */ -function detectMissingStackTrace(event: Event): PrioritizedConcern | null { +function detectMissingStackTrace({ + event, +}: IssueSideQuestInput): SideQuestCandidate | null { if (event.type !== "error" && event.type !== "default") { return null; } if (isCrossOriginScriptError(event)) { return missingStackTrace( - "Allow cross-origin script errors", `The browser hid this error's message and stack because the script came from another origin. Add ${inlineCode('crossorigin="anonymous"')} to its ${inlineCode("