Upcoming Gatus feature: Suites

[TwiN]

Suites are collections of endpoints that are executed sequentially with a shared context.

This allows you to create complex monitoring scenarios where the result from one endpoint can be used in subsequent endpoints, enabling workflow-style monitoring.

Here are a few cases in which suites could be useful:

• Testing multi-step authentication flows (login -> access protected resource -> logout)
• API workflows where you need to chain requests (create resource -> update -> verify -> delete)
• Monitoring business processes that span multiple services
• Validating data consistency across multiple endpoints

This is a feature I have been wanting to implement for a very long time, and coupled with Gatus' extremely powerful and customizable endpoint health validating capabilities (vs. most other status pages that are limited to basic checks), I believe that suites are what will bring Gatus into a league of its own.

Here's an example of what the configuration looks like:

suites:
  - name: item-crud-workflow
    group: api-tests
    interval: 5m
    context:
      price: "19.99"  # Initial static value in context
    endpoints:
      # Step 1: Create an item and store the item ID 
      - 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"
          - "[BODY].price == [CONTEXT].price"
        store:
          itemId: "[BODY].id"
        alerts:
          - type: slack
            description: "Failed to create item"
            
      # Step 2: Update the item using the stored item ID
      - name: update-item
        url: https://api.example.com/items/[CONTEXT].itemId
        method: PUT
        body: '{"price": "24.99"}'
        conditions:
          - "[STATUS] == 200"
        alerts:
          - type: slack
            description: "Failed to update item"
        
      # Step 3: Fetch the item and validate the price
      - name: get-item
        url: https://api.example.com/items/[CONTEXT].itemId
        method: GET
        conditions:
          - "[STATUS] == 200"
          - "[BODY].price == 24.99"
        alerts:
          - type: slack
            description: "Item price did not update correctly"
            
      # Step 4: Delete the item (always-run: true to ensure cleanup even if step 2 or 3 fails)
      - name: delete-item
        url: https://api.example.com/items/[CONTEXT].itemId
        method: DELETE
        always-run: true
        conditions:
          - "[STATUS] == 204"
        alerts:
          - type: slack
            description: "Failed to delete item"

Just to clarify, this does not mean endpoints are going away. Just like external-endpoints, suites are just a different way of using Gatus.

Disclaimer: I don't expect the feature to be production ready out of the box. There's a lot of moving parts, which means a lot of potential points of failure. Besides, I also refactored a decent chunk of the core Gatus logic, which worries me a little bit, but no amount of verification and double-checking on my part will make me 100% confident that everything will work as planned. All I can hope is that the large amount of unit tests caught all potential issues.

The feature will be merged shortly, but right now, it's available on #1239 and I built an image for those eager to try it:

 $ docker pull ghcr.io/twin/gatus:pr-1239-suites 

If you have any questions, ask away.

[TwiN]

Here goes. #1239 has been merged.

This feature will have to soak in the latest tag for a little bit since it's a new feature and I have no idea how quickly people will start using it, but if you have any bugs to report or if you're using the new suites feature successfully, please do share your experience - good or bad. I know people are more likely to report issues than they are to report that everything is working as expected, but I need as much feedback as possible on this new feature.

To be honest, just any feedback on how well the new latest tag is working after the merge would be strongly appreciated, as implementing suites forced me to redesign a lot of code for existing features too, and just knowing old features are still working as expected would be strongly appreciated.

Aside from that, I wish you all a great weekend :)

[jeffrpowell]

Adding a data point, since you asked. My setup is fairly simple, just leveraging ping and DNS checks and sending alerts to Discord. Storage in Postgres.
Made the jump from 5.23.x to 5.25.x today. No regressions spotted during my testing.

[TwiN]

@jeffrpowell Thank you for the input!

[mediana]

Looks like a very interesting feature to me, especially for the #1 case given in the initial post : Testing multi-step authentication flows (login -> access protected resource -> logout).

How can such a case be implemented in Gatus ?
Interacting with JSON values seems easy, but not that easy when dealing with HTML DOM, given the documentation I found.
Am I wrong or is XPATH / CSS selector matching is something that will be added to Gatus ?

Best regards,
Antoine

[TwiN]

Not at the moment. The example was more for APIs.

It would be nice, but adding a rendering engine would be quite a task.

[rasodu]

I setup a suit with 3 endpoints. The interval is set to 1m. My webhook alert is set with failure-threshold: 2 and success-threshold: 2. I intentionally failed my 2nd endpoint. I got the failure notification. Then I fixed the the endpoint. I didn't receive notification of resolution of the issue. Checking if anyone else is seeing the same issue.

Also, another issue that I noticed. My dashboard is set to refresh every 10 seconds. I see "Ran 7 minutes ago" on the details page of the suits even though the execution history shows that it was run a few seconds ago. According to execution history, the checks are running every minute. But the note under the suit is not updated.

I am using docker image: docker.io/twinproduction/gatus:latest (10/12)

[rasodu]

storage:
  type: sqlite
  path: /data/data.db

alerting:
  slack:
    webhook-url: "${SLACK_WEBHOOK_URL}"
    default-alert:
      enabled: true
      description: "Health Check Failed"
      send-on-resolved: true
      failure-threshold: 2
      success-threshold: 2

# Common config
alert-default: &default-alert
  alerts:
    - type: slack


endpoint-default-url: &default-url
  <<: *default-alert
  interval: 1m
  client:
    timeout: 10s
  conditions:
    - "[STATUS] == 200"

suites:
  - name: Test websites
    group: Suites
    interval: 1m
    endpoints:
      - name: Google Found
        <<: *default-url
        url: "http://www.google.com"
        conditions:
          - "[BODY] == pat(*Google*)"
      - name: Github not found
        <<: *default-url
        url: "https://github.com/not-found-endpoint2"
        conditions:
          - "[STATUS] == 404"
        client:
          insecure: true
      - name: Google not found
        <<: *default-url
        url: "http://www.google.com/dgdgfd"
        conditions:
          - "[BODY] == pat(*not found on this server*)"

1. Break "Github not found" by changing url from "https://github.com/not-found-endpoint2" to "https://github.com/"
2. Restart the Gatus. (At this point I did get failure notification. But this also seems to not take into account the run failure before restart - next step. So, for example if the service was already failed once before the the next restart step, then the notification still get send after two more additional failed attempts. My expectation was that I would receive notification after just one more failed attempt.)
3. Revert the changes from step 1.
4. Restart the Gatus.
5. No notification of issue resolution.

I am using docker. So, I am restarting container. But my data/DB is persisted thru volume.

I can also confirm that the second issue in the UI is resolved. I see "Last run" time updated correctly.

[TwiN]

Ok, so the issue with the alerting is that suite endpoint alerts aren't loaded on start; seems like I missed that when I implement suites. I'll create a PR to fix it.

[TwiN]

#1347

[rasodu]

I will retest once the PR is merged. I see a lot of places where I would be able to use Suits instead of simple grouped checks.

One more request. I didn't use "always-run: true". If the 2nd check fails, then I don't see the third check at all in the UI. Would it be possible to view all the the check. But if the 2nd check fails, then to display rest of the checks as disabled.

[TwiN]

The original issue you mentioned is now merged/resolved.

For the other issue/feature request, please create an issue