Quickstart

Active setup takes about 5 minutes. The 48-hour learning window that follows is baseline construction running in the background. During that window, all alerts pass through to your alertmanager unchanged.

Step 1: Sign up and create a workspace

Go to obsrvhq.com/register and create a free account. During onboarding you will be prompted to create a workspace. Name it after your environment or team (e.g., acme-production). One workspace per production environment is the recommended setup.

After workspace creation you will land on the dashboard. Copy your API key from Settings → API Keys. This key is used for both the config file and direct API calls.

Step 2: Add your first integration

ObsrvHQ reads your existing alert rule definitions. No changes to your Prometheus configuration are required. Add the following config block to a new file obsrvhq.yaml:

obsrvhq:
  workspace: your-workspace-id
  source: prometheus
  endpoint: http://prometheus.your-cluster:9090
  rules_path: /etc/prometheus/rules
  api_key: ${OBSRVHQ_API_KEY}
  learning:
    min_window_hours: 48
    granularity: per_hour_per_weekday
    sensitivity: 1.5

Set the OBSRVHQ_API_KEY environment variable to the key copied in Step 1. For Kubernetes deployments, store it as a secret:

kubectl create secret generic obsrvhq-secret \
  --from-literal=api-key=YOUR_API_KEY

Step 3: Apply and verify connection

Start the ObsrvHQ agent or apply the config. Within 2 minutes the workspace dashboard will show the number of metric series detected and the learning window start time. If the series count shows 0, check that the Prometheus endpoint is reachable from the ObsrvHQ agent and that your API key is correctly set.

Verify the connection via API:

curl -H "Authorization: Bearer $OBSRVHQ_API_KEY" \
  https://api.obsrvhq.com/v1/workspace/status

A successful response returns {"status": "learning", "series_count": 847, "learning_started": "..."}.

Step 4: Wait for baseline learning (48 hours)

During the learning window, ObsrvHQ builds per-series, per-hour baseline envelopes for every metric it observes. No alerts are suppressed. All alerts pass through to your existing alertmanager unchanged. The dashboard shows learning progress as series count and window elapsed time.

After 48 hours the workspace status changes from learning to active and suppression begins automatically. The first suppression decisions appear in the Decision Feed within minutes of the window completing.

Step 5: Review your first suppressed alerts

In the workspace dashboard, navigate to Decision Feed. Each entry shows: timestamp, service, metric name, alert rule name, and the decision with reason.

Suppressed entries include the envelope context at decision time: for example, within_envelope: p99=310ms, baseline_max=380ms, sensitivity=1.5x. This tells you exactly why the alert was not paged: the observed value was within the learned range for this time window at the configured sensitivity.

Next steps