DHIVA LABS · LEARN

Appearance

Monitoring ​

A test tells you the API worked when you ran it. Monitoring runs the same checks again and again, so you find out when it stops working, ideally before a user does.

What to monitor ​

A monitor is a small, fast subset of your tests. Choose requests that:

  • Read, and do not write. A monitor that creates an order every minute fills a database.
  • Cover the critical paths. The health check, sign-in, one main read.
  • Have real checks. Status, one value that proves the content, and a time limit.
  • Finish in seconds.

Three to six requests is typical.

While you work: recurring runs ​

ApiWorkbench's runner can repeat a set of requests on a timer for as long as it stays open. Useful when you are developing against an API, deploying, or waiting for a fix to arrive.

  1. Put the monitor's requests in one collection, or pick a folder of an imported one.

  2. Open its ⋯ menu and choose Run collection or Run folder.

  3. Turn on Recurring and set Every (s) to the pause you want between passes, such as 60.

  4. Select Run. The run repeats until you select Stop.

Each pass adds its results to the list, with pass and fail counts and the average, fastest and slowest times across the whole run. A red row with a timestamp tells you when things went wrong. See Collection runner.

A recurring run lives in the open app. Close ApiWorkbench, or let the computer sleep, and it stops. For unattended monitoring, use the command line.

Unattended: scheduled command-line runs ​

apiworkbench-cli runs a collection without the app and exits with a code that says whether everything passed. Anything that can run a command on a schedule can use it.

Export the collection from ApiWorkbench first, so the monitor has a file to run. See Export and share.

With cron, on a Linux server ​

A small script that runs the monitor and records the outcome:

bash
#!/bin/sh
# /usr/local/bin/api-monitor.sh
if apiworkbench-cli run /srv/monitor/health.apiworkbench.json \
     --timeout-request 10000 \
     -r cli,junit --reporter-junit-export /srv/monitor/last-run.xml \
     > /srv/monitor/last-run.log 2>&1
then
  echo "$(date -Is) ok" >> /srv/monitor/history.log
else
  echo "$(date -Is) FAILED" >> /srv/monitor/history.log
  # Put your alert here: send a mail, post to a chat webhook, and so on.
fi

Then schedule it every five minutes with crontab -e:

text
*/5 * * * * /usr/local/bin/api-monitor.sh

With a scheduled CI job ​

Most CI systems can run a job on a timer and notify you when it fails. In GitHub Actions:

yaml
name: API monitor
on:
  schedule:
    - cron: '*/15 * * * *'
jobs:
  monitor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install apiworkbench-cli
        run: |
          curl -fsSLO https://github.com/Dhiva-Labs/ApiWorkbench/releases/download/v1.4.0/apiworkbench_1.4.0_amd64.deb
          sudo apt-get update
          sudo apt-get install -y ./apiworkbench_1.4.0_amd64.deb
      - name: Run the monitor
        run: apiworkbench-cli run monitor/health.apiworkbench.json --timeout-request 10000

A failed run fails the job, and the CI system's own notifications do the alerting. See Automating in CI and the command-line runner for every option.

Designing checks that do not cry wolf ​

A monitor that raises false alarms gets ignored, and then it is worthless.

  • Set time limits with room to spare. If the endpoint normally takes 200 ms, alert at 2,000, not 250.
  • Check stable values. status equals ok, not today's count of orders.
  • Alert on repeated failure. One failed pass can be a network blip. Two or three in a row is an outage.
  • Monitor from where your users are, if you can. A check running beside the server proves less than one running outside.
  • Use a dedicated account with the least access that works. Keep its credentials in the scheduler's secret store, and pass them with --env-var.

What a monitor should tell you ​

When it fails, the report should answer three questions without further digging:

  1. What failed: which request, which check.
  2. How: the status and message. expected 200, got 503 is a different incident from a timeout.
  3. Since when: the first failing run.

Keep the junit or html report from each run for that purpose.

Practise with a mock ​

Run a recurring monitor against the Todo API sample in ApiWorkbench, then in Mock Studio:

  • Select Stop on the server. The next pass fails with a connection error.
  • Start it again. The monitor recovers on the next pass.
  • Change the health check's status to 503. A different failure, a different message.

Seeing each failure once makes the real one easier to read.

Next steps ​