Gotcha

Documentation

Gotcha is a self-hosted observability platform in a single Go binary: errors, uptime, traces, metrics, and profiles on your own server — no external services, no data leaving your infrastructure. The docs cover the whole journey, from the first docker compose up to production tuning, backups, and upgrades.

Where to start:

  • Installation — system requirements, docker compose, first run;
  • Getting started — an organization, a project, your first event and first monitor;
  • SDK & Integrations — connecting Sentry-compatible SDKs and OpenTelemetry (OTLP).

Migrating from Sentry? There’s a dedicated walkthrough on the blog: how to migrate from Sentry to self-hosted Gotcha. The full table of contents is below, grouped by section.

Getting started

  • Getting Started — Gotcha is an observability platform: errors, performance, metrics, uptime, and alerts in one place. It speaks the Sentry ingestion protocol, so connecting yo…
  • Ingest keys — Every project accepts telemetry through a DSN key — a public string that both names the project and authorizes sending data to it (see Glossary). Each key ha…
  • Glossary — A short dictionary of Gotcha's terms — from organizations and projects to profiles and quotas. Where a term has its own detail page, it's linked.
  • Time range — Every page with a chart — Performance and the endpoint page, Web Vitals, Metrics, Profiles, a monitor's latency chart, and an issue's frequency chart — share…

Install & operate

  • Installation — This guide assumes you've never deployed a Docker application or administered a Linux server before. Every command below is ready to copy and paste.
  • Configuration — Gotcha is configured entirely through environment variables prefixed GOTCHA_. There's no config file and no web UI screen for system-level settings — only en…
  • Hardening your install — The baseline production checklist lives in Installation; the table of HSTS variables and how they constrain each other lives in Configuration (Security secti…
  • Backup & Restore — Gotcha keeps data in two separate databases, and both matter equally — you must back up both together, otherwise after a restore they'll be out of sync (e.g.…
  • Upgrade — An upgrade applies database schema migrations — this is not reversible automatically (nobody runs a "just in case" down-migration for you). Before upgrading,…
  • Versioning policy — Before 1.0, gotcha changes the contract between releases freely — the practical steps for that live in Upgrade, release by release. That stops at 1.0: part o…
  • Monitoring gotcha itself — gotcha watches your services. This page is about watching gotcha — what it exposes about its own health, and what to look at when you suspect it is losing da…
  • Cardinality: why some names are grouped — If the performance or metrics page shows a warning about a limit on distinct values, and <cardinality-limit> appeared in the list, this page explains what ha…

Sections

  • Overview — The "Overview" screen is the way into a project: a single timeline of what is broken right now and what was recently fixed, gathered from every incident sour…
  • Issues — An issue is not a single error — it's a group of identical errors collapsed by fingerprint. Instead of a thousand rows of the same exception, the "Issues" se…
  • Exports — A job for a file listing a project's error groups or raw events — CSV, JSON, or NDJSON — built in the background and ready to download from the /projects/{id…
  • Performance — The "Performance" section isn't about individual errors — it's about how fast your application is: transactions (a handled request or a background operation)…
  • Dependencies — The "Dependencies" screen shows what your service *talks to* outside of itself — databases, caches, and other HTTP services it calls — with call volume, late…
  • Deployments — A record of your releases: each deployment your CI reports shows up as a vertical marker on the project's charts, in a dedicated list, and next to the regres…
  • SLOs & error budgets — A Service Level Objective (SLO) turns "the service should be reliable" into a number you can hold yourself to: *99% of requests succeed over the last 30 days…
  • Metrics — The "Metrics" section stores numeric time series that your application sends over the OTLP (OpenTelemetry Protocol) protocol. This is a separate ingest chann…
  • Monitoring Recipes — The "Recipes" section is ready-made monitoring for common services: PostgreSQL, MariaDB, nginx, Redis and Docker. A recipe is a single page with everything n…
  • Metric Alerts — A metric alert rule watches a metric's aggregate (avg/max/p95, etc.) over a rolling time window and opens an incident when the value crosses a threshold. Eac…
  • Hosts — The "Hosts" section shows system metrics for the servers your application runs on: CPU, memory, disk, network, load average, and process count — kept separat…
  • Logs — The telemetry channel for structured application logs: the ingest API (described below) and a browsing/search screen in the UI.
  • Profiling — A profile is a snapshot of where CPU time or memory (alloc/heap) goes inside your application, captured from real call stacks during actual requests — not a…
  • Uptime — The "Uptime" section watches the availability of external addresses and services through periodic checks — monitors. Open it from the activity icon in the le…
  • Public status pages — A public status page is a public view of the state of selected monitors in a project: a standalone page that requires no login, which you can link to for use…
  • Maintenance windows — A maintenance window is a pre-announced interval of planned work for a project. While it's active, incidents opened by that project's monitors are marked "in…
  • Probes (remote regions) — A probe is a separate gotcha process, started with --mode=probe, that runs monitor checks from its own point in the network (a different city, data center, o…
  • Alerts — The "Alerts" section links rules to delivery channels, so your team learns about new issues, regressions, and spikes without having to watch dashboards const…
  • Escalations — Escalation is a ladder of notification steps: the longer an incident stays open and unacknowledged, the wider the set of channels a notification goes to. The…
  • Storm suppression — When a node other things depend on goes down — a gateway, a hypervisor, a database — every dependent node either goes silent or starts firing its own alerts,…
  • Incident groups — When a node other things depend on goes down — a gateway, a hypervisor, a database — signals fire from every direction: hosts behind the gateway go silent, m…

Administration

  • Organizations, projects and teams — Roles are assigned at the organization level and apply across all its projects:
  • SSO and social login — Besides passwords, Gotcha can sign users in through external providers: a generic OIDC provider (any compatible IdP — Keycloak, Authentik, Auth0, etc.), Yand…
  • Privacy and personal data (152-FZ) — Gotcha is a self-hosted platform: you run it on your own infrastructure and control all of the data. Under Russia's Federal Law No. 152-FZ "On Personal Data"…

Integrations

  • SDK & Integrations — Gotcha doesn't have its own wire protocol for sending data — it accepts events and transactions via the Sentry ingestion protocol, and metrics and profiles v…