Gatus Health Dashboard

Gatus is a developer-oriented health dashboard designed to monitor services proactively. Unlike metric-based monitoring (like Prometheus or Cloudwatch) which relies on existing traffic, Gatus performs active health checks to detect issues even when there is no client traffic.

Key Capabilities:

• Proactive Monitoring: Uses HTTP, ICMP, TCP, and DNS queries to actively test endpoints.
• Flexible Conditions: Evaluate health based on status codes, response times, certificate expiration, response body content, IP addresses, and more.
• Alerting: Integrated support for numerous providers including Slack, Teams, PagerDuty, Discord, Twilio, and custom providers.
• User Acceptance Testing: Can be used to create automated UATs by checking specific response patterns.
• Low Footprint: Built in Go for minimal resource consumption.
• Visualizations: Provides a dashboard with dark mode support and generates status badges (Uptime, Health, Response Time).

Suites (ALPHA) allow you to execute a collection of endpoints sequentially within a shared context. This is ideal for multi-step workflows like authentication flows (login $\rightarrow$ access resource $\rightarrow$ logout) or API CRUD testing (create $\rightarrow$ update $\rightarrow$ verify $\rightarrow$ delete).

Core Concepts:

• Shared Context: Values extracted from one endpoint can be used in subsequent endpoints using the [CONTEXT].key syntax.
• Sequential Execution: Endpoints run one after another. A suite is successful only if all required endpoints pass their conditions.
• always-run: Setting this to true on an endpoint ensures it executes even if previous steps in the suite failed (useful for cleanup/logout steps).
• Alerting: Suite-level alerts are not yet supported; configure alerts on individual endpoints within the suite instead.

Context Syntax: You can reference context values in URLs, headers, request bodies, or conditions:

• URL: https://api.example.com/users/[CONTEXT].user_id
• Header: Authorization: Bearer [CONTEXT].auth_token
• Body: {"user_id": "[CONTEXT].user_id"}
• Condition: [BODY].server_ip == [CONTEXT].server_ip

Note: Context/store keys are limited to A-Z, a-z, 0-9, _, and -.

suites:
  - name: item-crud-workflow
    group: api-tests
    interval: 5m
    context:
      price: "19.99"
    endpoints:
      - name: create-item
        url: https://api.example.com/items
        method: POST
        body: '{"name": "Test Item", "price": "[CONTEXT].price"}'
        conditions:
          - "[STATUS] == 201"
          - "len([BODY].id) > 0"
        store:
          itemId: "[BODY].id"
      - name: delete-item
        url: https://api.example.com/items/[CONTEXT].itemId
        method: DELETE
        always-run: true
        conditions:
          - "[STATUS] == 204"

You can integrate Gatus with PagerDuty to notify on-call responders when endpoints fail and automatically resolve incidents when endpoints return to a healthy state.

1. Configure PagerDuty

1. In PagerDuty, go to Configuration > Services.
2. For an existing service: Click the service name, go to the Integrations tab, and click New Integration.
3. For a new service: Create a new service in PagerDuty and select Gatus as the Integration Type.
4. Set an Integration Name (e.g., Gatus-Shopping-Cart) and select Gatus from the Integration Type menu.
5. Click Add Integration.
6. Save the generated Integration Key; you will need this for the Gatus configuration.

2. Configure Gatus

In your Gatus configuration file, add the PagerDuty integration key under alerting.pagerduty.integration-key. Then, add an alert of type pagerduty to your specific endpoints.

Note: It is highly recommended to set send-on-resolved: true for PagerDuty alerts to ensure incidents are automatically closed in PagerDuty when the endpoint recovers.

alerting:
  pagerduty: 
    integration-key: "YOUR_PAGERDUTY_INTEGRATION_KEY"

endpoints:
  - name: website
    url: "https://example.com/health"
    interval: 30s
    alerts:
      - type: pagerduty
        enabled: true
        failure-threshold: 3
        success-threshold: 5
        description: "healthcheck failed"
        send-on-resolved: true
    conditions:
      - "[STATUS] == 200"