From dc975d4a0e88ff608e182e1f028b7fc63ac99942 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 22:06:52 +0000 Subject: [PATCH 1/2] fix(cli): Template org and project slugs in telemetry endpoints (#2213) `normalizeEndpoint` only templated paths with a leading slash, so paths relative to `/api/0/` reached telemetry with raw org and project slugs. This also normalizes full URLs, drops query strings, and templates short IDs, monitor slugs, and numeric IDs. The same normalization now applies to the `api_error` context, the `api_error.endpoint` span attribute of `sentry api`, and the description and URL attributes (`url`, `url.full`, `http.url`, `url.path`) of `http.client` spans. On 0.48.0+, no `api_error.endpoint` value (~6K spans in 14d) and no `http.client` span description (~1.3M of ~1.4M in 14d carry an org path) was templated. Some `cli_error.api_endpoint` values still carried raw slugs, through relative paths or short IDs. **Before** ``` cli_error.api_endpoint: organizations/my-org/artifactbundle/assemble/ cli_error.api_endpoint: /organizations/{org}/shortids/MY-PROJECT-1A/ api_error.endpoint: projects/my-org/my-project/issues/?query=is:unresolved span.description: GET https://sentry.io/api/0/organizations/my-org/issues/ ``` **After** ``` cli_error.api_endpoint: organizations/{org}/artifactbundle/assemble/ cli_error.api_endpoint: /organizations/{org}/shortids/{id}/ api_error.endpoint: projects/{org}/{project}/issues/ span.description: GET https://sentry.io/api/0/organizations/{org}/issues/ ``` via @betegon. -- [View Session](https://junior-prod.sentry.dev/conversations/agent%3Af73d86afcba15ac6080900f12725b985) [[Sentry]](https://sentry.sentry.io/explore/conversations/agent%3Af73d86afcba15ac6080900f12725b985/?project=4510944073809921) --------- Co-Authored-By: bete <28983162+betegon@users.noreply.github.com> --- packages/cli/src/commands/api.ts | 3 +- packages/cli/src/lib/error-reporting.ts | 23 ++++++++++---- packages/cli/src/lib/telemetry.ts | 25 ++++++++++++++++ packages/cli/test/lib/error-reporting.test.ts | 30 +++++++++++++++++++ 4 files changed, 75 insertions(+), 6 deletions(-) diff --git a/packages/cli/src/commands/api.ts b/packages/cli/src/commands/api.ts index da0a03d68..2d0304151 100644 --- a/packages/cli/src/commands/api.ts +++ b/packages/cli/src/commands/api.ts @@ -35,6 +35,7 @@ import { hasPreviousPage, resolveCursor, } from "../lib/db/pagination.js"; +import { normalizeEndpoint as templateEndpoint } from "../lib/error-reporting.js"; import { OutputError, stringifyUnknown, @@ -1463,7 +1464,7 @@ function recordApiErrorAttributes( const span = Sentry.getActiveSpan(); if (span) { span.setAttribute("api_error.status", status); - span.setAttribute("api_error.endpoint", endpoint); + span.setAttribute("api_error.endpoint", templateEndpoint(endpoint)); span.setAttribute("api_error.method", method); } } diff --git a/packages/cli/src/lib/error-reporting.ts b/packages/cli/src/lib/error-reporting.ts index 5bf15ca82..c1386fc4c 100644 --- a/packages/cli/src/lib/error-reporting.ts +++ b/packages/cli/src/lib/error-reporting.ts @@ -223,13 +223,18 @@ const ENDPOINT_PATTERNS: [RegExp, string][] = [ [/\/teams\/[^/]+\/[^/]+/, "/teams/{org}/{team}"], [/\/dashboards\/[^/]+/, "/dashboards/{id}"], [/\/customers\/[^/]+/, "/customers/{org}"], + [/\/shortids\/[^/]+/, "/shortids/{id}"], + [/\/monitors\/[^/]+/, "/monitors/{monitor}"], ]; /** * Strip remaining bare numeric segments (e.g. /12345/) but preserve - * the API version prefix /0/ which is always the second segment. + * the API version in /api/0/, which may follow an install prefix. */ -const BARE_NUMERIC_SEGMENT_RE = /(?<=\/api\/0\/.*)\/\d+(?=\/|$)/g; +const BARE_NUMERIC_SEGMENT_RE = /(? + normalizeEndpoint(url), + ); + for (const key of HTTP_SPAN_URL_KEYS) { + const value = span.data[key]; + if (typeof value === "string") { + span.data[key] = normalizeEndpoint(value); + } + } + } +} + /** * Integrations to exclude for CLI. * These add overhead without benefit for short-lived CLI processes. @@ -690,6 +714,7 @@ export function initSentry( beforeSendTransaction: (event) => { // Remove server_name which may contain hostname (PII) event.server_name = undefined; + normalizeHttpSpans(event); return event; }, diff --git a/packages/cli/test/lib/error-reporting.test.ts b/packages/cli/test/lib/error-reporting.test.ts index d4d2c5a86..e30a58fef 100644 --- a/packages/cli/test/lib/error-reporting.test.ts +++ b/packages/cli/test/lib/error-reporting.test.ts @@ -209,6 +209,36 @@ describe("normalizeEndpoint", () => { test("leaves paths without variable segments unchanged", () => { expect(normalizeEndpoint("/api/0/auth/")).toBe("/api/0/auth/"); }); + + test.each([ + ["organizations/my-org/releases/", "organizations/{org}/releases/"], + [ + "projects/my-org/my-project/issues/?query=is:unresolved", + "projects/{org}/{project}/issues/", + ], + [ + "https://sentry.example.com/api/0/organizations/my-org/events/?field=title", + "https://sentry.example.com/api/0/organizations/{org}/events/", + ], + [ + "https://sentry.example.com/sentry/api/0/organizations/my-org/", + "https://sentry.example.com/sentry/api/0/organizations/{org}/", + ], + [ + "/organizations/my-org/shortids/MY-PROJECT-1A/", + "/organizations/{org}/shortids/{id}/", + ], + [ + "organizations/my-org/monitors/my-monitor/", + "organizations/{org}/monitors/{monitor}/", + ], + [ + "organizations/my-org/alert-rules/123/", + "organizations/{org}/alert-rules/{id}/", + ], + ])("templates %s", (endpoint, expected) => { + expect(normalizeEndpoint(endpoint)).toBe(expected); + }); }); // --------------------------------------------------------------------------- From 6167d871713f3497b893f7ab426e050ebf577c78 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 07:45:45 +0000 Subject: [PATCH 2/2] ref(cli): Template telemetry endpoints with the API catalog's paths Replace normalizeEndpoint's regex list with the OpenAPI path templates from @sentry/api, which generate-api-schema now writes to src/generated/api-path-templates.json so the CLI never loads the full catalog. The most specific template that matches the most of a path wins, and segments past it that the templates don't spell out become {id}, so a path outside the catalog leaks nothing. Placeholders now use the OpenAPI names, such as {organization_id_or_slug} and {project_id_or_slug}, which changes existing cli_error.api_endpoint values. Co-Authored-By: bete <28983162+betegon@users.noreply.github.com> --- packages/cli/script/ensure-generated.mjs | 1 + packages/cli/script/generate-api-schema.ts | 17 ++- packages/cli/src/lib/error-reporting.ts | 112 +++++++++++++----- packages/cli/test/lib/error-reporting.test.ts | 79 ++---------- 4 files changed, 106 insertions(+), 103 deletions(-) diff --git a/packages/cli/script/ensure-generated.mjs b/packages/cli/script/ensure-generated.mjs index 83aa80ef1..86628d0d5 100644 --- a/packages/cli/script/ensure-generated.mjs +++ b/packages/cli/script/ensure-generated.mjs @@ -23,6 +23,7 @@ import { existsSync } from "node:fs"; const SCHEMA_OUTPUTS = [ "src/generated/api-schema.json", "src/generated/idempotent-operations.json", + "src/generated/api-path-templates.json", ]; /** Produced by `generate:grammar`; imported by `src/lib/arg-parsing.ts`. */ const GRAMMAR_OUTPUTS = [ diff --git a/packages/cli/script/generate-api-schema.ts b/packages/cli/script/generate-api-schema.ts index 702aeae92..4d53ee3a4 100644 --- a/packages/cli/script/generate-api-schema.ts +++ b/packages/cli/script/generate-api-schema.ts @@ -3,7 +3,8 @@ * Generate the CLI discovery index from the installed SDK's operation catalog. * * Usage: tsx script/generate-api-schema.ts - * Outputs: src/generated/api-schema.json and src/generated/idempotent-operations.json + * Outputs: src/generated/api-schema.json, src/generated/idempotent-operations.json + * and src/generated/api-path-templates.json */ import { mkdir, writeFile } from "node:fs/promises"; @@ -15,6 +16,7 @@ import { projectApiOperations } from "./lib/api-schema.js"; const OUTPUT_PATH = "src/generated/api-schema.json"; const IDEMPOTENT_OUTPUT_PATH = "src/generated/idempotent-operations.json"; +const PATH_TEMPLATES_OUTPUT_PATH = "src/generated/api-path-templates.json"; const endpoints = projectApiOperations(operations); await mkdir(dirname(OUTPUT_PATH), { recursive: true }); @@ -41,3 +43,16 @@ await writeFile( console.log( `Generated ${IDEMPOTENT_OUTPUT_PATH} (${idempotentOperations.length} operations)`, ); + +// Telemetry templates request paths against these, so it loads only the +// paths, not the catalog. +const pathTemplates = [...new Set(operations.map((op) => op.path))].sort(); + +await writeFile( + PATH_TEMPLATES_OUTPUT_PATH, + JSON.stringify(pathTemplates, null, 2), +); + +console.log( + `Generated ${PATH_TEMPLATES_OUTPUT_PATH} (${pathTemplates.length} paths)`, +); diff --git a/packages/cli/src/lib/error-reporting.ts b/packages/cli/src/lib/error-reporting.ts index c1386fc4c..98cad9c49 100644 --- a/packages/cli/src/lib/error-reporting.ts +++ b/packages/cli/src/lib/error-reporting.ts @@ -38,6 +38,8 @@ import { UnsatisfiedFlagError, UnsatisfiedPositionalError, } from "@stricli/core"; +import { matchApiPathTemplate } from "@sentry/toolkit-core/api-path-template"; +import apiPathTemplates from "../generated/api-path-templates.json"; import { redactCredentialText } from "./credential-redaction.js"; import { ApiError, @@ -212,54 +214,100 @@ function recordSilencedError(error: unknown, reason: SilenceReason): void { // Grouping tags // --------------------------------------------------------------------------- -/** Endpoint normalization patterns — compiled once at module scope. */ -const ENDPOINT_PATTERNS: [RegExp, string][] = [ - [/\/organizations\/[^/]+/, "/organizations/{org}"], - [/\/projects\/[^/]+\/[^/]+/, "/projects/{org}/{project}"], - [/\/issues\/[^/]+/, "/issues/{id}"], - [/\/events\/[^/]+/, "/events/{id}"], - [/\/groups\/[^/]+/, "/groups/{id}"], - [/\/releases\/[^/]+/, "/releases/{version}"], - [/\/teams\/[^/]+\/[^/]+/, "/teams/{org}/{team}"], - [/\/dashboards\/[^/]+/, "/dashboards/{id}"], - [/\/customers\/[^/]+/, "/customers/{org}"], - [/\/shortids\/[^/]+/, "/shortids/{id}"], - [/\/monitors\/[^/]+/, "/monitors/{monitor}"], -]; +/** The API version prefix every OpenAPI path template starts with. */ +const API_PREFIX = "/api/0"; -/** - * Strip remaining bare numeric segments (e.g. /12345/) but preserve - * the API version in /api/0/, which may follow an install prefix. - */ -const BARE_NUMERIC_SEGMENT_RE = /(? { + const template = path.replace(/\/$/, ""); + return { template, length: template.split("/").length }; +}); + +/** Segments the templates spell out literally, such as `issues`. */ +const LITERAL_SEGMENTS = new Set( + PATH_TEMPLATES.flatMap(({ template }) => template.split("/")).filter( + (segment) => !segment.startsWith("{"), + ), +); /** Scheme and host of an absolute URL. */ const URL_ORIGIN_RE = /^[a-z][a-z\d+.-]*:\/\/[^/?#]*/i; +/** + * Template `apiPath` with the OpenAPI path template that matches the most of + * it, most specific first. Segments past that match keep their literal + * segments and replace every other segment with `{id}`, so a path outside + * the catalog leaks nothing. + */ +function templateApiPath(apiPath: string): string { + const segments = apiPath.split("/"); + let best = { + template: API_PREFIX, + length: API_PREFIX.split("/").length, + literalSegments: 0, + }; + for (const { template, length } of PATH_TEMPLATES) { + if (length > segments.length || length < best.length) { + continue; + } + const match = matchApiPathTemplate( + template, + segments.slice(0, length).join("/"), + ); + if ( + match && + (length > best.length || match.literalSegments > best.literalSegments) + ) { + best = { template, length, literalSegments: match.literalSegments }; + } + } + const rest = segments + .slice(best.length) + .map((segment) => (LITERAL_SEGMENTS.has(segment) ? segment : "{id}")); + return [best.template, ...rest].join("/"); +} + /** * Normalize an API endpoint path by parameterizing variable segments. * * Replaces org slugs, project slugs, issue IDs, event IDs, and other - * entity identifiers with placeholders so that server-side fingerprint - * rules can sub-group `ApiError` by endpoint shape rather than exact path. + * entity identifiers with the placeholders of the `@sentry/api` OpenAPI + * path templates, so that server-side fingerprint rules can sub-group + * `ApiError` by endpoint shape rather than exact path. * - * Accepts a path with or without a leading slash, or a full URL, whose - * origin is kept. Drops the query string and fragment. + * Accepts a path relative to `/api/0/`, with or without a leading slash, or + * a full URL, whose origin and any install prefix before `/api/0/` are kept. + * Leaves full URLs outside `/api/0/` alone, since they are not API requests. + * Drops the query string and fragment. * * `"/api/0/projects/my-org/my-project/events/abc123/"` → - * `"/api/0/projects/{org}/{project}/events/{id}/"` + * `"/api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/events/{event_id}/"` */ export function normalizeEndpoint(endpoint: string): string { const origin = URL_ORIGIN_RE.exec(endpoint)?.[0] ?? ""; const path = endpoint.slice(origin.length).split(/[?#]/, 1)[0] ?? ""; - // The patterns match on a leading slash, which relative paths lack. - const hasLeadingSlash = origin !== "" || path.startsWith("/"); - let result = path.startsWith("/") ? path : `/${path}`; - for (const [pattern, replacement] of ENDPOINT_PATTERNS) { - result = result.replace(pattern, replacement); - } - result = result.replace(BARE_NUMERIC_SEGMENT_RE, "/{id}"); - return origin + (hasLeadingSlash ? result : result.slice(1)); + const segments = path.split("/").filter(Boolean); + const apiIndex = segments.findIndex( + (segment, index) => segment === "api" && segments[index + 1] === "0", + ); + if (origin && apiIndex === -1) { + return origin + path; + } + // A path without /api/0 is relative to it. Keep a self-hosted install + // prefix before it. + const relative = apiIndex === -1; + const template = templateApiPath( + [API_PREFIX, ...segments.slice(relative ? 0 : apiIndex + 2)].join("/"), + ); + const prefix = segments + .slice(0, Math.max(apiIndex, 0)) + .map((segment) => `/${segment}`) + .join(""); + let result = relative ? template.slice(API_PREFIX.length) : prefix + template; + if (path.endsWith("/") && !result.endsWith("/")) { + result += "/"; + } + return origin || path.startsWith("/") ? origin + result : result.slice(1); } /** diff --git a/packages/cli/test/lib/error-reporting.test.ts b/packages/cli/test/lib/error-reporting.test.ts index e30a58fef..a01ae9f1b 100644 --- a/packages/cli/test/lib/error-reporting.test.ts +++ b/packages/cli/test/lib/error-reporting.test.ts @@ -158,83 +158,22 @@ describe("extractMessagePrefix", () => { // --------------------------------------------------------------------------- describe("normalizeEndpoint", () => { - test("parameterizes org slug in organizations path", () => { - expect(normalizeEndpoint("/api/0/organizations/my-org/issues/")).toBe( - "/api/0/organizations/{org}/issues/", - ); - }); - - test("parameterizes org and project in projects path", () => { - expect( - normalizeEndpoint("/api/0/projects/my-org/my-project/events/abc123/"), - ).toBe("/api/0/projects/{org}/{project}/events/{id}/"); - }); - - test("parameterizes issue, event, group, release IDs", () => { - expect(normalizeEndpoint("/api/0/issues/12345/")).toBe( - "/api/0/issues/{id}/", - ); - expect(normalizeEndpoint("/api/0/groups/99/events/abc/")).toBe( - "/api/0/groups/{id}/events/{id}/", - ); - expect(normalizeEndpoint("/api/0/releases/1.0.0/")).toBe( - "/api/0/releases/{version}/", - ); - }); - - test("parameterizes teams path", () => { - expect(normalizeEndpoint("/api/0/teams/my-org/backend/")).toBe( - "/api/0/teams/{org}/{team}/", - ); - }); - - test("parameterizes dashboards path", () => { - expect(normalizeEndpoint("/api/0/dashboards/42/")).toBe( - "/api/0/dashboards/{id}/", - ); - }); - - test("parameterizes customers path", () => { - expect(normalizeEndpoint("/api/0/customers/my-org/")).toBe( - "/api/0/customers/{org}/", - ); - }); - - test("parameterizes bare numeric segments", () => { - expect(normalizeEndpoint("/api/0/some/123/thing/456")).toBe( - "/api/0/some/{id}/thing/{id}", - ); - }); - - test("leaves paths without variable segments unchanged", () => { - expect(normalizeEndpoint("/api/0/auth/")).toBe("/api/0/auth/"); - }); - test.each([ - ["organizations/my-org/releases/", "organizations/{org}/releases/"], - [ - "projects/my-org/my-project/issues/?query=is:unresolved", - "projects/{org}/{project}/issues/", - ], - [ - "https://sentry.example.com/api/0/organizations/my-org/events/?field=title", - "https://sentry.example.com/api/0/organizations/{org}/events/", - ], [ - "https://sentry.example.com/sentry/api/0/organizations/my-org/", - "https://sentry.example.com/sentry/api/0/organizations/{org}/", + "/api/0/projects/my-org/my-project/events/abc123/", + "/api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/events/{event_id}/", ], [ - "/organizations/my-org/shortids/MY-PROJECT-1A/", - "/organizations/{org}/shortids/{id}/", + "organizations/my-org/releases/?per_page=1", + "organizations/{organization_id_or_slug}/releases/", ], [ - "organizations/my-org/monitors/my-monitor/", - "organizations/{org}/monitors/{monitor}/", + "https://sentry.example.com/sentry/api/0/organizations/my-org/issues/", + "https://sentry.example.com/sentry/api/0/organizations/{organization_id_or_slug}/issues/", ], [ - "organizations/my-org/alert-rules/123/", - "organizations/{org}/alert-rules/{id}/", + "organizations/my-org/not-an-endpoint/my-thing/", + "organizations/{organization_id_or_slug}/{id}/{id}/", ], ])("templates %s", (endpoint, expected) => { expect(normalizeEndpoint(endpoint)).toBe(expected); @@ -744,7 +683,7 @@ describe("reportCliError integration", () => { expect(tags["cli_error.api_status"]).toBe("400"); expect(tags["cli_error.kind"]).toBe("400"); expect(tags["cli_error.api_endpoint"]).toBe( - "/api/0/organizations/{org}/issues/", + "/api/0/organizations/{organization_id_or_slug}/issues/", ); });