Sentry

Sentry Documentation Audit

Sentry has a broad, agent-aware docs program — llms.txt, an MCP server, OpenAPI-style endpoint catalogs, and platform-specific SDK guides — but the substance is uneven: copy-paste examples ship with unrendered template markers, core API reference landing pages have lost their headings, the highest-trafficked CLI install page is pinned to a 2022 version, and several sidebar-linked pages are content-free stubs.

1. llms-full.txt returns 404 despite agent-friendly positioning (significant)

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

Problem: docs.sentry.io/llms.txt is served and tells AI assistants: "All documentation pages are available as clean Markdown by appending .md to any URL." Sentry has explicitly positioned itself as agent-friendly (skills, plugin, MCP server, llms.txt). However, the well-known companion convention https://docs.sentry.io/llms-full.txt returns HTTP 404. llms.txt does not itself advertise llms-full.txt — but the convention is widely indexed by agent tooling and Sentry's own framing implies a one-shot corpus access path.

Consequence: Agents that follow the community llms-full.txt convention (Cursor, Claude Code skills, Continue, etc.) fall back to crawling individual pages. That means more requests, slower indexing, partial context, and a higher chance the agent ends up using stale training-data answers — exactly what the llms.txt instructions warn against ("Do not rely on training data for Sentry setup or configuration").

The fix: Either serve llms-full.txt as a concatenated Markdown of the public docs, or explicitly document in llms.txt that the .md suffix trick is the only supported access path so agents don't waste a probe on the missing file.

2. Unrendered template placeholders leak into the user-facing React and Python guides (critical)

Location: https://docs.sentry.io/platforms/javascript/guides/react/ and https://docs.sentry.io/platforms/python/

Problem: The published React quickstart code block contains raw build-time markers in the file a developer is told to copy verbatim, including dsn: "___PUBLIC_DSN___", // ___PRODUCT_OPTION_START___ performance, // ___PRODUCT_OPTION_END___ performance, // ___PRODUCT_OPTION_START___ session-replay, // ___PRODUCT_OPTION_END___ session-replay, etc. The Python guide has the same problem (# ___PRODUCT_OPTION_START___ logs, # ___PRODUCT_OPTION_END___ logs, dsn="___PUBLIC_DSN___"). These are clearly internal templating tokens that should have been substituted or stripped at render time.

Consequence: A developer (or an AI agent following the page) who pastes the snippet ends up with comments like ___PRODUCT_OPTION_START___ performance in their production code, and a DSN literally set to the string ___PUBLIC_DSN___, which means the SDK silently fails to initialize. Because Sentry explicitly tells agents in llms.txt to "follow these guidelines" and use the docs as the source of truth, this is a copy-paste integrity failure on the most-trafficked install page.

The fix: Run the placeholder substitution before publishing, mark unfilled placeholders (e.g., <YOUR_DSN_HERE>) as required user input in a parseable convention, and add a CI check that fails the build if any ___[A-Z_]+___ token leaks into rendered HTML.

3. API Reference landing page has lost its section headings (significant)

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

Problem: The main API Reference index renders multiple empty ## headings — sections that should be titled "Versioning", "Endpoints", "Regional Domains", etc. all show up as blank H2s. The page reads as four disjoint paragraphs with no section anchors. Versioning is also stated only as "considered v0" with no policy on deprecation or breaking-change communication.

Consequence: Developers (and the search/agent tooling that crawls the page for anchors) can't find or link to the sections — the URL fragment for "Regional Domains" doesn't exist. Agents using the page to learn the API conventions get a structureless blob, and humans skimming it can't tell where one topic ends and the next begins.

The fix: Restore the section headings (something is clearly stripping H2 text — likely a Markdown front-matter or template bug) and add anchors for Versioning, Endpoints, and Regional Domains so agents and humans can deep-link.

4. Key sidebar-linked pages are empty stubs (significant)

Location: https://docs.sentry.io/concepts/key-terms/, https://docs.sentry.io/organization/authentication/, https://docs.sentry.io/security-legal-pii/scrubbing/

Problem: Three pages that are linked from the docs sidebar and from llms.txt have no body content beyond their title and subtitle:

• /concepts/key-terms/ — "Learn about important concepts that are essential to using Sentry." (no content)
• /organization/authentication/ — described as covering "single sign-on and two-factor authentication"; no content
• /security-legal-pii/scrubbing/ — "Learn more about scrubbing data using the Settings for your project and organization." (single sentence telling you to go look at the SDK docs instead)

Consequence: SSO/2FA is exactly the page an enterprise admin lands on after clicking through from llms.txt. Data scrubbing is a compliance-critical page. Hitting a content-free stub erodes trust and forces users to search elsewhere or open support tickets. Agents indexing the docs will cache these as real pages with no information.

The fix: Either write the content, or remove the pages from navigation and llms.txt until they exist. At minimum, add canonical "see also" redirects to the pages that actually contain the information.

5. sentry-cli install page is pinned to a stale version (significant)

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

Problem: Every example, the pinning snippet, and the entire checksum table all use v3.4.3:

• curl -sL https://sentry.io/get-cli/ | SENTRY_CLI_VERSION="3.4.3" sh
• A "Filename (v3.4.3) / Integrity Checksum" table listing sha384 hashes for that specific release
• The SENTRYCLI_SKIP_CHECKSUM_VALIDATION paragraph references a "Build Checksums page" with no link target

Consequence: Anyone who copies the pinning command pins to a version that is many releases behind. The checksum table is worse: if a user takes those sha384 values as canonical and validates a current binary against them, validation fails — there's no way to tell from the page whether the table is the latest checksums or a frozen example. And the "Build Checksums page" reference with no URL is a dead end.

The fix: Replace the hard-coded 3.4.3 with a build-time variable that always resolves to latest stable, label the checksum table as "example for v3.4.3" or rebuild it from the release registry, and link the "Build Checksums page" properly (or point to https://release-registry.services.sentry.io/apps/sentry-cli/{version} directly).

6. En-dash instead of double-hyphen breaks a copy-paste shell command (significant)

Location: https://docs.sentry.io/cli/send-event/

Problem: The logfile example renders as sentry-cli send-event -m "task failed" –-logfile error.log. The flag is prefixed with an en-dash followed by a hyphen (–-logfile) instead of two ASCII hyphens (--logfile).

Consequence: Pasted into bash/zsh, this produces "unknown option" errors. Agents that round-trip the snippet through text manipulation may preserve the typographic character and silently break the example. This is a textbook copy-paste-completeness failure for both humans and agents.

The fix: Configure the Markdown renderer to disable smartypants/typographer inside code blocks, and add a CI lint that rejects non-ASCII characters (especially en-dash/em-dash) inside fenced shell blocks.

7. Rate limit docs omit HTTP 429 and Retry-After, document only fixed window (significant)

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

Problem: The rate-limit page lists the custom X-Sentry-Rate-Limit-* response headers but never tells the developer what HTTP status code is returned when a request is rejected, whether the standard Retry-After header is set, what the concurrent-limit rejection looks like in body/status terms, or what the per-endpoint defaults are. It also describes only a single "fixed window" strategy with no token bucket or sliding window backoff guidance, even though it says "Each endpoint has its own maximum number of requests and window size" — none of which are documented anywhere visible.

Consequence: Developers writing API clients have to discover the rejection status code by tripping it in production. Without Retry-After semantics or per-endpoint limits, every client implements ad hoc backoff. Agents writing API client code will guess 429 + Retry-After (the convention) and may be wrong.

The fix: Document the rejection status code (likely 429), state whether Retry-After is honored, link to a per-endpoint limits table (or publish one), and describe what concurrent-limit rejections look like distinctly from per-second limits.

8. API Requests page uses a 2015-dated example and omits timeout/retry/idempotency contract (significant)

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

Problem: The "Requests" page — the canonical landing for API mechanics — uses a literal example response with Date: Sat, 14 Feb 2015 18:47:20 GMT, which is the only timestamp anywhere on the page. The page documents the HTTP verbs and JSON Content-Type but never addresses: timeouts (server-side or recommended client-side), retry policy, idempotency keys (for POST/PUT), or content negotiation beyond application/json. The Pagination page (/api/pagination/) carries the same 2015 timestamp in its example, so the entire "API basics" cluster reads like it was last touched a decade ago.

Consequence: Developers writing API clients have no documented contract for how to retry a POST safely, whether a 502 means "try again" or "the call may have succeeded," or how the server behaves under partial failure. Agents generating client code will invent defaults. The 2015 timestamp also signals "this page is unmaintained," which discourages trust even where the content is current.

The fix: Regenerate the example timestamp at build time (or use a static "2024-01-01" with a note). Add a "Request semantics" section that covers timeouts, retry guidance, idempotency for write operations, and any non-JSON content types the API accepts.

9. Events & Issues and Projects API landing pages are link-less bullet lists (significant)

Location: https://docs.sentry.io/api/events/ and https://docs.sentry.io/api/projects/

Problem: Both landing pages render as a flat bullet list of endpoint titles (e.g., "List a Project's Issues", "Bulk Mutate a List of Issues", "Create a New Client Key") with no descriptions, no HTTP method indicators, no path templates, and — critically — no inline links to the individual endpoint pages. Compare with the much smaller /api/auth/ and /api/ratelimits/ pages, which are dense and complete.

Consequence: A developer landing on /api/events/ has to either search the docs again or guess URL paths to find the actual endpoint docs. Agents crawling the page index will record a flat list of titles with no targets, making the Events and Projects sections functionally invisible to RAG pipelines.

The fix: Render each bullet as a real link to its endpoint page, add the HTTP method and path next to each title (e.g., GET /api/0/projects/{org}/{project}/issues/), and ideally publish a machine-readable OpenAPI catalogue from the same source.

10. Pricing quotas matrix has been flattened — Action × Data Category mapping is broken (significant)

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

Problem: The "What does and doesn't count toward your quota" section and the preceding "Action × Data Category" matrix render as vertical lists of column labels (Errors, Spans, Replays, Attachments, Logs, Application Metrics) followed by scenario rows where checkmarks float without a clearly preserved column anchor. A reader trying to determine, e.g., "does enabling spike protection apply to attachments?" has to count checkmarks against a header that's no longer aligned. The same problem affects the "Scenario / Yes, this data counts" table for repeated events.

Consequence: This is a billing comprehension page — developers and finance teams use it to decide whether to upgrade plans or rate-limit their SDKs. When the column-to-checkmark mapping is unreliable, customers will either over- or under-provision. Agents parsing the page for "what counts against my quota" will pick up labels and checkmarks in the wrong association.

The fix: Re-render the matrix as a proper HTML table with explicit <th> headers, or convert each row to "Action: X — applies to: Errors, Spans" prose so the mapping is unambiguous. Until that's fixed, add a callout pointing readers to the per-category subpages for authoritative answers.

11. Auth tokens page contradicts itself on Personal Token visibility (significant)

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

Problem: The page says of Organization Tokens: "For security reasons, organization tokens are only visible once, right after you create them." But the section on Personal Tokens immediately below says: "Currently, you can view personal tokens in the UI after creating them. This is a legacy behavior that may change in the future. We recommend only using each personal token once, and creating a new token for each use case."

Consequence: Two token types in the same product follow opposite policies, and the doc explicitly tells you the looser one "may change in the future" without specifying when, how, or with what migration path. Anyone building automation around personal tokens has to plan for both possibilities. Security reviewers reading this will (correctly) flag the personal-token UX as unsafe but can't determine if it's a documented intentional behavior or a known-bad legacy.

The fix: Either commit to a deprecation date and add it to the page, or document explicitly that the visibility behavior is stable. In either case, surface the contradiction up-front in a "Token type comparison" table so the difference is obvious instead of buried.

12. Dynamic Sampling page lists outdated SDK minimums and ships a broken sentence (significant)

Location: https://docs.sentry.io/organization/dynamic-sampling/

Problem: Two problems on one page:

1. The "minimum SDK versions" list reads "Python: 1.7.2 or later, JavaScript: 7.6.0 or later, Apple: 7.23.0 or later…" — these are 2022-era minimums, while the current SDK majors (per the React quickstart and the npm registry) are well past these numbers. The page never says when the list was last reviewed.

2. The page contains a clearly mangled sentence: "Additionally, advanced mode is not active, Dynamic Sampling continuously monitors the traffic for each project and adjusts the sample rate of each to prioritize the most relevant data." — a missing "when" makes the conditional clause meaningless.

Consequence: Customers on current SDK versions may assume they're not eligible because they don't recognize the old version numbers, or assume the page is stale and ignore other guidance on it. The mangled sentence reads as if it's documenting the opposite of the intended behavior.

The fix: Replace the static minimum-version list with a "Sentry SDK ≥ X" table generated from the supported-features matrix, and rewrite the sentence to "When advanced mode is not active, Dynamic Sampling continuously monitors…" (or whatever the intended condition is).

13. sentry-cli configuration page has ini-only settings with no env var and vague defaults (significant)

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

Problem: The settings reference is introduced as "first is the environment variable, the value in the parentheses is the config key in the config file" — but several rows have only the ini key in parentheses and no environment variable at all: http.keepalive, http.proxy_username, http.proxy_password, http.verify_ssl, dif.max_upload_size, dif.max_item_size. The dif.max_upload_size entry also reads "The default is 35MB or 100MB (depending on the version of sentry-cli)" with no table mapping version → default. The http_proxy entry warns that the env var is honored "Note that it is lowercase" — a known footgun on Windows and in CI shells where casing varies.

Consequence: Anyone configuring sentry-cli in a CI environment (the dominant use case) cannot set proxy auth or SSL verification via env var, but the page doesn't say so explicitly — it just omits the env column. The "35MB or 100MB depending on version" wording means a user uploading debug symbols can't tell from the docs whether their current install will split bundles or not.

The fix: Add an explicit "ini-only" badge or column to rows without an env var, document the version cutoff for the 35MB → 100MB default, and surface the lowercase http_proxy requirement as a callout box (not a trailing sentence in the description).

14. Monitors and Alerts page contains a self-referential link (minor)

Location: https://docs.sentry.io/product/monitors-and-alerts/

Problem: The page tells the reader: "For a concise Issues-centric explanation (how this shows up in your triage flow), see Monitors and Alerts." That link target is the same page the user is currently reading.

Consequence: Readers click a link that does nothing; agents follow it into a loop.

The fix: Point the "Issues-centric explanation" link at the actual Issues-side page (likely /product/issues/ or a sub-page).

15. Two competing CLI commands shown for Sentry Agent Skills without preference (minor)

Location: https://docs.sentry.io/ai/agent-skills/

Problem: The page shows both npx skills add getsentry/sentry-for-ai --skill sentry-fix-issues and npx @sentry/dotagents add getsentry/sentry-for-ai --name sentry-fix-issues for what appears to be the same action. The page never explains which tool is canonical, when to prefer one over the other, or whether they produce equivalent outputs. The per-client paths table also mixes plural and singular directory names across editors (~/.claude/skills/, ~/.config/opencode/skill/, ~/.config/agents/skills/) — that inconsistency is in upstream tools, but the docs need to flag it so users don't typo their own filesystem paths.

Consequence: First-time users guess which command to run. Agents reading the page may pick either, leading to inconsistent skill management within a single team.

The fix: Pick one recommended path (likely @sentry/dotagents given it's the lockfile-aware option) and demote the other to a "Manual / one-off" subsection. Add a callout next to the path table noting the skill vs skills discrepancy in OpenCode vs the rest.

16. Changelog has no dates and many empty "Modified" sections (minor)

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

Problem: The Documentation Changelog renders entries with titles like "docs(java): Add cache tracing integration pages" and "feat(Dashboards): Added new markdown widget docs" but no timestamps anywhere, and most entries have an "Added:" or "Modified:" header with no items underneath.

Consequence: Developers checking whether a known bug or doc gap has been fixed can't tell when an entry landed or what page actually changed. Agents using the changelog to verify currency of cached content get no useful signal.

The fix: Restore the date for each entry, and either populate the "Modified:" lists with the actual pages affected or hide the header when empty.

17. Relocation guide contains "you'll should" typo and dated examples (minor)

Location: https://docs.sentry.io/concepts/migration/

Problem: The final step in the SaaS migration guide reads: "Once you complete this step, you'll should start to see issues and events…". The page also explains relocation eligibility using a hardcoded sample version pair ("if the latest self-hosted release is version 24.2.3, your self-hosted install must be on at least version 24.1.0") which dates the page and forces re-reading every quarter.

Consequence: Minor credibility hit; the version example will go stale and confuse users on more recent self-hosted releases who don't see their own version numbers in the example.

The fix: Fix the typo. Replace the hardcoded version-pair example with the rule expressed in terms of "the latest two minor releases on the self-hosted release page" with a link.

What they do well

• Strong agent-first positioning: llms.txt exists, advises agents to avoid stale training data, points to the MCP server, and ships a plugin and skill registry. Most peers don't do any of this.
• Auth scopes are tabularized cleanly (/api/permissions/) — methods → required scopes in a parseable table, exactly what agents need.
• Data residency page is unusually honest (/organization/data-storage-location/) — calls out exactly which categories of data are stored only in the US even for EU customers, and which are unrecoverable when relocating.

Top 3 recommendations

1. Fix the copy-paste contract: strip ___PRODUCT_OPTION_START___ / ___PUBLIC_DSN___ markers from rendered pages, replace en-dashes inside fenced shell blocks with ASCII hyphens, and add a CI lint that rejects both. These two fixes alone make every copy-paste example trustworthy for both humans and agents.
2. Make the API reference parseable: restore the missing H2 headings on /api/, regenerate the 2015 timestamp on /api/requests/ and /api/pagination/, link the bullet lists on /api/events/ and /api/projects/ to their endpoint pages, and add the rejection-status-code + Retry-After semantics to /api/ratelimits/.
3. Delete or finish the stub pages and fix the quotas matrix: /concepts/key-terms/, /organization/authentication/, and /security-legal-pii/scrubbing/ should either get real content or be removed from navigation and llms.txt. Re-render /pricing/quotas/ as a real HTML table so the Action × Data Category mapping is unambiguous — this is a billing-decision page.