From d9103ddf97799ec7892e171890b2bfba0ccaf219 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 19:30:46 +0000 Subject: [PATCH] feat(mcp): Record side quest next-call fingerprints so taken quests can be measured Each shown side quest records fingerprints of the next calls it offered as app.side_quest..next, and every tool call records its own fingerprint as app.tool_call.fingerprint (on the inner span for execute_sentry_tool). Analytics can then join a later call from the same user to the quest that offered it, with no server-side state. Co-Authored-By: Christina Long <60594860+Christinarlong@users.noreply.github.com> --- docs/operations/monitoring.md | 2 + .../mcp-core/src/internal/side-quests.test.ts | 67 +++++++++++++++++++ packages/mcp-core/src/internal/side-quests.ts | 58 ++++++++++++++++ packages/mcp-core/src/server.test.ts | 36 ++++++++++ packages/mcp-core/src/server.ts | 12 ++++ .../src/tools/special/execute-tool.ts | 8 +++ 6 files changed, 183 insertions(+) diff --git a/docs/operations/monitoring.md b/docs/operations/monitoring.md index e62143446..48f6e6db0 100644 --- a/docs/operations/monitoring.md +++ b/docs/operations/monitoring.md @@ -187,6 +187,8 @@ These are Sentry MCP application attributes that are not part of the MCP semanti - `app.consent.skill..granted` - Per-skill boolean attributes for skills granted to the MCP request. Skill ids are normalized with `-` replaced by `_` - `app.side_quest.` - `"shown"` or `"capped"` (detected but cut by the cap) for each side quest a tool call detected; unset when not detected. Ids are stable snake_case - `app.side_quests.detected`, `app.side_quests.shown` - Integer counts of side quests detected and shown; `0` when detectors ran and found none. Each shown quest also increments the `app.side_quest.shown` counter metric, tagged `side_quest.id`, which trace sampling does not drop +- `app.side_quest..next` - Comma-separated fingerprints of the `next` calls a shown side quest offered; unset when it offered none +- `app.tool_call.fingerprint` - Fingerprint of the tool call: a hash of the tool name and its arguments, without scope keys (organization, project, region) or empty values. For `execute_sentry_tool`, it is set on the child span of the tool it runs. A span from the same user whose fingerprint is in an earlier span's `app.side_quest..next` is a call that quest offered. Both spans are sampled independently, so divide the matched share by the sample rate - `app.upstream.host` - Upstream Sentry host configured for the server - `app.url.full` - MCP URL configured for stdio diff --git a/packages/mcp-core/src/internal/side-quests.test.ts b/packages/mcp-core/src/internal/side-quests.test.ts index 0412884cc..07f1ccf19 100644 --- a/packages/mcp-core/src/internal/side-quests.test.ts +++ b/packages/mcp-core/src/internal/side-quests.test.ts @@ -3,6 +3,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest"; import { type SideQuestCandidate, buildSideQuests, + fingerprintToolCall, formatSideQuests, } from "./side-quests"; @@ -186,6 +187,35 @@ describe("side quest telemetry", () => { ]); }); + it("records the fingerprints of the calls each shown quest offered", () => { + buildSideQuests( + null, + [ + detector({ + rank: 0, + id: "calls", + tip: "Tip.", + next: [ + { tool: "update_project", args: { slug: "web" } }, + { tool: "get_issue_details", args: { issueId: "WEB-1" } }, + { tool: "search_events", args: { query: "a" } }, + ], + }), + detector({ rank: 1, id: "tip_only", tip: "Tip." }), + ], + session, + ); + + // update_project is not in the session, so only the calls the quest + // shows are recorded. + expect(setAttributes).toHaveBeenLastCalledWith({ + "app.side_quest.calls.next": [ + fingerprintToolCall("get_issue_details", { issueId: "WEB-1" }), + fingerprintToolCall("search_events", { query: "a" }), + ].join(","), + }); + }); + it("records zero counts when no detector finds anything", () => { buildSideQuests(null, [detector(null)], session); @@ -197,6 +227,43 @@ describe("side quest telemetry", () => { }); }); +describe("fingerprintToolCall", () => { + const call = { + organizationSlug: "acme", + resourceType: "issue", + resourceId: "WEB-1", + }; + + it("is a short hex id", () => { + expect(fingerprintToolCall("get_sentry_resource", call)).toMatch( + /^[0-9a-f]{8}$/, + ); + }); + + it("ignores key order, scope keys, and empty values", () => { + expect( + fingerprintToolCall("get_sentry_resource", { + resourceId: "WEB-1", + regionUrl: "https://us.sentry.io", + resourceType: "issue", + url: "", + packageNames: undefined, + }), + ).toBe(fingerprintToolCall("get_sentry_resource", call)); + }); + + it("differs by tool and by argument value", () => { + const fingerprint = fingerprintToolCall("get_sentry_resource", call); + expect(fingerprintToolCall("update_issue", call)).not.toBe(fingerprint); + expect( + fingerprintToolCall("get_sentry_resource", { + ...call, + resourceId: "WEB-2", + }), + ).not.toBe(fingerprint); + }); +}); + describe("formatSideQuests", () => { it("renders one line per quest, with its calls, docs, and details", () => { expect( diff --git a/packages/mcp-core/src/internal/side-quests.ts b/packages/mcp-core/src/internal/side-quests.ts index 931045bed..09f127d06 100644 --- a/packages/mcp-core/src/internal/side-quests.ts +++ b/packages/mcp-core/src/internal/side-quests.ts @@ -7,6 +7,7 @@ import { getToolCallRoute, } from "./tool-helpers/tool-call-formatting"; import type { SuggestedActionValue } from "./tool-helpers/suggested-actions"; +import { CONSTRAINT_PARAMETER_KEYS } from "../types"; /** * Side quests are optional detours a tool response points out, such as a @@ -107,9 +108,66 @@ export function buildSideQuests( ...(lines.length > 0 && { details: lines }), }; }); + recordOfferedCalls(quests); return quests.length > 0 ? quests : undefined; } +/** The span attribute every tool call records its fingerprint in. */ +export const TOOL_CALL_FINGERPRINT_ATTRIBUTE = "app.tool_call.fingerprint"; + +/** + * A short, stable id for a tool call: the tool name and its arguments in key + * order, hashed. A shown quest records the fingerprints of its `next` calls, + * and every tool call records its own, so analytics can tell when a later + * call from the same user is one a quest offered. + * + * Scope keys (organization, project, region) are left out: the server fills + * them from constraints or the default organization, so an agent may or may + * not pass them. Empty values are left out for the same reason. + */ +export function fingerprintToolCall( + tool: string, + args: Record, +): string { + const entries = Object.entries(args) + .filter( + ([key, value]) => + !CONSTRAINT_PARAMETER_KEYS.has(key) && value != null && value !== "", + ) + .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)); + return fnv1a(JSON.stringify([tool, entries])); +} + +/** 32-bit FNV-1a as 8 hex characters. Not for security; only stability matters. */ +function fnv1a(input: string): string { + let hash = 0x811c9dc5; + for (let i = 0; i < input.length; i++) { + hash ^= input.charCodeAt(i); + hash = Math.imul(hash, 0x01000193); + } + return (hash >>> 0).toString(16).padStart(8, "0"); +} + +/** + * Records the `next` calls each shown quest offered as + * `app.side_quest..next`, a comma-separated list of fingerprints. A later + * span from the same user whose {@link TOOL_CALL_FINGERPRINT_ATTRIBUTE} is in + * that list is a call the quest offered. + */ +function recordOfferedCalls(quests: SideQuest[]) { + const attributes: Record = {}; + for (const { id, next } of quests) { + if (next?.length) { + attributes[`app.side_quest.${id}.next`] = next + .map(({ tool, args }) => fingerprintToolCall(tool, args)) + .join(","); + } + } + if (Object.keys(attributes).length > 0) { + getActiveSpan()?.setAttributes(attributes); + } +} + /** * Records which quests were detected and which the cap cut, so analytics can * query them without parsing tool output: one `app.side_quest.` span diff --git a/packages/mcp-core/src/server.test.ts b/packages/mcp-core/src/server.test.ts index 569c41b2b..c76ed6bb0 100644 --- a/packages/mcp-core/src/server.test.ts +++ b/packages/mcp-core/src/server.test.ts @@ -4,6 +4,7 @@ import { McpServer } from "@modelcontextprotocol/server"; import { type Span, captureException, + getActiveSpan, getClient, setUser, startSpan, @@ -22,6 +23,7 @@ import { z } from "zod"; import { MAX_TOOL_INPUT_ELEMENTS } from "@sentry/toolkit-core/mcp-limits"; import { ApiAuthenticationError } from "./api-client"; import { UserInputError } from "./errors"; +import { fingerprintToolCall } from "./internal/side-quests"; import { apiServiceFromContext } from "./internal/tool-helpers/api"; import { structuredResult } from "./internal/tool-helpers/results"; import { buildServer } from "./server"; @@ -3279,6 +3281,40 @@ describe("buildServer", () => { expect(span.recordException).not.toHaveBeenCalled(); }); + it("records each call's fingerprint on the span of the tool that ran", async () => { + const registry: Record = {}; + registry.fake_catalog_tool = createMockTool("fake_catalog_tool", { + inputSchema: { value: z.string() }, + }); + registry.execute_sentry_tool = createExecuteTool(() => registry); + const activeSpan = { ...createMockSpan(), setAttributes: vi.fn() }; + vi.mocked(getActiveSpan).mockReturnValue(activeSpan as unknown as Span); + const server = buildServer({ context: baseContext, tools: registry }); + const fingerprint = fingerprintToolCall("fake_catalog_tool", { + value: "a", + }); + + await callRegisteredTool(server, "execute_sentry_tool", { + name: "fake_catalog_tool", + arguments: { value: "a" }, + }); + expect(startedSpans[0].setAttribute).toHaveBeenCalledWith( + "app.tool_call.fingerprint", + fingerprint, + ); + expect(activeSpan.setAttribute).not.toHaveBeenCalledWith( + "app.tool_call.fingerprint", + expect.anything(), + ); + + await callRegisteredTool(server, "fake_catalog_tool", { value: "a" }); + expect(activeSpan.setAttribute).toHaveBeenCalledWith( + "app.tool_call.fingerprint", + fingerprint, + ); + vi.mocked(getActiveSpan).mockReturnValue(undefined); + }); + it("execute_sentry_tool injects constrained arguments for catalog-only tools", async () => { const server = buildServer({ context: { diff --git a/packages/mcp-core/src/server.ts b/packages/mcp-core/src/server.ts index 3ade13e5c..877fe8564 100644 --- a/packages/mcp-core/src/server.ts +++ b/packages/mcp-core/src/server.ts @@ -45,6 +45,10 @@ import { isExpectedToolError, recordToolFailure, } from "./internal/error-handling"; +import { + TOOL_CALL_FINGERPRINT_ATTRIBUTE, + fingerprintToolCall, +} from "./internal/side-quests"; import type { Skill } from "./skills"; import { type LogIssueOptions, logIssue } from "./telem/logging"; import { @@ -457,6 +461,14 @@ function configureServer({ ); if (activeSpan) { + // execute_sentry_tool records the fingerprint of the tool it runs + // on its own child span. + if (tool.name !== "execute_sentry_tool") { + activeSpan.setAttribute( + TOOL_CALL_FINGERPRINT_ATTRIBUTE, + fingerprintToolCall(tool.name, paramsWithConstraints), + ); + } // Intentional GenAI semconv extension: per-key attrs like http.request.header.. for (const [key, value] of Object.entries(paramsWithConstraints)) { const attributeValue = diff --git a/packages/mcp-core/src/tools/special/execute-tool.ts b/packages/mcp-core/src/tools/special/execute-tool.ts index bd21ac79c..b43ea5e76 100644 --- a/packages/mcp-core/src/tools/special/execute-tool.ts +++ b/packages/mcp-core/src/tools/special/execute-tool.ts @@ -6,6 +6,10 @@ import { recordToolFailure, } from "../../internal/error-handling"; import { UserInputError } from "../../errors"; +import { + TOOL_CALL_FINGERPRINT_ATTRIBUTE, + fingerprintToolCall, +} from "../../internal/side-quests"; import { withRoutedCredential } from "../../internal/tool-helpers/credential-routing"; import { ALL_SKILLS } from "../../skills"; import type { ServerContext } from "../../types"; @@ -66,6 +70,10 @@ async function executeCatalogToolWithSpan({ context, }); setToolArgumentAttributes(span, paramsWithConstraints); + span.setAttribute( + TOOL_CALL_FINGERPRINT_ATTRIBUTE, + fingerprintToolCall(tool.name, paramsWithConstraints), + ); const output = await withRoutedCredential( context, paramsWithConstraints,