Gotcha

Documentation

Install, quickstart, SDK setup and alerts.

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…
  • 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.

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…
  • 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,…

Sections

  • 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…
  • 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)…
  • Metrics — The "Metrics" section stores numeric time series that your application sends over the OTLP (OpenTelemetry Protocol) protocol. This is a separate ingest chann…
  • 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…
  • 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…

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…