sentry-mcp-queries

Sentry MCP Queries

When To Use

• Investigating a production error before attributing root cause
• Checking dist (MV3 vs MV2) error distribution
• Estimating event or span volume from production data
• Comparing error rates release-over-release for regression detection
• Retrieving session replay or profiling data

Do Not Use When

• The error reproduces locally with a full stack trace
• Reading product analytics (Segment events, not Sentry errors/spans)
• Pre-merge investigation — Sentry data is post-merge only

Setup

Run once per session:

mcp__sentry__whoami            → confirm auth
mcp__sentry__find_organizations → org slug
mcp__sentry__find_projects     → project slug(s)

All subsequent tools require organization_slug and usually project_slug. Slug mismatch causes silent empty results. A filter on an attribute the dataset does not carry also returns an empty result with no error, so run the query without that filter as a control before reading a zero. mcp__sentry__search_events returns at most 100 rows per call, has no cursor, and accepts only a relative period such as 90d.

Workflow: Error Triage

1. mcp__sentry__search_issues — find by title, fingerprint, or keyword. An issue is a grouping bucket, not a fault: Sentry groups by stack trace, which the issue list does not return, so two issues with matching titles are not shown to be one fault.
2. mcp__sentry__get_issue_tag_values — check dist distribution before attributing root cause. An error's tag distribution does not reflect the user population's, so also compare count_unique(user.id) by that tag.
3. If 99%+ one dist → platform lifecycle root cause (see extension-errors-debugging)
4. mcp__sentry__search_issue_events — individual events for stack trace detail
5. mcp__sentry__analyze_issue_with_seer — AI-assisted hypothesis (validate against code)

Workflow: Volume Estimation

Segment event volume is invisible from Sentry, but a correlated http.client span is not. Anchor estimation on an HTTP endpoint the event's controller calls 1:1 with the event firing.

1. Identify the correlated endpoint — the one that fires once per event, not per sub-call (e.g. a per-init call, not a per-account call). Picking a per-sub-call endpoint over-counts.
2. mcp__sentry__search_events aggregate mode, filter span.op:http.client + endpoint
3. Read the count() aggregate. Span datasets already extrapolate it by each span's sample weight (see Longer-Range (30D+) Queries and Percentile Fidelity), so it is the volume estimate.
4. Do not multiply it by 1 / tracesSampleRate. That extrapolates twice, and the weight Sentry applies can differ from the configured rate (a per-name sampler rate, a remote override, a trace continued as sampled).
5. Treat as an upper bound — the endpoint may have callers beyond the event path. Sample population = MetaMetrics-opted-in users only (Sentry opt-in is tied to MetaMetrics).

Workflow: Release Comparison

Compare error rates or metrics across releases for regression detection:

1. mcp__sentry__find_releases — list releases sorted by date
2. Filter out unreliable releases (see below) before comparing
3. mcp__sentry__search_events with release:12.5.0 for baseline
4. mcp__sentry__search_events with release:12.6.0 for comparison
5. Normalize by sessions or users — raw counts conflate traffic changes with error rate changes:

   rate = events / sessions_for_that_release
   

6. Report delta against baseline with sample-size caveat

Sentry's Endpoint Regression detector checks p95 transaction duration only for server operations (http.server, serverless.function, asgi.server, rails.request, function.aws, function.aws.lambda), so a browser transaction such as pageload gets no automatic regression issue and needs this comparison.

Filtering Unreliable Releases

Patch releases have uneven adoption — comparing raw counts against them produces false signal. Skip a release before comparing if:

Filter	Threshold	Reason
Age since publish	< 48–72h	Browser auto-update rollout still ramping (Chrome/Firefox/Edge)
Session count	< ~50% of previous stable release	Sample too small for meaningful rates
Stored span count	< ~few hundred for p75, < ~few thousand for p95+	Tail percentiles are computed over the stored sample — extrapolated counts hide how few events back them
Superseded patch	a higher patch in the same X.Y.* line exists and the active window (first_seen→last_seen) is short	Hotfixed-past releases collect few spans, biased to early-updaters during the rollout/migration window
Release stage	dev, canary, nightly	Non-production build — different error profile
Environment	not production	Development / staging noise
Manifest split	compare only within same dist	MV3 and MV2 populations have different error distributions

Rule of thumb: use the newest release that has ≥ 3 days of production adoption and session volume comparable to the previous stable release. Everything in between is hotfix noise — skip it for regression comparisons unless investigating that specific patch.

Longer-Range (30D+) Queries and Percentile Fidelity

Widening the window past ~30 days to gain sample size trades it back for fidelity loss on older releases. Three effects compound:

• Sample-rate drift — tracesSampleRate changes between releases, so absolute span counts across a 30D+ window mix different capture rates. Normalize each release by its own sample rate (or by sessions/users), never a single global rate.
• Extrapolation hides thin samples — span datasets report sample-rate-weighted (extrapolated) counts. A release with 40 stored spans at 0.75% extrapolates to ~5,300 — a real-looking number backed by 40 events. Always check the stored sample count (count_sample()), not the extrapolated total, before trusting a release. A group backed by a single stored span reports that span's extrapolation weight, not 1, so a per-entity ranking at high cardinality (groupBy trace, user or session) or a ratio such as count() / count_unique(trace) measures sample weight rather than volume. For one trace's stored span count, read GET /api/0/organizations/{org}/trace-meta/{trace_id}/?project=-1&statsPeriod=<window>, which does not extrapolate.
• Retention downsampling — spans near the retention boundary are partially evicted, so an old release's count is truncated, not representative. Treat the oldest releases in a 30D+ window as lower bounds only. Span listings over a long window undercount as well, not only aggregate counts.

For p75+ analysis (any tail percentile — p75/p90/p95/p99), sample size and quality both matter:

• Size — percentiles are computed over stored events. p50 stabilizes in the low hundreds; p75 needs more; p95/p99 need thousands of stored spans. Below that, a handful of outliers move the number — don't report a tail percentile you can't back with stored count.
• Quality — rollout-window spans (first-launch, cold cache, state migration) skew the tail high. A superseded patch release's spans are disproportionately these, so its p75+ reads worse than its steady state would. In the extension project, 84.8% of span.op:pageload transactions were measured as not user-visible page loads, and the service worker's pageload adopts every request made before finalTimeout as a child. Scope a pageload percentile by transaction name.

Resolving the size-vs-fidelity tension: when a single release lacks the sample to support p75+, collapse the patch chain — aggregate release:X.Y.* across the minor line, or compare against the last widely-adopted patch — rather than extending the window into aged, downsampled, sample-rate-drifted territory. Reach for sample size across adjacent stable patches inside the retention-safe window, not by going further back in time. Use a longer (90d) window as the primary, comparable-across-releases source for p75/p95 and a 30d window only as secondary context — 30d over-weights the users still lingering on old versions and inflates baselines. A 90d query has returned meta.dataScanned: partial from the events API, meaning Sentry scanned only part of the window, and the mcp__sentry__search_events output does not show that field.

For attributing a confirmed p75/p95 movement to specific code changes, see the performance-attribution skill.

Workflow: Replay and Profile

1. mcp__sentry__search_issue_events — find an event ID with replay/profile
2. mcp__sentry__get_replay_details / mcp__sentry__get_profile_details for that event ID

The extension's setupSentry.js configures no profiling integration or profilesSampleRate, and browser profiling needs a Document-Policy response header that an MV3 extension cannot set, so the extension has no profiles to retrieve.

Tag Filters

Tag	Values	Use
dist	mv3, mv2	Isolate by manifest version
environment	production, staging	Exclude non-prod noise
installType	normal, development, sideload, admin	Exclude developer-loaded builds

Do not conflate environment and installType — a production build can have installType:development if loaded unpacked.

Common Pitfalls

Mistake	Correct Approach
Attribute root cause before checking dist distribution	Check tag values first — 99%+ MV3 → lifecycle, not app logic
Multiply a span count() by 1 / tracesSampleRate	count() is already extrapolated, so read it as the estimate
Filter environment:development for dev builds	Filter installType:normal — environment ≠ install method
Skip whoami and guess org slug	Slug mismatch causes silent empty results
Treat Seer analysis as ground truth	Use as hypothesis to validate against code/traces
Compare raw event counts across releases	Normalize by sessions — traffic changes masquerade as regressions
Include a <48h-old release in a regression comparison	Wait for rollout; auto-update adoption takes 2–7 days
Treat every patch release as a comparison point	Most patches have low adoption — compare to the last widely-adopted release
Treat a release absent from a sort:-count() top-N result as filtered out	It fell below the volume cut, which is not an exclusion. Query it by name
Trust a release's p95 because its (extrapolated) span count looks large	Check the stored sample — p75+ needs hundreds-to-thousands of stored events to be stable
Compare span counts across a 30D+ window at face value	Normalize per-release sample rate; older releases are downsampled / retention-truncated
Read the newest minutes of a window that ends now as complete	Ingestion lag was measured at ~14 min, so those minutes read low
Anchor a percentile on a .0 release	.0 releases have 10–100× fewer samples — use the highest-sample patch in the minor line