Skip to content

docs: Update troubleshooting guide for 8.0 and add Cloud troubleshooting page - #2085

Open
enriquegh wants to merge 4 commits into
mainfrom
enrique/troubleshooting-accuracy
Open

enriquegh wants to merge 4 commits into
mainfrom
enrique/troubleshooting-accuracy

Conversation

@enriquegh

@enriquegh enriquegh commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Checked https://sourcegraph.com/docs/self-hosted/observability/troubleshooting against [email protected], sourcegraph/zoekt, and deploy-sourcegraph-k8s, and added a troubleshooting page for Sourcegraph Cloud.

Self-hosted troubleshooting guide (8.0 accuracy)

  • Removed: "Sourcegraph 3.14 / older" instructions and the "Gitserver rev2" dashboard. The page now uses the current gitserver: echo_command_duration_test alert (20ms+ for 30s) and the "Git commands running on each gitserver instance" panel.
  • Removed the USE_ENHANCED_LANGUAGE_DETECTION=false "solution". The variable no longer exists in the codebase; it dates from 3.11.
  • Removed steps for features that no longer exist: single-container debug logs (deployment removed in 7.0), the search-timeouts Grafana gist (returns 404), and the "Sourcegraph Internal > HTTP" dashboard and its QPS panels.
  • Fixed the gitserver disk metric: gitserver_disk_free_percent is now src_gitserver_disk_space_available / src_gitserver_disk_space_total.
  • Updated UI paths to the 8.0 UI: /site-admin/report-bug is now /user/settings/report-bug, and /site-admin/repositories is now /admin/repositories (/site-admin/* only redirects). /site-admin/usage-statistics no longer exists, so usage stats now point to Sourcegraph Analytics. The status notifications and Code host connections page replace the "cloud icon".
  • cAdvisor: the page linked to a "namespaced overlay" that doesn't exist. It now links to Filtering cAdvisor metrics.
  • Fixed 4 broken anchors: #Logs, #accessing-prometheus, and #accessing-jaeger (twice).
  • Other updates:
    • count:999999 is now count:all.
    • The x-trace-url header is documented.
    • The max_map_count guidance now matches the zoekt memory_map_areas_percentage_used alert (2× repos per replica), and the page mentions shard merging.
    • Resource usage and error rates now point to the Grafana panels that exist (Container monitoring, Provisioning indicators, Search at a glance, Overview).
  • Added a "Check diagnostics" action for Site admin > Diagnostics (/admin/diagnostics).
  • Added a callout at the top pointing Cloud customers to the new Cloud page.

Existing headings are unchanged, so the redirect to #scenario-search-timeouts still works.

New: Troubleshooting Sourcegraph Cloud (/cloud/troubleshooting)

Cloud site admins cannot use most of the self-hosted guide. The Observability admin page is hidden on Cloud for anyone who isn't a Sourcegraph operator. It also hides /-/debug/{grafana,jaeger,prometheus} for customers. The new page is a self-contained checklist of what Cloud admins can collect and send to support:

  • issue context
  • browser console and network evidence, including the x-trace ID
  • search comparisons and trace=1
  • repository sync errors
  • Diagnostics
  • Report a bug
  • instance stats
  • audit logs

It is added under Sourcegraph Cloud in the nav. cloud/index.mdx now links to it instead of to the self-hosted observability docs.

Test plan

  • pnpm run check links --check-anchors --check-self-links: no findings on the changed pages. The 4 anchors this page used to break are fixed; cloud/index.mdx still has 2 broken anchors from before this PR.
  • CSpell, dev/check-hostnames.mjs, tsc --noEmit, and contentlayer2 build pass.
  • Rendered both pages on the dev server: the callout, nav entry, and anchors (#check-diagnostics, Cloud page sections) are present, with no console errors.

Changed links on the Vercel preview

File containing the link Old link (broken today) New link (preview) Page rendered Anchor found
docs/self-hosted/observability/troubleshooting.mdx /self-hosted/observability/tracing#accessing-jaeger /self-hosted/observability/tracing#jaeger ✅ ✅

@vercel

vercel Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
sourcegraph-docs Ready Ready Preview Oct 9, 2026 9:00pm UTC

Request Review

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Direct preview links to pages changed in this PR:

@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

@enriquegh
enriquegh enabled auto-merge (squash) October 9, 2026 21:15
@enriquegh enriquegh added the documentation Improvements or additions to documentation label Oct 9, 2026
enriquegh added a commit that referenced this pull request Oct 9, 2026
The Help Center moved new support requests from
`https://help.sourcegraph.com/hc/en-us/requests/new` to
`https://help.sourcegraph.com/inbox/new`. This updates the six remaining
links on five pages:

- `docs/code-navigation/how-to/index-other-languages.mdx`
- `docs/code-navigation/how-to/adding-scip-to-workflows.mdx` (two links)
- `docs/integration/browser-extension/how-tos/troubleshooting.mdx`
- `docs/getting-started/personalization/badges.mdx`
- `docs/admin/repo/perforce.mdx`

`docs/self-hosted/observability/troubleshooting.mdx` is left alone
because #2085 fixes it.

Not changed, needs follow-up: `docs/batch-changes/faq.mdx` links to the
Help Center article
`/hc/en-us/articles/28471221973133-Changing-Ownership-Of-A-Batch-Change-Before-User-Deletion`,
which now returns 404.

## Test plan

- `https://help.sourcegraph.com/inbox/new` loads the Help Center sign-in
page with `returnPath=/inbox/new`.
- Baseline-filtered link check (`--check-anchors --check-self-links
--check-external`): no new dead links.
- `npx cspell@10` on the changed files: 0 issues.
- Vercel preview: all five pages render
`href="https://help.sourcegraph.com/inbox/new"` (six links total) and no
`hc/en-us/requests/new`.

Co-authored-by: Amp <[email protected]>

This branch was successfully deployed

1 active deployment
Preview — d3157806 Deployed Oct 9, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant