tutorial

Uptime monitoring for Sourcegraph code search and intelligence platform

Sourcegraph is the backbone of large-scale code navigation — engineers use it to search millions of lines across repositories, find references, trace call pa...

Sourcegraph is the backbone of large-scale code navigation — engineers use it to search millions of lines across repositories, find references, trace call paths, and review code intelligence signals. When your self-hosted Sourcegraph instance goes down, the blast radius extends beyond individual productivity: onboarding stops, code reviews slow to a crawl, and automated batch change pipelines fail silently. Because Sourcegraph is developer infrastructure rather than user-facing software, it often lacks the monitoring priority it deserves.

This tutorial covers production-grade uptime monitoring for Sourcegraph using Vigilmon. We will walk through:

  • Monitoring the Sourcegraph frontend health endpoint
  • Monitoring the Sourcegraph Gitserver and Zoekt search processes
  • SSL certificate monitoring for your code intelligence endpoints
  • Webhook alerts for DOWN/UP events

Prerequisites

  • Sourcegraph self-hosted (Docker Compose or Kubernetes)
  • A free account at vigilmon.online

Part 1: Enable and verify the Sourcegraph health endpoint

Sourcegraph's frontend service exposes a /-/healthz endpoint that returns HTTP 200 when the instance is operational. It checks that the frontend can reach the database and other internal services.

Docker Compose deployment

# docker-compose.yaml (excerpt)
version: "3.8"

services:
  frontend:
    image: sourcegraph/server:5.3.0
    ports:
      - "7080:7080"
      - "7443:7443"
    environment:
      - SRC_FRONTEND_INTERNAL=http://frontend:3090
      - DEPLOY_TYPE=docker-compose
    restart: unless-stopped

Start the stack:

docker compose up -d

Verify the health endpoint

curl -s http://localhost:7080/-/healthz

Expected response when healthy:

200 OK

Or with verbose output:

curl -sv http://localhost:7080/-/healthz 2>&1 | grep "< HTTP"
# < HTTP/1.1 200 OK

The endpoint returns HTTP 503 when the frontend cannot reach its PostgreSQL or Redis dependencies. A 200 confirms the primary services are connected and ready to serve traffic.

Part 2: Expose the health endpoint for external monitoring

Sourcegraph typically runs behind a reverse proxy with TLS. Expose /-/healthz publicly so Vigilmon can poll it from external check nodes.

nginx configuration

# /etc/nginx/sites-available/sourcegraph
server {
    listen 443 ssl;
    server_name sourcegraph.example.com;

    ssl_certificate     /etc/letsencrypt/live/sourcegraph.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sourcegraph.example.com/privkey.pem;

    # Health endpoint — no authentication required
    location = /-/healthz {
        proxy_pass http://127.0.0.1:7080/-/healthz;
        proxy_set_header Host $host;
        access_log off;
    }

    # All other traffic through normal auth
    location / {
        proxy_pass       http://127.0.0.1:7080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Caddy configuration

sourcegraph.example.com {
    handle /-/healthz {
        reverse_proxy localhost:7080
    }

    handle {
        reverse_proxy localhost:7080
    }
}

Verify from outside:

curl https://sourcegraph.example.com/-/healthz
# 200 OK

Part 3: Set up HTTP monitoring in Vigilmon

Monitor the Sourcegraph frontend

  1. Log in to vigilmon.online and click Add Monitor.
  2. Choose HTTP(S) monitor.
  3. Enter: https://sourcegraph.example.com/-/healthz
  4. Set interval to 1 minute.
  5. Set expected HTTP status to 200.
  6. Add your alert channel.
  7. Click Save.

Monitor the Sourcegraph search API

Sourcegraph exposes a GraphQL API at /.api/graphql. Add a lightweight monitor for it:

| Component | Monitor URL | Expected code | |-----------|-------------|---------------| | Frontend health | https://sourcegraph.example.com/-/healthz | 200 | | GraphQL endpoint | https://sourcegraph.example.com/.api/graphql | 200 or 401 | | Sign-in page | https://sourcegraph.example.com/sign-in | 200 |

For the GraphQL monitor, a 401 is acceptable — it confirms the API is alive and rejecting unauthenticated requests. Set the expected code accordingly or use a keyword check for the JSON error body.

Part 4: Monitor Gitserver and Zoekt separately

Sourcegraph's search and code intelligence rely on two background processes: gitserver (raw repository access) and zoekt (text search indexer). They each expose their own health endpoints when deployed in distributed mode.

Gitserver health

If gitserver runs on a separate host or port:

curl http://gitserver:3178/healthz
# {"ready": true}

Add a Vigilmon monitor:

  1. Add Monitor → HTTP(S)
  2. URL: https://sourcegraph.example.com/gitserver/healthz (or internal URL via reverse proxy)
  3. Keyword check: ready
  4. Interval: 1 minute

Zoekt health

Zoekt's indexer exposes /-/ready on port 6070:

curl http://zoekt:6070/-/ready
# ready

Add a Vigilmon monitor for the search indexer:

  1. Add Monitor → HTTP(S)
  2. URL: internal endpoint proxied as https://sourcegraph.example.com/zoekt/-/ready
  3. Keyword: ready
  4. Interval: 1 minute

Keeping gitserver and zoekt as separate monitors means you can immediately distinguish between "Sourcegraph frontend is down" and "only search indexing is degraded" — two failure modes with very different impact and remediation paths.

Part 5: SSL certificate monitoring

Code intelligence endpoints are consumed directly by IDE extensions (VS Code, JetBrains), browser extensions, and the Sourcegraph CLI. An expired certificate immediately breaks all of these integrations without any warning visible in the Sourcegraph UI itself.

  1. In Vigilmon, click Add Monitor.
  2. Choose SSL monitor.
  3. Enter: sourcegraph.example.com
  4. Set alert threshold to 14 days before expiry.
  5. Add your alert channel.
  6. Click Save.

If you expose gitserver or other subdomains on separate certificates, add a separate SSL monitor for each.

Part 6: Webhook alerts for DOWN events

Wire Vigilmon DOWN/UP events into your incident response workflow:

// webhook-receiver.ts
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook/vigilmon', (req, res) => {
  const { monitor_name, status, url, response_code, checked_at } = req.body;

  if (status === 'down') {
    console.error('[VIGILMON] Sourcegraph monitor DOWN', {
      monitor: monitor_name,
      url,
      code: response_code,
      at: checked_at,
    });

    postSlackAlert({
      text: `⚠️ Sourcegraph is DOWN\n${url}\nHTTP ${response_code}`,
      channel: '#developer-tooling-alerts',
    });
  } else if (status === 'up') {
    console.info('[VIGILMON] Sourcegraph recovered', { monitor: monitor_name });
    postSlackAlert({
      text: `✅ Sourcegraph recovered\n${url}`,
      channel: '#developer-tooling-alerts',
    });
  }

  res.sendStatus(204);
});

app.listen(3000);

Vigilmon sends this payload on DOWN and UP transitions:

{
  "monitor_id": "mon_abc123",
  "monitor_name": "Sourcegraph /-/healthz",
  "status": "down",
  "url": "https://sourcegraph.example.com/-/healthz",
  "checked_at": "2026-06-30T09:00:00Z",
  "response_code": 503,
  "response_time_ms": 5210
}

Part 7: Kubernetes deployments

For Sourcegraph deployed in Kubernetes using the official Helm chart, add a Vigilmon ingress path for the health endpoint:

# sourcegraph-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: sourcegraph
  namespace: sourcegraph
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "200m"
spec:
  tls:
    - hosts:
        - sourcegraph.example.com
      secretName: sourcegraph-tls
  rules:
    - host: sourcegraph.example.com
      http:
        paths:
          - path: /-/healthz
            pathType: Exact
            backend:
              service:
                name: sourcegraph-frontend
                port:
                  number: 30080
          - path: /
            pathType: Prefix
            backend:
              service:
                name: sourcegraph-frontend
                port:
                  number: 30080

Add liveness and readiness probes to the frontend deployment:

livenessProbe:
  httpGet:
    path: /-/healthz
    port: 3080
  initialDelaySeconds: 60
  periodSeconds: 30
  timeoutSeconds: 10
  failureThreshold: 3
readinessProbe:
  httpGet:
    path: /-/healthz
    port: 3080
  initialDelaySeconds: 10
  periodSeconds: 10
  timeoutSeconds: 5

Summary

Your Sourcegraph deployment now has four layers of monitoring:

  1. /-/healthz endpoint — confirms the frontend, PostgreSQL, and Redis are connected, polled every 60 seconds by Vigilmon.
  2. Gitserver and Zoekt monitors — separate checks for search indexing and repository access so you can pinpoint which Sourcegraph layer degraded.
  3. SSL monitor — alerts you 14 days before certificate expiry, before IDE extensions and CLI tools start failing.
  4. Webhook/Slack alerts — DOWN and UP events reach your developer tooling channel within one check interval.

Vigilmon handles check scheduling, multi-region polling, alert routing, and uptime history. When Sourcegraph goes down, your team knows within 60 seconds — before engineers open a support ticket wondering why code search stopped working.

Monitor your Sourcegraph infrastructure free at vigilmon.online

#sourcegraph #codesearch #devtools #monitoring #uptime

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles