- The API Entrypoint
- API Request/Response Structure
- Submitting Data To The Monitoring API
- Add New Monitor
- REST API for reading and writing monitoring data
- /monitors - List All Monitors
- /monitors/:id - get monitor by id
- /events - list events
- /data - Retrieve monitoring data
- API Constants
The API Entrypoint
Our API has two specific methods for adding data and monitors, which are listed first. Furthermore all data that has been added to the system is available as a REST API which is described afterwards.
API Request/Response Structure
The default procedure is to make an urlencoded POST request to the URL given for each method.
The default API response is a JSON structure, which will contain at least a status field that will be either ok or error. In case of an error status, there will be a structure like:
{
status: 'error',
error_code: 'ERR_ACCESS',
error_message:'...human readable error message'
}
in case of success the structure will depend on the individual method that was called.
Submitting Data To The Monitoring API
Use this method to add new data into Observu. The storage of data is asynchronous, so newly added data may not be immediately available.
API Request Input Parameters
Data should be urlencoded and submitted with Content-type: application/x-www-form-urlencoded.
| POST Variable | Type | Info |
|---|---|---|
| key | Optional string | an access key obtained from the observu website |
| source | Optional string | a string that (uniquely) describes the current monitor |
| records | Required json | a JSON encoded set of records that need to be added to the system. The records variable should look something like:
[
{"timestamp": 1234568, /* unix timestamp of the event */
"monitor_id":24324, /* only required if not implied by the API key */
"monitor_name":"my host", /* only required if not implied by the API key
and monitor_id is unknown, this requires the API
key to specify at least the service/group level
*/
"monitor_tags":{ /* not required */
"role": "web"
},
"data": { /* required */
'load:float': 4.52,
'disks.dev_sda.available:bytes': 523453,
'apache_running:boolean': true,
/*........ more vars */
},
/*................ more records .......... */
] |
The HTTP response will be a JSON encoded object (Content-type: application/json), in case of a successfull response it will contain the following fields.
| Field | Type | Info |
|---|---|---|
| status | string | 'ok' in case of success, 'error' in case of failure |
| count | string | Number of successfully processed records |
Add New Monitor
Create a new monitor and return it's access key
API Request Input Parameters
Data should be urlencoded and submitted with Content-type: application/x-www-form-urlencoded.
| POST Variable | Type | Info |
|---|---|---|
| key | Optional string | |
| username | Optional string | |
| password | Optional string | |
| service_name | Optional string | |
| service_id | Optional string | |
| monitor_name | Optional string | |
| monitor_type | Optional string | (default: 5) |
The HTTP response will be a JSON encoded object (Content-type: application/json), in case of a successfull response it will contain the following fields.
| Field | Type | Info |
|---|---|---|
| status | string | 'ok' in case of success, 'error' in case of failure |
| key | string | Monitor-level access key to this specific monitor |
| monitor_id | int | ID of the newly created monitor |
| service_id | int | ID of the service the monitor was created under. Can be new or existing |
REST API for reading and writing monitoring data
The basic structure of our monitoring API is fairly straight forward: any URL on the website can be turned into a JSON formatted resource by either passing Accept: application/json as a header in the request or by appending ".json" as an extention to the URL.
Basic HTTP Authentication
The easiest way to authorize yourself is by providing your login credentials as Basic HTTP authentication.
Sample using curl
curl -u test:1234 -H "Accept:application/json" https://observu.com/monitorsWhich will make a request to the /monitors resource for user test with password 1234.
Token based authentication
For specific monitors or services you can use token based authentication.
/monitors - List All Monitors
List all monitors currently configured in your account.
The HTTP API response will be a JSON encoded object (Content-type: application/json), in case of a successfull response it will contain the following fields.
Sample response
{
"monitors": [
{
"id": 1,
"name": "Observu Availability",
"type": 1,
"service_id": 1,
"url": "https://observu.com",
"interval": 60,
"expect_content": "monitor"
}
]
}
/monitors/:id - get monitor by id
List a specific monitor by it's id.
The HTTP API response will be a JSON encoded object (Content-type: application/json), in case of a successfull response it will contain the following fields.
Sample response
{
"monitor":
{
"id": 1,
"name": "Observu Availability",
"type": 1,
"service_id": 1,
"url": "https://observu.com",
"interval": 60,
"expect_content": "monitor"
},
"properties":
{
"total_time": [
{
"id": 671,
"name": "total_time",
"source": "urlmonitor_US_aws-east1",
"type": 5
},
{
"id": 672,
"name": "total_time",
"source": "urlmonitor_EU_aws-west1",
"type": 5
}
]
},
"active_events":[
{
"id":"2116490",
"name":"Slow URL",
"rule_id":"3",
"monitor_id":"1",
"priority":"3",
"property_name":"total_time",
"info":"4.718032",
"event_timestamp":"1381904221",
"measurement_count":"1",
"sources_count":"1",
"against_measurement_count":"5",
"support":"0.25",
"ack":null,
"created":"2013-10-16 06:17:52",
"updated":"2013-10-16 06:19:19"
}
],
"latest_events":[
{
"id":"2116490",
"name":"Slow URL",
"rule_id":"3",
"monitor_id":"1",
"priority":"3",
"property_name":"total_time",
"info":"4.718032",
"event_timestamp":"1381904221",
"end_timestamp":"1381904342",
"measurement_count":"1",
"sources_count":"1",
"against_measurement_count":"5",
"support":"0.25",
"ack":null,
"created":"2013-10-16 06:17:52",
"updated":"2013-10-16 06:19:19"
}
],
"service":
{
"id": 1,
"name": "Observu"
},
"urls":
{
"edit_monitor": "https://observu.com/monitors/1/edit",
"monitor_detail": "https://observu.com/monitors/1",
"service_detail": "https://observu.com/services/1"
}
}
/events - list events
List all active and past events by specific criteria
API Request Query Parameters
Data should be urlencoded and passed as query parameters in the URL.
| Query Parameter | Type | Info |
|---|---|---|
| active | Optional boolean | Whether or not to list only active events |
| priority | Optional numeric set | Which priority events to include, leave empty for all. Multiple priorities can be included like: ?priority%5B%5D=3&priority%5B%5D=4 |
| start_datetime | Optional datetime | e.g. ?start_datetime=2013-10-02+00%3A00+%2B0000 |
| start_timestamp | Optional timestamp | e.g. ?start_timestamp=1381825014 |
| end_datetime | Optional datetime | e.g. ?end_datetime=2013-10-02+00%3A00+%2B0000 |
| end_timestamp | Optional timestamp | e.g. ?end_timestamp=1381825014 |
| min_duration_minutes | Optional numeric | minimum duration of the events to return |
| min_support_perc | Optional numeric | min. percentage of support e.g. 50 will only list events with at least 2 out of 4 monitor locations concurring. |
| sort | Optional string | what to sort by e.g. end_timestamp, begin_timestamp or duration |
| sort_dir | Optional string | sort direction: ASC or DESC(default: DESC) |
The HTTP API response will be a JSON encoded object (Content-type: application/json), in case of a successfull response it will contain the following fields.
Sample response
{"events":[
{
"id":"2116853",
"name":"High CPU Usage",
"rule_id":"3012",
"monitor_id":"938",
"priority":"2",
"property_name":"cpu.idle",
"property_ids":null,
"info":"0.034123869646818",
"event_timestamp":"1381910185",
"end_timestamp":"0",
"measurement_count":"1",
"sources_count":"1",
"against_measurement_count":"0",
"support":"1",
"ack":null,
"created":"2013-10-16 07:57:34",
"updated":"2013-10-16 07:57:34",
"app_id":null,
"rec_id":null,
"uid":null,
"archive":"0",
"status":null,
"duration":"1",
"monitor":{
"id":"938",
"name":"test.ec2",
"type":"5",
"service_id":"17",
"checker_settings":null,
"created":"2013-07-30 12:32:37",
"updated":"2013-07-30 12:32:37",
"app_id":null,
"rec_id":null,
"uid":"1",
"archive":"0",
"status":"1",
"meta":[],
"service":{
"id":"17",
"name":"Observu",
"type":"3",
"parent_id":null,
"auto_archive":null,
"created":"2011-02-11 11:36:40",
"updated":"2011-02-11 11:36:40",
"app_id":null,
"rec_id":null,
"uid":"1",
"archive":null,
"status":null}
},
"detail_url":"https:\/\/observu.com\/events\/2116853"
},
]
"conditions":
{
"min_duration":0,
"active":true
}
}/data - Retrieve monitoring data
API Request Query Parameters
Data should be urlencoded and passed as query parameters in the URL.
| Query Parameter | Type | Info |
|---|---|---|
| property_id | Optional numeric / string | comma seperated list of property id's e.g ?property_id=2430,2964,3148 |
| begin_ts | Optional timestamp | e.g. ?begin_ts=1381896600 |
| end_ts | Optional timestamp | e.g. ?begin_ts=1381896600 |
| scale | Optional string | minute or hour |
The HTTP API response will be a JSON encoded object (Content-type: application/json), in case of a successfull response it will contain the following fields.
Sample response
{
"data":
{
"2794":{
"id":"2794",
"name":"connect_time",
"pretty":"Connect time",
"type":"5",
"data":{
"event_timestamp":[1381896661,1381897021,1381897261,1381897501,
1381897862,1381898161,1381898462,1381898761,1381899061,
1381899301,1381899662,1381899962,1381900262,1381900621,
1381900861,1381901101,1381901462,1381901761,1381902001,
1381902242,1381902541,1381902781,1381903142,1381903502,
1381903802,1381904042,1381904341,1381904642,1381905121,
1381905361,1381905601,1381905841,1381906142,1381906381,
1381906682,1381906981,1381907462,1381907821,1381908121,
1381908421,1381908721,1381909021,1381909381,1381909682,
1381909982,1381910282,1381910582,1381910881,1381911121,
1381911481],
"value":["0.21238","0.211987","0.123225","0.277666","0.192088",
"0.181585","0.121383","0.521781","0.245452","0.356953",
"0.141771","0.119141","0.197402","0.145979","0.201831",
"0.10936","0.224976","0.109763","0.314986","0.214095",
"0.259288","0.273699","0.180135","0.193795","0.139822",
"0.126578","0.131736","0.176617","0.32221","0.11937",
"0.303054","0.287431","0.116255","0.17785","0.129297",
"0.203714","0.137778","0.191393","0.112122","0.226435",
"0.118407","0.150998","0.117217","0.490978","0.19398",
"0.118728","0.158431","0.154729","0.368129","0.413637"]
,"count":50
},
"sampled":1,
"monitor_name":"picturepush URL",
"monitor_id":"1",
"source":"urlmonitor_US_aws-east1"},
"4547":{
"id":"4547",
"name":"connect_time",
"pretty":"Connect time",
"type":"5",
"data":{
"event_timestamp": [ 1381896662,1381896962,1381897262,
1381897562,1381897862,1381898282,1381898522,1381898881,
1381899242,1381899541,1381899842,1381900082,1381900322,
1381900621,1381900862,1381901162,1381901462,1381901761,
1381902122,1381902362,1381902662,1381903022,1381903381,
1381903681,1381904042,1381904402,1381904642,1381904941,
1381905242,1381905482,1381905781,1381906082,1381906322,
1381906742,1381907042,1381907342,1381907701,1381907941,
1381908241,1381908482,1381908841,1381909202,1381909442,
1381909741,1381910102,1381910402,1381910763,1381911002,
1381911362,1381911662],
"value": [ "0.21677","0.217523","0.232275","0.251221",
"0.239458","0.284154","0.213766","0.20435","0.213631",
"0.252877","0.263305","0.295329","0.246822","0.200433",
"0.265453","0.303403","0.214165","0.322499","0.225386",
"0.232194","0.233745","0.176325","0.216467","0.254387",
"0.178956","0.200335","0.190509","0.198034","0.198652",
"0.216807","0.191296","0.206602","0.206229","0.259545",
"0.246217","0.234832","0.242754","0.258386","0.21291",
"0.178833","0.202352","0.200828","0.169612","0.33061",
"0.22558","0.312803","0.198255","0.231611","0.215259",
"0.271422"],
"count":50
},
"sampled":1,
"monitor_name":"picturepush URL",
"monitor_id":"1","source":"urlmonitor_US_aws-west2"}
},
"count":10,
"grouping":[
{
"name":"connect_time",
"prop_name_pattern":"connect_time",
"label":"Connect time",
"type":"5",
"monitor_ids":["1"],
"properties":[
{"id":"2794",
"name":"connect_time",
"source":"urlmonitor_US_aws-east1",
"monitor_id":"1",
"type":"5",
"created":"2011-09-26 16:51:03",
"updated":"2011-09-26 16:51:03",
"app_id":null,
"rec_id":null,
"uid":null,
"archive":null,
"status":null,
"monitor_name":"picturepush URL"},
{"id":"4547",
"name":"connect_time",
"source":"urlmonitor_SG_aws-west2",
"monitor_id":"1",
"type":"5",
"created":"2011-10-03 21:36:08",
"updated":"2011-10-03 21:36:08",
"app_id":null,
"rec_id":null,
"uid":null,
"archive":null,
"status":null,
"monitor_name":"picturepush URL"},
]
}
],
"query":{
"property_id":"671,747,1470,2126,2430,2794,2964,3148,3607,4547",
"scale":"minute",
"begin_ts":"1381896600"
}
}
API Constants
The API uses several numeric constants to identify types of monitors and properties.
Property Types
The table below lists all available property types. Providing your data with the most accurate type will provide extra hints to the system for proper reporting and representation.
| Type ID | Numeric repr. | Base Type | Description |
|---|---|---|---|
| string | 1 | String | |
| float | 2 | Numeric | Float |
| int | 3 | Numeric | Integer |
| bytes | 4 | Numeric | |
| seconds | 5 | Numeric | |
| boolean | 6 | Discrete (represented as Integer) | |
| percentage | 7 | Numeric | |
| http_code | 8 | Discrete (represented as Integer) | |
| error_code | 9 | Discrete (represented as Integer) | |
| milliseconds | 10 | Numeric | |
| kilobytes | 11 | Numeric | |
| Bps | 12 | Numeric | Bytes per second |
| tsv | 13 | Table (represented as tsv String) | Table represented as a tab-seperated string |
| ps_tsv | 14 | Table (represented as tsv String) | Process table represented as a tab separated string |
| Ops | 15 | Numeric | Operations per second |
| log | 16 | String | Chunk of logfile |
| har | 17 | Requested Page Resources | |
| megabytes | 18 | Numeric |
Note: The types with base type 'Discrete' are intended to be used if there is a limited set of possible values. E.g. error codes or system state. Each value can be represented by any integer, but the total number of different values should be limited per property. (Preferably at most a few dozen)
Monitor Types
| Type | Numeric repr. | Pretty |
|---|---|---|
| URL | 1 | HTTP URL |
| PING | 2 | ping |
| SERVER | 5 | Observu Server Agent |
Priorities
| Priority | Numeric repr. | |
|---|---|---|
| Interesting | 2 | Something is different |
| Warning | 3 | Serious risk of errors, some impact on users |
| Error | 4 | Serious impact on end-users |
