api

README

Pulse

Pulse is a stat collecting and publishing service. It serves historical stats over an http api while live stats are sent to mist for live updates.

API

Route	Description	Output
GET /keys	Returns list of stats being recorded	string array
GET /tags	Returns list of filterable tags	string array
GET /latest/{stat}*	Returns latest stat (averages if multiple filters applied)	json stat object
GET /hourly/{stat}**	Returns hourly averages for stat	json array of stat objects
GET /daily/{stat}**	Returns average for stat at the same daily time	string map

ALERTS (requires "kapacitor-address" to be configured)

Route	Description	Payload	Output
POST /alerts	Add a kapacitor alert	json alert object	json alert object
PUT /alerts	Update a kapacitor alert	json alert object	json alert object
DELETE /alerts/{alert}	Delete a kapacitor alert	nil	success message

*: reserved query parameters is 'verb', all others act as filters
**: reserved query parameters are 'backfill', 'verb', 'start', and 'stop', all others act as filters

note: The API requires a token to be passed for authentication by default and is configurable at server start (--token). The token is passed in as a custom header: X-AUTH-TOKEN.

Usage Example:

get latest 'cpu_used' for 'web1' service

$ curl http://localhost:8080/latest/cpu_used?service=web1
# {"time":0,"value":0.2207}

get latest max 'cpu_used' for 'web1', 'web2', and 'web3' services

$ curl "http://localhost:8080/latest/cpu_used?service=web1&service=web2&service=web3&verb=max"
# {"time":0,"value":0.262}

get hourly 'cpu_used' for 'web1' service

$ curl http://localhost:8080/hourly/cpu_used?service=web1
# [{"time":1465419600000,"value":0.22331906098017212}]

get hourly max 'cpu_used' for 'web1', 'web2', and 'web3' services

$ curl "http://localhost:8080/hourly/cpu_used?service=web1&service=web2&service=web3&verb=max"
# [{"time":1465419600000,"value":0.22331906098017212}]

^{note: Multiple filters on hourly needs tested for accuracy}

get daily averages 'cpu_used' for 'web1' service

$ curl http://localhost:8080/daily/cpu_used?service=web1
# {"15:0":0.22501574074074077,"15:15":0.22325925160697888,"15:30":0.22123160173160175}

get daily max 'cpu_used' for 'web1', 'web2', and 'web3' services for the last 3 days

$ curl "http://localhost:8080/daily/cpu_used?service=web1&service=web2&service=web3&verb=max&start=3d"
# [{"time":1465419600000,"value":0.22331906098017212}]

^{note: Multiple filters on daily needs tested for accuracy}

get tags to filter by

$ curl -k -H "X-AUTH-TOKEN: secret" https://localhost:8080/tags
# ["host","service"]

get list of stats stored

$ curl http://localhost:8080/keys
# ["cpu_used","ram_used"]

add alert for cpu_used to trigger critical alert to localhost/alert if cpu_used is > 80 for 30s

$ curl http://localhost:8080/alerts -d '{
  "tags": {"host":"abcd"},
  "metric": "cpu_used",
  "level": "crit",
  "threshold": 80,
  "duration": "30s",
  "post": "http://127.0.0.1/alert"
}'
# {"tags":{"host":"abcd"},"metric":"cpu_used","level":"crit","threshold":80,"duration":"30s","post":"http://127.0.0.1/alert"}

delete alert for cpu_used to trigger critical alert to localhost/alert if cpu_used is > 80 for 30s

$ curl http://localhost:8080/alerts/cpu_used -X DELETE
# {"msg":"Success"}

^{note: Known bug regarding lack of unique alert id}

Documentation

Overview

Package api provides a restful interface to view aggregated stats as well as manage alerts.

Index

• Variables
• func Start() error
• Bugs

Variables

var (
	BadJson      = errors.New("Bad JSON syntax received in body")
	BodyReadFail = errors.New("Body Read Failed")
)

Functions

func Start

func Start() error

start sets the state of the package if the config has all the necessary data for the api and starts the default api server; routing web requests and handling all the routes

Notes

Bugs

• ids are not unique enough for the same stat to be used with different tag sets todo: make id more unique, for use with same stat, multiple tags