API and Developer Documentation


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.

Request/Response Structure

The default procedure is to make an urlencoded POST request to the URL given for each method.

The default 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

HTTP POST to: https://observu.com/api/add

Use this method to add new data into Observu. The storage of data is asynchronous, so newly added data may not be immediately available.

Input Parameters

Data should be urlencoded and submitted with Content-type: application/x-www-form-urlencoded.

POST VariableTypeInfo
keyOptional stringan access key obtained from the observu website
sourceOptional stringa string that (uniquely) describes the current monitor
recordsRequired jsona 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.

FieldTypeInfo
statusstring'ok' in case of success, 'error' in case of failure
countstringNumber of successfully processed records

Add New Monitor

HTTP POST to: https://observu.com/api/add-external-monitor

Create a new monitor and return it's access key

Input Parameters

Data should be urlencoded and submitted with Content-type: application/x-www-form-urlencoded.

POST VariableTypeInfo
keyOptional string
usernameOptional string
passwordOptional string
service_nameOptional string
service_idOptional string
monitor_nameOptional string
monitor_typeOptional 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.

FieldTypeInfo
statusstring'ok' in case of success, 'error' in case of failure
keystringMonitor-level access key to this specific monitor
monitor_idintID of the newly created monitor
service_idintID of the service the monitor was created under. Can be new or existing

REST API

The basic structure of our 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/monitors

Which 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

HTTP GET: https://observu.com/monitors

List all monitors currently configured in your account.

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.

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

HTTP GET: https://observu.com/monitors/:id

List a specific monitor by it's id.

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.

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

HTTP GET: https://observu.com/events

List all active and past events by specific criteria

Query Parameters

Data should be urlencoded and passed as query parameters in the URL.

Query ParameterTypeInfo
activeOptional booleanWhether or not to list only active events
priorityOptional numeric setWhich priority events to include, leave empty for all. Multiple priorities can be included like: ?priority%5B%5D=3&priority%5B%5D=4
start_datetimeOptional datetimee.g. ?start_datetime=2013-10-02+00%3A00+%2B0000
start_timestampOptional timestampe.g. ?start_timestamp=1381825014
end_datetimeOptional datetimee.g. ?end_datetime=2013-10-02+00%3A00+%2B0000
end_timestampOptional timestampe.g. ?end_timestamp=1381825014
min_duration_minutesOptional numericminimum duration of the events to return
min_support_percOptional numericmin. percentage of support e.g. 50 will only list events with at least 2 out of 4 monitor locations concurring.
sortOptional stringwhat to sort by e.g. end_timestamp, begin_timestamp or duration
sort_dirOptional stringsort direction: ASC or DESC(default: DESC)

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.

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

HTTP GET: https://observu.com/data

Query Parameters

Data should be urlencoded and passed as query parameters in the URL.

Query ParameterTypeInfo
property_idOptional numeric / stringcomma seperated list of property id's e.g ?property_id=2430,2964,3148
begin_tsOptional timestampe.g. ?begin_ts=1381896600
end_tsOptional timestampe.g. ?begin_ts=1381896600
scaleOptional stringminute or hour

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.

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"
        }
}

        

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 IDNumeric repr.Base TypeDescription
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

TypeNumeric repr.Pretty
URL1HTTP URL
PING2ping
SERVER5Observu Server Agent

Priorities

PriorityNumeric repr.
Interesting2Something is different
Warning3Serious risk of errors, some impact on users
Error4Serious impact on end-users