Skip to content

Latest commit

 

History

History
215 lines (170 loc) · 6.11 KB

CheckupAPI.md

File metadata and controls

215 lines (170 loc) · 6.11 KB

CheckupAPI

This is an API for data generated by the checkup tool.

Note: The API prefix is currently /api/v1. For example, to use the check endpoint the path is /api/v1/check.

Check

GET /check

Returns a short status of the latest checks, with the checks timestamp.

Parameter Description
format Output format: json, plain (default: plain)

Current Status

GET /status
GET /status/{site}

Returns the current status with the details of the last check, for a given site if the site title is provided.

Parameter Description
format Output format: json, plain (default: json)
details If set to 1, display detailed results (plain output)

Timelines

GET /timeline
GET /timeline/{site}

Returns the global timeline, or the timeline for a given site.

Parameter Description
format Output format: json, plain (default: json)
allstates Display all records (not only state changes) if set to 1
limit Limit the output to the given number of results
start Display records from this UNIX timestamp
end Display records until this UNIX timestamp
reverse If set to 1, reverse output order, display last record first (plain output only)
details If set to 1, display detailed results (plain output)

Statistics

GET /stats
GET /stats/{site}

Returns the statistics, for a given site if the site title is provided.

Parameter Description
format Output format: json, plain (default: json)
limit Compute statistics based on a limited number of results
start Use records from this UNIX timestamp
end Use records until this UNIX timestamp

Global Checkup

GET /checkup

Returns JSON data with several pieces of information (status, latest results, statistics and global timeline). This endpoint is intended to be used by frontends.

Parameter Description
limit Limit the number of events in the timeline
start Use records from this UNIX timestamp (timeline)
end Use records until this UNIX timestamp (timeline)
stats_start Compute statistics since this UNIX timestamp
stats_end Compute statistics until this UNIX timestamp

Examples

Global health

Degraded system:

% curl -s "http://localhost:8801/api/v1/check"
DEGRADED	2017-08-14 13:36:11.172206168 +0200 CEST

% curl -s "http://localhost:8801/api/v1/check?format=json"
{"status":"DEGRADED","timestamp":"1502710571"}

Healthy system:

% curl -s "http://localhost:8801/api/v1/check"
OK	2017-08-14 18:21:12.924297223 +0200 CEST

Current status

Note: there is only 1 configured site in the following example.

% curl -s "http://localhost:8801/api/v1/status?format=plain"
Check timestamp: 2017-08-14 13:36:11.172206168 +0200 CEST

== MCabber - https://mcabber.com
  Threshold: 0s
        Max: 10.000189368s
        Min: 10.000189368s
     Median: 10.000189368s
       Mean: 10.000189368s
        All: [{10.000189368s Get https://mcabber.com: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)}]
 Assessment: down

% curl -s "http://localhost:8801/api/v1/status" | jq .
[
  {
    "title": "MCabber",
    "endpoint": "https://mcabber.com",
    "timestamp": 1502710561168856000,
    "times": [
      {
        "rtt": 10000189368,
        "error": "Get https://mcabber.com: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)"
      }
    ],
    "down": true
  }
]

Event Timelines

State changes for a given site for the last 8 hours (use allstates=1 to get all records):

% curl -s "http://localhost:8801/api/v1/timeline/MCabber?format=plain&details=1&start=$(date +%s -d "8 hours ago")"
== MCabber - https://mcabber.com
  Threshold: 0s
        Max: 1.161048474s
        Min: 1.161048474s
     Median: 1.161048474s
       Mean: 1.161048474s
        All: [{1.161048474s }]
 Assessment: healthy
State change: false
Timestamp:    2017-08-14 10:49:03.887247101 +0200 CEST

== MCabber - https://mcabber.com
  Threshold: 0s
        Max: 10.000189368s
        Min: 10.000189368s
     Median: 10.000189368s
       Mean: 10.000189368s
        All: [{10.000189368s Get https://mcabber.com: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)}]
 Assessment: down
State change: true
Timestamp:    2017-08-14 13:36:11.172206168 +0200 CEST

State changes for all sites for the last 24 hours, more recent first:

% curl -s "http://localhost:8801/api/v1/timeline?format=plain&reverse=1&start=$(date +%s -d "1 day ago")"

For a script-friendly JSON output:

% curl -s "http://localhost:8801/api/v1/timeline?start=$(date +%s -d "1 day ago")"

Complete plain-text timeline of state changes recorded for the "LMWEB" website, last event first:

% curl -s "http://localhost:8801/api/v1/timeline/LMWEB?format=plain&reverse=1"
== LMWEB - https://lmwww.test.local/
Assessment:   healthy
Timestamp:    2017-08-07 22:35:50.391241518 +0200 CEST

== LMWEB - https://lmwww.test.local/
Assessment:   down
   Results:   [{5.742818945s Get https://lmwww.test.local/: net/http: timeout awaiting response headers}]
Timestamp:    2017-08-07 22:34:53.047248253 +0200 CEST

== LMWEB - https://lmwww.test.local/
Assessment:   healthy
Timestamp:    2017-08-07 22:15:51.883855662 +0200 CEST

Statistics

Global Statistics:

% curl -s "http://localhost:8801/api/v1/stats?format=plain"
First check timestamp: 2017-08-07 19:43:49 +0200 CEST
Last  check timestamp: 2017-08-15 12:15:12 +0200 CEST
Check count: 11706
Healthy/Degraded/Down counts: 11686/0/20
Healthy/Degraded/Down % rate: 99.83/0.00/0.17

Site-specific statistics, in JSON:

% curl -s "http://localhost:8801/api/v1/stats/MySite" | jq .
{
  "FirstTimestamp": 1502127829608248000,
  "LastTimestamp": 1502791872316004400,
  "ItemsCount": 2936,
  "HealthyCount": 2930,
  "DegradedCount": 0,
  "DownCount": 6,
  "HealthyPC": 99.79564032697547,
  "DegradedPC": 0,
  "DownPC": 0.20435967302452315
}