Sentry

Sentry Documentation Audit

Sentry's docs are broad, .md-mirrored, and llms.txt-aware — genuinely ahead on machine-readability. But the parts a developer copies verbatim (a JS quickstart, a DSN host, an auth-token location) carry concrete contradictions and outright broken code, a CLI security page mislabels its own checksum algorithm, and several high-stakes landing pages (security, data scrubbing, concepts) are stubs that defer elsewhere and never deliver.

1. CLI install page labels its checksums SHA256 in prose but prefixes every value sha384- (significant)

Location: https://docs.sentry.io/cli/installation/

Problem: The prose says the integrity checks are SHA256 three times — "in a form of hash, in our case SHA256," "the table of SHA256 checksums," and "you can use sha256sum utility." But every entry in the table is prefixed sha384-, e.g. sentry-cli-Darwin-arm64 → sha384-583827dcf9db3f2489c1145644b3f404e5d888c92f535062568344cb30a816a4. The digest itself is 64 hex characters — the length of a SHA-256 hash (a real SHA-384 digest is 96 hex chars) — so the prose, the recommended sha256sum utility, and the actual value all agree on SHA-256; only the sha384- label prefix is wrong.

Consequence: A developer verifying the download sees a sha384- prefix while the page tells them to run sha256sum, with no signal about which is authoritative. If they strip the prefix and compare the 64-char hex against sha256sum output it can match — but the contradictory label undermines trust in the exact security step the page exists to teach, and anyone who takes the sha384- prefix literally (e.g. runs sha384sum, whose 96-char output can never equal a 64-char value) gets a guaranteed mismatch and a false "binary compromised" alarm.

The fix: Change the table's sha384- prefix to sha256- (or drop the prefix entirely), leaving the prose and the sha256sum instruction as-is. Do not rewrite the prose to say SHA-384 — that would tell users to run sha384sum against 64-char SHA-256 values and break verification. (Separately, the table and install command are pinned to a single stale version, v3.4.3; lean on the release-registry link the page already provides.)

2. JavaScript quickstart imports from a placeholder package, not the one it just told you to install (critical)

Location: https://docs.sentry.io/platforms/javascript/

Problem: The page instructs npm install @sentry/browser --save, then the very next "npm example" opens with import * as Sentry from "<sdk-package-name>";. The placeholder <sdk-package-name> is never replaced with @sentry/browser.

Consequence: Copy-paste — the whole point of a quickstart, and the default behavior of an AI coding agent extracting the snippet — yields Cannot find module '<sdk-package-name>'. An agent has no way to infer the correct package from the string, because it's not marked as a placeholder in any structured way; it will emit code that fails at build time.

The fix: Replace "<sdk-package-name>" with "@sentry/browser" in the browser example (and audit sibling platform pages for the same templating leak).

3. Tracing verification snippet uses await inside a non-async function (significant)

Location: https://docs.sentry.io/platforms/javascript/

Problem: The "Break the World" tracing example declares function triggerError() { await Sentry.startSpan(... ) } — await is used at the top level of triggerError, but the function is not marked async (only the inner callback is).

Consequence: This is not a runtime edge case — it's a SyntaxError: await is only valid in async functions, so the <script> block fails to parse and the button does nothing. A developer testing their install gets no error event and wrongly concludes Sentry isn't wired up.

The fix: Declare the outer function async function triggerError(), or drop the outer await and let startSpan run without awaiting it.

4. Personal auth tokens have two different documented creation locations (significant)

Location: https://docs.sentry.io/api/auth/ vs https://docs.sentry.io/account/auth-tokens/

Problem: The API auth reference says personal tokens "can be created within Sentry on the 'User settings' page (User settings > Personal Tokens)." The Auth Tokens overview says personal tokens "can be created in sentry.io on the Personal Tokens page under the Account dropdown in the top left." These are two different navigation paths for the same action.

Consequence: A developer following one page hunts for a "User settings" page that the other page calls the "Account dropdown," wasting time and losing confidence in the docs during the very first step of API onboarding. An agent reconciling the two pages gets conflicting instructions with no signal about which is current.

The fix: Verify the actual UI location and make both pages use identical wording for the navigation path.

5. Region base domains are documented, but every auth example and the DSN template hardcode the non-regional host (significant)

Location: https://docs.sentry.io/api/ (regions) vs https://docs.sentry.io/api/auth/ and https://docs.sentry.io/platforms/javascript/

Problem: The API overview documents region-specific base domains — "US: us.sentry.io, US2: us2.sentry.io, DE: de.sentry.io" — and says a region-specific domain "can lower latency," with your region shown on the org settings page. But every auth example hardcodes the plain sentry.io host (curl -u {API_KEY}: https://sentry.io/api/0/organizations/{organization_slug}/projects/, https://sentry.io/oauth/authorize/...), and the JS quickstart's DSN template hardcodes https://<key>@o<orgId>.ingest.sentry.io/<projectId> with no regional ingest variant.

Consequence: A developer who copy-pastes the examples verbatim sends API traffic and event ingestion to the default host instead of the regional endpoint — giving up the lower latency the region docs promise and, for an EU region like DE, routing data through a host other than the one the customer deliberately selected. Nothing in the copyable snippets signals the host should change per region, so an agent or a developer following the quickstart never learns they had a choice.

The fix: Show region-parameterized hosts in the examples (e.g. a {region}.sentry.io / region-specific ingest placeholder marked as such), or add an inline note on the auth and DSN examples pointing to the region table and stating when the host must be swapped.

6. Security & Legal landing page is a two-link stub that still advertises Privacy Shield (significant)

Location: https://docs.sentry.io/security-legal-pii/security/

Problem: The page a reader lands on for security is one intro line plus two links, with no SOC 2, GDPR, sub-processor, or data-retention detail present inline. It also states "We also maintain a Privacy Shield Certification" — the EU-US Privacy Shield framework was invalidated by the Schrems II ruling in 2020.

Consequence: For a monitoring product that ingests error payloads and PII, security is a purchase-blocking evaluation. A reviewer lands on a near-empty page and a compliance claim tied to a defunct framework, which reads as stale at best and misleading at worst — exactly the wrong signal during a vendor security review.

The fix: Remove or replace the Privacy Shield reference with the current transfer mechanism (e.g., SCCs / Data Privacy Framework as applicable), and surface the core compliance facts (SOC 2, GDPR, retention, sub-processors) on the landing page rather than only behind links.

7. Rate Limits page documents the headers but states no numeric limits (significant)

Location: https://docs.sentry.io/api/ratelimits/

Problem: The page explains the X-Sentry-Rate-Limit-* headers and says "Each endpoint has its own maximum number of requests and window size," but never gives a single concrete number — no per-endpoint limit, no default, no concurrent cap.

Consequence: A developer sizing a polling loop or batch job has nothing to design against and must reverse-engineer limits from 429s in production. The page even recommends webhooks "if possible" but leaves polling users with zero quantitative guidance.

The fix: Publish concrete limits (or a representative table by endpoint category), or link to a live per-endpoint limits reference. At minimum, document the default requests-per-second and concurrent ceilings.

8. "Data Scrubbing" and "Data Management" pages promise server-side options, then list none (significant)

Location: https://docs.sentry.io/security-legal-pii/scrubbing/ and https://docs.sentry.io/concepts/data-management/

Problem: The Data Scrubbing page says "This page documents only the server-side options" but its body is two sentences that defer to "the SDK documentation" and contains no server-side options. The Data Management page's own description promises "issue grouping, data forwarding, and inbound filters," then repeats the same defer-to-SDK stub with none of them.

Consequence: A developer trying to configure server-side PII scrubbing — a compliance requirement — arrives at the page that explicitly claims to cover it and finds nothing, with a redirect to SDK docs that the page itself says are out of scope. This is a dead-end loop on a sensitive topic.

The fix: Populate these pages with the actual server-side controls (data scrubbing rules, safe fields, inbound filters, data forwarding). At minimum, redirect to the pages that actually document server-side scrubbing — the Relay overview (https://docs.sentry.io/product/relay/) explicitly describes Sentry scrubbing PII "in two places" (in the SDK, and on arrival at Sentry's infrastructure) with Relay adding a "third" central option — instead of leaving a self-contradicting stub that points back to the SDK docs it says are out of scope.

9. Pricing quota "quick reference" table has broken/missing checkmark labeling (significant)

Location: https://docs.sentry.io/pricing/quotas/

Problem: The table titled "what does and doesn't count towards your quota" renders with only a "Yes, this data counts" column and no "No, doesn't count" column header, and checkmarks appear on only some rows. As shown, "Spike protection no longer active (errors) ✓" and "This is a repeated event for an issue that you've set to Ignore ✓" both carry checkmarks, while "Your quota has been exceeded" and "A rate limit for a project has been applied" have none — leaving it ambiguous whether a blank means "doesn't count" or "unlabeled."

Consequence: Billing behavior is exactly where ambiguity costs money. A developer can't tell whether ignored/rate-limited/over-quota events are billable, and the table's structure gives no reliable way to read the "no" cases.

The fix: Restore both column headers and put an explicit marker in every cell (✓ / ✗), so each scenario has an unambiguous counts / doesn't-count value.

10. API index pages list endpoint titles with no methods, paths, schemas, or scopes (significant)

Location: https://docs.sentry.io/api/seer/ and https://docs.sentry.io/api/crons/

Problem: The Seer API index shows only three titles ("List Seer AI Models," "Retrieve Seer Issue Fix State," "Start Seer Issue Fix") with no HTTP methods, URL paths, request/response schemas, or required scopes at the index level. The Crons index has the same shallow shape and additionally lists near-duplicate operations ("Delete a Monitor…" vs "Delete a Monitor… for a Project," "Retrieve Check-Ins for a Monitor" vs "…by Project") with nothing to disambiguate which to use.

Consequence: An AI agent (or a human) scanning the index can't discover how to call anything without opening each detail page one at a time, and for Crons can't tell the project-scoped from org-scoped variant. For a prominently marketed feature like Seer, the index is effectively undiscoverable programmatically.

The fix: Show method + path (and ideally required scope) on each index row, and add a one-line "use this when…" note distinguishing the project-level vs organization-level Crons variants.

11. llms-full.txt 404s even though llms.txt advertises a full section index (significant)

Location: https://docs.sentry.io/llms-full.txt

Problem: https://docs.sentry.io/llms.txt exists and enumerates the full documentation surface, but the conventional full-text companion https://docs.sentry.io/llms-full.txt returns {"error":"page_not_found","status":404}.

Consequence: Many AI ingestion tools probe for llms-full.txt to pull the entire corpus in one request. Its absence means agents fall back to fetching hundreds of individual .md files (or hit a hard 404 and stop), undercutting the machine-readability the llms.txt file signals is supported.

The fix: Either publish a real llms-full.txt, or, if it's intentionally unsupported, ensure the llms.txt doesn't imply a full-text variant and return a clean signal rather than a bare 404.

12. Concepts landing page shows only a title in HTML while the .md mirror has the full sub-page list (significant)

Location: https://docs.sentry.io/concepts/key-terms/ vs https://docs.sentry.io/concepts/key-terms.md

Problem: The rendered HTML "Concepts" page contains only a title and one-sentence description with no body links. The .md mirror of the same URL lists the entire section — Key Terms & Features, DSN, Sample Rates, Environments, Event Data, Tracing, Extrapolation — under a "Pages in this section" heading.

Consequence: A human browsing the site sees a dead-end landing page and can't navigate to the concept pages that actually exist; the content is only reachable via the .md variant or direct URL. The two representations of the same page disagree on what's on it.

The fix: Render the "Pages in this section" list on the HTML page so it matches the .md mirror. (Separately, note the page title is "Concepts" while the slug is key-terms — worth aligning to avoid confusion.)

13. Personal-token scope editability is stated as immutable, with a grammar error and a conflicting "viewable after creation" note (minor)

Location: https://docs.sentry.io/api/permissions/ and https://docs.sentry.io/account/auth-tokens/

Problem: The Permissions page says integration-token scopes "can be edited later" but "for an personal token… These cannot be edited later" (also note "an personal token"). Meanwhile the Auth Tokens page says personal tokens remain viewable in the UI after creation as "a legacy behavior," whereas organization tokens "are only visible once."

Consequence: A developer can't tell from one page whether they can adjust a personal token's scopes or must recreate it, and the differing visibility rules for token types are easy to miss. The typo undercuts polish on a security-sensitive reference.

The fix: Fix "an personal token" → "a personal token," and state the scope-immutability and post-creation visibility rules for each token type consistently across both pages.

14. Pagination reference uses a decade-old example and never states default/max page size (minor)

Location: https://docs.sentry.io/api/pagination/

Problem: The example response carries Date: Sat, 14 Feb 2015 18:47:20 GMT, and the page defines the cursor triple but never documents the default or maximum page size (examples merely imply 100).

Consequence: A developer implementing pagination can't size requests or validate behavior against a stated maximum, and the stale date signals the page hasn't been reviewed recently.

The fix: Refresh the example and state the default and maximum per_page/cursor page size explicitly.

15. Documentation changelog entries have empty Added/Modified/Removed labels (minor)

Location: https://docs.sentry.io/changelog/

Problem: Many entries render Added: / Modified: / Removed: labels with no page list beneath them (e.g. "docs: add Xurrent IMR and Shiprail to third-party integrations — Modified: [empty]"), and most entries show no date. The changelog reads as a list of PR titles rather than a usable record of what changed.

Consequence: A reader (or agent) can't tell which pages a given change touched or when, so the changelog can't be used to track doc drift or verify that a fix landed.

The fix: Populate the Added/Modified/Removed lists with the actual affected pages and attach a date to each entry, or drop the empty labels.

What they do well

• Machine-readable by default: every path has a .md mirror and an llms.txt section index exists — real investment in agent consumption, even if llms-full.txt is missing.
• Auth token model is well-segmented: the three token types (org, internal integration, personal) are clearly distinguished with scope/permission boundaries and CI guidance.
• Rate-limit headers and cursor-pagination mechanics are precisely specified, giving clients a concrete contract to build against (once the missing numbers are added).

Top 3 recommendations

1. Fix the copy-paste-critical defects first: the placeholder <sdk-package-name> import (#2) and the await-in-non-async SyntaxError (#3) both fail the exact "run it unmodified" test that new developers and AI agents rely on — and correct the mislabeled sha384- checksum prefix (#1) so the verification instructions are internally consistent.
2. De-stub the security and data pages: remove the invalidated Privacy Shield claim and populate the Security, Data Scrubbing, and Data Management landing pages — or at minimum point them at Relay, where server-side scrubbing actually lives (#6, #8) — since these block vendor security reviews.
3. Make examples region-aware and deepen the API indexes for agents: parameterize hosts so EU customers don't silently ship to the default region (#5), put method + path + scope on every API index row, and reconcile cross-page contradictions (auth-token location #4, token scope editability #13) so programmatic consumers get one consistent answer.