Error tracking

HelpBites can provision a separate Sentry-compatible project for each HelpBites project in either GlitchTip or Bugsink. The Errors page lists a project's issues; click one to expand its stack trace, event details, breadcrumbs and tags (from the latest event), and resolve or ignore it in the tracker. Errors don't create inbox conversations (earlier ones stay, and resolving one still resolves the issue).

Alerts. The Alerts button sets rules that email the team (the addresses typed there, else the project's notify emails): a new error appears, an error totals N events, or an error happens N times within M minutes, each for all tracker projects or one, with a cooldown before the same error can alert again. Rules are checked once a minute by polling the tracker (first page of unresolved issues per tracker project), and immediately when a tracker's alert webhook calls. The first check of a tracker project only learns what exists, so a new rule doesn't announce old errors as new. Rate windows count from when polling first saw the issue. Needs Mailgun for the emails.

Fix with AI. An expanded error has Analyze and suggest a fix (cause, fix, how to verify, impact; needs an LLM endpoint, saved for 6 hours) and Copy prompt for a coding agent (the same context, no AI call).

File on board. An expanded error has File on board (when the project board is on). It makes a board item in the board's first status, titled from the issue, with the culprit, how many times it happened and a link to the issue in the tracker in its internal description. The item remembers where it came from (errorRefs, shown in its drawer with an Open in GlitchTip/Bugsink link), and the error's row on the Errors page then shows the item instead of the button. Filing is idempotent: pressing it again, or filing from the API, returns the same item. When the error already has a conversation in the inbox (earlier ones do), it is linked to the item too, so both sides show each other. It never changes the issue in the tracker. It emits the errors.filed_on_board event (EVENTS.md).

# Is it filed? (item is null when not; boardEnabled says whether filing is possible)
curl -H "Authorization: Bearer ak_…" \
  "https://YOUR-SUPPORT-HOST/v1/admin/errors/ISSUE_ID/board?project=PROJECT_ID&link=main"

# File it (link: the tracker project's id from project.errorLinks, default the first)
curl -X POST -H "Authorization: Bearer ak_…" -H "Content-Type: application/json" \
  "https://YOUR-SUPPORT-HOST/v1/admin/errors/ISSUE_ID/board" \
  -d '{ "project": "PROJECT_ID", "link": "main" }'
# { "item": { "id": "…", "number": 14, "title": "TypeError: x is undefined", "errorRefs": [{ "provider": "glitchtip", "issueId": "42", "linkId": "main", "title": "…", "url": "https://…/issues/42" }], … }, "created": true }

This is an operator action (an admin session or ak_ key); there is nothing for a visitor's browser to embed.

Repo context. If the project has GitHub repos connected, the analysis and the prompt also include the source of the files in the stack trace (up to 3 files, around the failing line, read from each repo's default branch, so they can differ from the release that failed). Only the event's in-app frames count, and a frame is used only if its path matches exactly one file across the project's repos. It is sent as untrusted data, like the event. No repos, or GitHub not set up: it is written from the event alone.

Add your trackers once in Settings → Error tracking: a name, the URL and API token (plus the organisation slug for GlitchTip). Add as many servers as you like, GlitchTip and Bugsink alike; every project in the workspace can use any of them. Then open Project → Install & API (or Errors) → Connect error tracking, pick a server from the list (or add a new one right there) and connect. No env vars or restart needed. Tokens are stored master-key-only in the workspace's settings and never sent back to the browser. A project uses one server at a time, and a server can't be removed while projects report to it.

Where the edition shares one tracker with everyone (the community edition), a server configured with the GLITCHTIP_* / BUGSINK_* env vars below also shows up in the list, read-only. Projects connected before servers existed keep working with the settings they had.

GlitchTip#

Run Compose with the glitchtip profile, then create the first operator once:

docker compose exec sb-glitchtip ./manage.py createsuperuser

Log in to GlitchTip, create an organisation, then create a token at /profile/auth-tokens with org:read, team:write, project:admin, and event:write. Enter the URL, token and organisation slug in Settings → Error tracking, or set GLITCHTIP_URL, GLITCHTIP_TOKEN and GLITCHTIP_ORG. GLITCHTIP_SECRET_KEY and GLITCHTIP_DB_PASSWORD configure the bundled service itself. In Compose the app reaches it at http://sb-glitchtip:8000, so enter that as the API URL. Attach your public GlitchTip domain to port 8000 so customer SDKs can send events.

Connecting creates the team, project, DSN, and alert webhook.

Bugsink#

Bugsink 2.6 or newer is needed (its canonical API with issue actions). Alerts use its Slack kind. Run Compose with the bugsink profile, set BUGSINK_SECRET_KEY and BUGSINK_URL (the public URL; it becomes Bugsink's BASE_URL and appears in DSNs), then create the first user and a token:

docker compose exec sb-bugsink bugsink-manage createsuperuser
docker compose exec sb-bugsink bugsink-manage create_auth_token

A token from Bugsink's Tokens page works too if it has teams:read, teams:manage, projects:read, projects:manage, issues:read, issues:triage and events:read. Enter the URL and token in Settings → Error tracking (API URL http://sb-bugsink:8000 in Compose), or set BUGSINK_URL and BUGSINK_TOKEN.

Connecting creates the project and stores the DSN. For Bugsink the dialog lets you pick the team it's created under (default: BUGSINK_TEAM, else HelpBites, made if missing); Bugsink's API can't add members, so pick a team you belong to to see the project under Team Projects. Bugsink's API can't add alert destinations, so the dialog then shows a webhook URL: in Bugsink open Projects and the Other Projects tab (the API creates the team and project without adding any user as a member, so they're not under My Projects), click the alerts (megaphone) icon next to the project, click Add, set Kind to Slack and paste the URL as the Webhook url (older Bugsink has no Custom kind; HelpBites reads the Slack payload and still accepts Custom). The webhook is optional: it only makes alert rules run right away instead of within a minute. The same URL stays on the Install & API and Errors pages. If Bugsink and HelpBites talk over a private network, set ALERTS_WEBHOOK_DENY_NON_GLOBAL=false on Bugsink.

More than one tracker project#

A HelpBites project can report to several tracker projects (a web app and an API, say). Run Connect error tracking again from the Errors or Install & API page and give a different Project name; a name that already exists in the team is reused. Each one has its own DSN, alert webhook URL and token. The Errors page shows one pill per tracker project ("All" merges each one's newest page; pick a pill to page further), and GET /v1/admin/errors?link= takes the id from project.errorLinks. Status changes go back to the tracker project an issue came from.

Manage (Errors page) lists each tracker project with its tracker, project name, team, DSN and alert webhook. You can change the name its pill shows or remove it; removing only stops HelpBites reporting there (the tracker project and past conversations stay), and the tracker, name and team are fixed, so to change them remove it and connect again. The alert webhook instructions sit in a collapsible on the same page.

Bugsink can't search issues by Sentry user id, so a customer's recent errors don't show in their conversation sidebar. Status and text filters on the Errors page apply to each page of 250 issues.

SDKs#

Use any Sentry SDK with the DSN shown in Project → Install & API. Always set the same stable identity value used in the HelpBites token's sub claim:

Sentry.init({ dsn: 'https://[email protected]/42' })
Sentry.setUser({ id: user.id })

NUXT_PUBLIC_SENTRY_DSN enables HelpBites' own browser and server reporting. GlitchTip is MIT licensed and Bugsink is PolyForm Shield licensed; both run as separate services next to HelpBites.