Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/operations/monitoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,8 @@ These are Sentry MCP application attributes that are not part of the MCP semanti
- `app.consent.skill.<skill>.granted` - Per-skill boolean attributes for skills granted to the MCP request. Skill ids are normalized with `-` replaced by `_`
- `app.side_quest.<id>` - `"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.<id>.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.<id>.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

Expand Down
67 changes: 67 additions & 0 deletions packages/mcp-core/src/internal/side-quests.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
import {
type SideQuestCandidate,
buildSideQuests,
fingerprintToolCall,
formatSideQuests,
} from "./side-quests";

Expand Down Expand Up @@ -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);

Expand All @@ -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(
Expand Down
58 changes: 58 additions & 0 deletions packages/mcp-core/src/internal/side-quests.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -107,9 +108,66 @@ export function buildSideQuests<Input>(
...(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, unknown>,
): 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.<id>.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<string, string> = {};
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.<id>` span
Expand Down
36 changes: 36 additions & 0 deletions packages/mcp-core/src/server.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import { McpServer } from "@modelcontextprotocol/server";
import {
type Span,
captureException,
getActiveSpan,
getClient,
setUser,
startSpan,
Expand All @@ -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";
Expand Down Expand Up @@ -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<string, ToolConfig> = {};
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: {
Expand Down
12 changes: 12 additions & 0 deletions packages/mcp-core/src/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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.<key>.
for (const [key, value] of Object.entries(paramsWithConstraints)) {
const attributeValue =
Expand Down
8 changes: 8 additions & 0 deletions packages/mcp-core/src/tools/special/execute-tool.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -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,
Expand Down
Loading