feat(observability): add a Grafana Sentry datasource for in-Grafana issue visualization

[JSONbored]

Summary

• Sentry error/issue data was previously only reachable from Grafana via a plain external hyperlink in resource-hub.json — no way to correlate it in time with the rest of the stack's metrics/logs/traces without leaving Grafana.
• Adds the grafana-sentry-datasource plugin (v2.2.4) — a first-party Grafana Labs plugin, confirmed Grafana-signed and free (no Enterprise/Cloud requirement), researched before assuming anything per the tracking issue's own requirement (not a guessed plugin name/version).
• New scripts/setup-sentry-datasource.sh mirrors the existing setup-github-datasource.sh API-provisioning pattern exactly (a backend datasource whose token isn't ready at Grafana boot would crash file-based provisioning, so it's added post-boot over the API).
• Important, clearly documented in both .env.example and the self-hosting docs: SENTRY_API_TOKEN (a Sentry Internal Integration token with Project/Issue & Event/Organization read scopes) is a separate credential from the existing SENTRY_DSN — a DSN authenticates event ingestion, not the read/query API this datasource needs. SENTRY_DSN cannot be reused here.
• New grafana/dashboards/sentry-issues.json: recent unresolved issues, top issues by event count, and error-volume trend over time.
• Distinct scope from Epic: consolidate Sentry + Alertmanager alerting into one real-time notification path #5007 (Alertmanager/Sentry notification routing) — this is read-only visualization, not paging.

Verification approach (I don't have the repo owner's real Sentry credentials, so full live data flow can't be confirmed the same way the other 3 sub-issues in this epic were — documented honestly rather than skipped):

1. Installed the plugin on the actual pinned grafana/grafana:13.1.0 image (both an isolated test container and the live edge-nl-01 Grafana) — registers with signatureType: grafana (valid, first-party signed), no version-incompatibility crash.
2. Created a real datasource via the Grafana API with the exact jsonData/secureJsonData shape this script sends — accepted correctly.
3. Ran all 3 dashboard panel query shapes (issues sorted by date, issues sorted by freq, eventsStats) against that datasource with a deliberately fake token — confirmed each one constructs a correct, well-formed real Sentry API request URL and gets a genuine 401 Unauthorized back from Sentry's own API, not a plugin-side schema-rejection error. This proves the query JSON shape (queryType/issuesQuery/issuesSort/issuesLimit/eventsStatsYAxis/eventsStatsQuery/eventsStatsGroups) is exactly correct — only a real token is needed for real data to flow.
4. Confirmed the dashboard imports cleanly via Grafana's own dashboard-import API and provisions correctly on the live server (5 elements: 2 rows + 3 panels).

Part of #5365. Closes #5369.

Test plan

• npm run typecheck
• npm run ui:lint, npm run ui:typecheck, npm run ui:openapi:check
• node scripts/validate-observability-configs.mjs
• shellcheck scripts/setup-sentry-datasource.sh — same pre-existing informational-only SC1091 note as setup-github-datasource.sh, nothing new
• npm run test:ci — full local gate green apart from 2 known, pre-existing, environment-only flakes in unrelated miner git-fixture tests (a local SSH-agent commit-signing key not being available in this shell's agent socket — confirmed via direct reproduction outside any test, and confirmed unrelated to this diff; GitHub Actions CI has no such signing config)
• Live verification on edge-nl-01 and an isolated Grafana 13.1.0 container as described above

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	2f86c0c	Commit Preview URL Branch Preview URL	Jul 12 2026, 07:59 PM

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.48%. Comparing base (65fa28b) to head (2f86c0c).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5453   +/-   ##
=======================================
  Coverage   94.48%   94.48%           
=======================================
  Files         554      554           
  Lines       44450    44450           
  Branches    14663    14663           
=======================================
  Hits        41999    41999           
  Misses       1776     1776           
  Partials      675      675           

Flag	Coverage Δ
shard-1	44.09% <ø> (ø)
shard-2	34.94% <ø> (ø)
shard-3	32.00% <ø> (+0.04%)	⬆️
shard-4	31.70% <ø> (+0.42%)	⬆️
shard-5	32.78% <ø> (-0.53%)	⬇️
shard-6	43.48% <ø> (-0.09%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-12 20:05:24 UTC}

8 files · 2 AI reviewers · no blockers · readiness 100/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx (matched apps/gittensory-ui/**), scripts/setup-sentry-datasource.sh (matched scripts/**).

Review summary
Adds a new Grafana Sentry datasource plugin, provisioning script, dashboard JSON, docs, and env-var documentation, closely mirroring the existing GitHub-datasource pattern (API-provisioned post-boot to avoid the boot-crash issue file-provisioning would cause). The change is well-scoped, internally consistent (script, dashboard, docs, and .env.example all agree on SENTRY_API_TOKEN/SENTRY_ORG_SLUG being distinct from SENTRY_DSN), and is explicitly tied to tracking issue #5369. Tests assert file-level shape (plugin listed, script contains expected strings, dashboard panel schema) rather than live Sentry API behavior, which the PR author is upfront about since real credentials aren't available.

Nits — 7 non-blocking

• The 'IaC misconfiguration' flag on .env.example:534 is a false positive — that line is a commented-out example (`SENTRY_API_URL=https:​//sentry.io`) in an .env.example file, not a hardcoded live config value.
• test/unit/selfhost-grafana-sentry-datasource.test.ts checks string presence/regexes in the shell script rather than executing it, so it can't catch a runtime curl/payload bug (e.g., a malformed JSON heredoc) — consider a smoke test that runs the script against a mocked Grafana API if that infra exists elsewhere in the repo.
• docker-compose.yml and .env.example are already long files per repo convention; this PR's additions are small increments to files already over the size threshold, not new bloat introduced by this diff — flagged by the external brief but not actionable here.
• The dashboard's 'Recent unresolved issues' and 'Top issues by event count' panels both leave `projectIds: []`, meaning by default the datasource queries every project the token can read — this is documented in the panel description but worth calling out again in the .env.example comment for operators with multi-project Sentry orgs.
• Consider adding a lightweight integration test (or documented manual step) that actually exercises setup-sentry-datasource.sh against a mocked/stubbed Grafana API, since the current test suite only greps script text.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#5369
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 44 registered-repo PR(s), 36 merged, 457 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 44 PR(s), 457 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — The PR closes a real observability gap (Sentry data only reachable via external link) by following an established, already-vetted provisioning pattern in the repo, with matching docs and tests.

Linked issue satisfaction

Addressed
The PR verifies and adds the grafana-sentry-datasource plugin, mirrors the setup-github-datasource.sh API-provisioning pattern in a new setup-sentry-datasource.sh with a distinct SENTRY_API_TOKEN/SENTRY_ORG_SLUG credential clearly documented as separate from SENTRY_DSN, adds a dashboard with recent issues/top issues/volume trend panels, updates resource-hub.json to link the new in-Grafana view alo

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 44 PR(s), 457 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

Visual preview

Route	Viewport	Before (production)	After (this PR's preview)	Diff
/docs/self-hosting-operations	desktop			—
/docs/self-hosting-operations	mobile			—

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review