How do I migrate from Sentry?

GlitchTip is API-compatible with Sentry, enabling migration paths by deploying GlitchTip and following the documentation for data import and integration steps.

How do I enable uptime monitoring and metrics?

Set GLITCHTIP_ENABLE_UPTIME to true to enable uptime checks and, if desired, ENABLE_OBSERVABILITY_API for Prometheus-compatible metrics; configure domain and alerting via environment variables.

glitchtip

Scanned

npx machina-cli add skill Lu1sDV/skillsmd/glitchtip --openclaw

Files (1)

SKILL.md

11.1 KB

GlitchTip

Open-source, Sentry API-compatible error tracking and uptime monitoring. Django + PostgreSQL backend, Angular frontend. Runs on 256MB RAM (all-in-one) or 512MB (standard).

Site: https://glitchtip.com
Docs: https://glitchtip.com/documentation
API: https://app.glitchtip.com/api/docs
Repo: https://gitlab.com/glitchtip/glitchtip-backend
License: MIT

Quick Reference

Resource	URL
Hosted (US)	`app.glitchtip.com`
Hosted (EU)	`eu.glitchtip.com`
SDK docs	`glitchtip.com/sdkdocs`
Install guide	`glitchtip.com/documentation/install`
CLI (gtc)	`pip install glitchtip-cli`

Deployment

Docker Compose (recommended)

# Download sample compose file
curl -sLO https://glitchtip.com/assets/docker-compose.sample.yml
mv docker-compose.sample.yml compose.yml
# Edit environment variables, then:
docker compose up -d
# Upgrade: docker compose pull && docker compose stop && docker compose up -d

Minimal variant: compose.minimal.yml — all-in-one mode, ~256MB RAM.

Kubernetes (Helm)

helm repo add glitchtip https://gitlab.com/api/v4/projects/16325141/packages/helm/stable
helm install glitchtip glitchtip/glitchtip

Externally managed PostgreSQL recommended. Supports pod disruption budgets and anti-affinity for HA.

Managed Platforms

PikaPods, Elestio, Nodion, Railway (one-click template), RepoCloud.

Configuration

All via environment variables. Set in compose.yml or Helm values.

Required

Variable	Purpose
`SECRET_KEY`	Random string for Django security
`DATABASE_URL`	PostgreSQL 14+ connection string
`GLITCHTIP_DOMAIN`	Full URL with scheme (`https://glitchtip.example.com`)
`DEFAULT_FROM_EMAIL`	Sender address for notifications

Email

Method	Config
SMTP	`EMAIL_URL=smtp://user:pass@host:port`
Mailgun	`MAILGUN_API_KEY` + `EMAIL_BACKEND=anymail.backends.mailgun.EmailBackend`
SendGrid	`SENDGRID_API_KEY` + `EMAIL_BACKEND=anymail.backends.sendgrid.EmailBackend`
Console (dev)	`EMAIL_URL=consolemail://`

Also supports Postmark, Mailjet, Mandrill, SparkPost, Brevo via Anymail.

Data Retention

Variable	Default
`GLITCHTIP_MAX_EVENT_LIFE_DAYS`	90
`GLITCHTIP_MAX_TRANSACTION_EVENT_LIFE_DAYS`	(inherits above)
`GLITCHTIP_MAX_FILE_LIFE_DAYS`	(inherits above)
`GLITCHTIP_MAX_UPTIME_CHECK_LIFE_DAYS`	(inherits above)

Cache & Workers

Variable	Default	Purpose
`VALKEY_URL`	—	`redis://:pass@host:port/db` (Valkey/Redis 7+)
`DATABASE_POOL_MAX_SIZE`	20	psycopg connection pool
`GRANIAN_WORKERS`	1	Web server workers (async, rarely needs >1)
`VTASKS_CONCURRENCY`	20	Background task concurrency

Set VALKEY_URL to empty string to disable and use PostgreSQL as queue.

Feature Flags & Security

Variable	Default	Purpose
`ENABLE_USER_REGISTRATION`	true	Allow self-signup
`ENABLE_ORGANIZATION_CREATION`	false	Allow users to create orgs
`GLITCHTIP_ENABLE_UPTIME`	true	Uptime monitoring
`GLITCHTIP_ENABLE_MCP`	false	Model Context Protocol server
`ENABLE_OBSERVABILITY_API`	false	Prometheus metrics
`ALLOWED_HOSTS`	`*`	Comma-separated allowed domains
`CSRF_TRUSTED_ORIGINS`	—	Reverse proxy origins
`BASE_PATH`	—	Subpath hosting (`/glitchtip`)

File Storage

Backend	`DEFAULT_FILE_STORAGE`	Key Variables
AWS S3 / DO Spaces	`storages.backends.s3boto3.S3Boto3Storage`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_STORAGE_BUCKET_NAME`
Azure Blob	`storages.backends.azure_storage.AzureStorage`	`AZURE_ACCOUNT_NAME`, `AZURE_ACCOUNT_KEY`, `AZURE_CONTAINER`
GCS	`storages.backends.gcloud.GoogleCloudStorage`	`GS_BUCKET_NAME`, `GS_PROJECT_ID`, `GOOGLE_APPLICATION_CREDENTIALS`

SDK Integration

GlitchTip uses Sentry SDKs — 58 implementations across 18 languages. Configure any Sentry SDK by pointing the DSN to the GlitchTip instance:

https://<SENTRY_KEY>@<GLITCHTIP_DOMAIN>/<PROJECT_ID>

Find the DSN in Project Settings > Security Endpoint.

Supported Platforms

JavaScript: Browser, React, Angular, Vue, Ember, Next.js, Backbone Node.js: Express, Koa, Connect, plain Node Python: Django, Flask, Celery, FastAPI (ASGI), AWS Lambda, WSGI, + 10 more PHP: Laravel, Symfony, Drupal, Monolog Ruby: Rails, Rack Java: Android, Log4j, Logback, App Engine Go: net/http, plain Go C#: ASP.NET Core Rust, Elixir, Flutter, React Native, Electron, Cordova, C/C++, Objective-C

Reduce Event Volume

sentry_sdk.init(
    dsn="...",
    traces_sample_rate=0.01,  # 1% of transactions
    sample_rate=0.5,          # 50% of errors
)

Source Maps (sentry-cli)

GlitchTip is Sentry API-compatible but does not support the newer artifact-bundle/debug-ID upload flow. Use legacy release-based uploads only.

SDK docs: https://glitchtip.com/sdkdocs
Install/storage guide: https://glitchtip.com/documentation/install

Prerequisites: File storage must be configured (S3/Azure/GCS or local volume) — source maps are storage-backed, not just metadata.

Discover Org & Project Slugs

# Slugs ≠ display names. Query the API to find correct values:
curl -s https://<GLITCHTIP_DOMAIN>/api/0/projects/ \
  -H "Authorization: Bearer <AUTH_TOKEN>" | jq '.[].slug'

Legacy Upload Workflow

# 1. Set release in your SDK init: release: "<RELEASE_ID>"
# 2. Build with source maps enabled
# 3. Upload (--url is a GLOBAL flag, must precede subcommand):
sentry-cli --url https://<GLITCHTIP_DOMAIN> releases \
  --org <org-slug> --project <project-slug> \
  files "<RELEASE_ID>" upload-sourcemaps ./dist \
  --url-prefix "~/"

Bundler Plugin (Vite/Webpack/esbuild/Rollup)

// Use uploadLegacySourcemaps — the default artifact-bundle mode
// triggers 404 on GlitchTip's /artifactbundle/assemble/ endpoint
sentryPlugin({
  url: "https://<GLITCHTIP_DOMAIN>",  // REQUIRED — defaults to sentry.io
  authToken: process.env.SENTRY_AUTH_TOKEN,
  org: "<org-slug>",
  project: "<project-slug>",
  release: { uploadLegacySourcemaps: "./dist" },
})

Next.js Specifics

Set productionBrowserSourceMaps: true in next.config.js
Pass sentryUrl (not url) into withSentryConfig
Watch for trailing slashes in the instance URL — they can break uploads

Gotchas

Gotcha	Detail
`.sentryclirc` ignored	Bundler plugin v2 no longer reads `.sentryclirc` — pass config via plugin options or env vars (`SENTRY_URL`, `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT`)
CLI calls sentry.io	`--url` is a global flag — must come before the subcommand, not after
Auth token vs DSN	DSN = SDK event ingestion. Auth token = CLI/API operations (Profile > Auth Tokens). Do not mix them
Upload succeeds, UI empty	CLI output can be decoupled from server persistence — always check server logs for 500s
`releases finalize` fails	Not fully supported on GlitchTip — skip finalize, rely on release creation + artifact upload
Proxy/TLS false 401	Corporate proxies cause "Invalid token" errors — enable `sentry-cli --log-level debug`, verify proxy env vars are full URLs

Uptime Monitoring

Four monitor types:

Type	Behavior
Ping	HTTP HEAD request (most common)
GET	HTTP GET, validates expected status code
POST	HTTP POST, validates expected status code
Heartbeat	Awaits inbound requests from your app at a generated URL

Link monitors to a project with email alerts configured for status change notifications.

Integrations

Alerting

Configure in Projects > Alert Recipients:

Email: Team member notifications on error frequency thresholds
Webhooks: POST to any URL on alert trigger

External Tools

Tool	Setup
GitLab	Settings > Monitor > Error Tracking > Sentry provider > GlitchTip URL + Auth Token
Grafana	Data source > Sentry type > GlitchTip URL + org + Auth Token

Auth tokens: Profile > Auth Tokens (scope: read-only or full).

Social Auth (OAuth)

Configure via Django Admin (/admin/socialaccount/socialapp/):

GitHub, GitLab, Google, Microsoft, Gitea, DigitalOcean, NextCloud, Okta, OpenID Connect (Keycloak, etc.)

Callback URL: https://example.com/accounts/<provider>/login/callback/

OpenID Connect settings:

{ "server_url": "https://idp.example.com/auth/realms/realm/.well-known/openid-configuration" }

CLI Tool (gtc)

pip install glitchtip-cli
gtc list      # list organizations
gtc create    # create organization
gtc delete    # delete organization
gtc members   # show org membership

First run prompts for API token and instance URL. Config saved to .env.

Troubleshooting

Issue	Fix
Events not appearing	Verify DSN, check SDK `sampleRate`, confirm `GLITCHTIP_DOMAIN` matches
High event volume	Lower `traces_sample_rate` / `sample_rate` in SDK config
Email not sending	Check `EMAIL_URL` or provider API key, try `consolemail://` for debugging
401 on API/integration	Regenerate Auth Token in Profile > Auth Tokens
Worker not processing	Check `VALKEY_URL`, ensure worker container running, verify `VTASKS_CONCURRENCY`
Out of memory	Use all-in-one mode (`compose.minimal.yml`) or increase RAM to 512MB+
Uptime checks failing	Verify monitor URL accessible from GlitchTip server, check expected status code
Social auth not working	Verify callback URL, check Django Admin socialaccount config
Search not working	Check PostgreSQL `text_search_config` for non-English languages
Disk growing fast	Lower `GLITCHTIP_MAX_EVENT_LIFE_DAYS`, check source map / file retention
404 on `/artifactbundle/assemble/`	GlitchTip doesn't support artifact-bundle flow — switch to `uploadLegacySourcemaps` or `releases files upload-sourcemaps`
"Nothing to upload" but UI empty	Check file storage config (S3/volume), inspect server logs for 500s on assemble endpoint
`debug_id_or_release_required`	Upload only `.js` + `.map` pairs, not entire `dist/` — remove files without matching maps
`files_fileblob_checksum_key` duplicate	Clean release artifacts before re-uploading identical builds; upload is not idempotent
`releases finalize` → "version required"	Skip finalize — not fully supported on GlitchTip. Use release creation + artifact upload only
CLI sends to sentry.io unexpectedly	`--url` must precede subcommand; check `.sentryclirc` `defaults.url`; bundler plugin v2 ignores `.sentryclirc`
Stack traces stay minified	Verify: (1) storage has files, (2) release value matches SDK init, (3) `--url-prefix` matches runtime paths

Source

git clone https://github.com/Lu1sDV/skillsmd/blob/main/glitchtip/SKILL.mdView on GitHub

Overview

GlitchTip is an open-source error-tracking and uptime-monitoring platform with a Django + PostgreSQL backend and an Angular frontend. It is API-compatible with Sentry, enabling self-hosted deployments through Docker Compose or Kubernetes (Helm). It supports SDK setup, source maps, and migration from Sentry, plus alerting and uptime checks.

How This Skill Works

GlitchTip runs a Django backend with PostgreSQL and an Angular frontend, exposing a Sentry-compatible API for error reporting. Deployment is configured entirely via environment variables (e.g., SECRET_KEY, DATABASE_URL, GLITCHTIP_DOMAIN), with optional Redis/Valkey-backed queues and workers for background tasks. It can be deployed via Docker Compose or Helm, and offers uptime monitoring, alerting, and optional observability metrics.

When to Use It

You want a self-hosted error tracking and uptime monitoring stack using Docker Compose or Kubernetes (Helm).
You need to configure deployment specifics with environment variables for security and routing (SECRET_KEY, DATABASE_URL, GLITCHTIP_DOMAIN).
You’re integrating the GlitchTip SDK into your app, including support for source maps and Sentry CLI workflows.
You plan to migrate from Sentry due to API compatibility and want a guided path to switch to GlitchTip.
You want built-in uptime monitoring and alerting, with optional metrics exposure for Prometheus.

Quick Start

Step 1: Choose a deployment method (Docker Compose or Helm) and follow the install steps in the docs.
Step 2: Set essential environment variables in compose.yml or Helm values (SECRET_KEY, DATABASE_URL, GLITCHTIP_DOMAIN, DEFAULT_FROM_EMAIL).
Step 3: Bring up the stack (docker compose up -d or helm install) and verify the UI and logs to confirm successful startup.

Best Practices

Start with the Minimal variant (compose.minimal.yml) for a 256MB RAM all-in-one setup to validate basics.
Use an external PostgreSQL for production deployments to separate data from the app container.
Set VALKEY_URL appropriately; if using PostgreSQL as queue, set VALKEY_URL to an empty string.
Secure critical settings: define SECRET_KEY, GLITCHTIP_DOMAIN, and ALLOWED_HOSTS; configure CSRF_TRUSTED_ORIGINS for proxies.
Enable uptime monitoring and metrics after core functionality is verified (GLITCHTIP_ENABLE_UPTIME; consider ENABLE_OBSERVABILITY_API for Prometheus).

Example Use Cases

Self-hosted GlitchTip deployed via Docker Compose with a minimal 256MB RAM stack and a separate PostgreSQL instance.
Kubernetes deployment using Helm with external PostgreSQL, anti-affinity rules, and proper resource requests/limits.
SMTP-based email notifications configured through EMAIL_URL or MAILGUN/SendGrid backends.
Migration from Sentry leveraging API compatibility to import and route error data in GlitchTip.
Uptime monitoring enabled with GLITCHTIP_ENABLE_UPTIME and optional Prometheus metrics via ENABLE_OBSERVABILITY_API.

Frequently Asked Questions

Add this skill to your agents