diff --git a/docs/api.rst b/docs/api.rst index e256c2c..481bfeb 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -114,10 +114,9 @@ stacky/hosts ["scheduler-x"], ["api-88"], ... - ] :query service: ``nova`` or ``glance``. default="nova" - + ] stacky/uuid =========== @@ -174,27 +173,376 @@ stacky/uuid :query service: ``nova`` or ``glance``. default="nova" -stacky/timings -============== +stacky/timings/uuid/ +==================== -stacky/timings/uuid -=================== +.. http:get:: http://example.com/stacky/timings/uuid/ + + Retrieve all timings for a given instance. Timings are the time + deltas between related .start and .end notifications. For example, + the time difference between ``compute.instance.run_instance.start`` + and ``compute.instance.run_instance.end``. + + The first column of the response will be + + * ``S`` if there is a ``.start`` event and no ``.end`` + * ``E`` if there is a ``.end`` event and no ``.start`` + * ``.`` if there was a ``.start`` and ``.end`` event + + No time difference will be returned in the ``S`` or ``E`` cases. + + **Example request**: + + .. sourcecode:: http + + GET /stacky/timings/uuid/?uuid=77e0f192-00a2-4f14-ad56-7467897828ea HTTP/1.1 + Host: example.com + Accept: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: text/json + + [ + ["?", "Event", "Time (secs)"], + [".", "compute.instance.create", "0d 00:00:55.50"], + [".", "compute.instance.snapshot", "0d 00:14:11.71"], + [".", "compute.instance.snapshot", "0d 00:17:31.33"], + [".", "compute.instance.snapshot", "0d 00:16:48.88"] + ... + ] + + :query uuid: UUID of desired instance. + :query service: ``nova`` or ``glance``. default="nova" stacky/summary ============== +.. http:get:: http://example.com/stacky/summary/ + + Returns timing summary information for each event type + collected. Only notifications with ``.start``/``.end`` pairs + are considered. + + This includes: :: + + * the number of events seen of each type (N) + * the Minimum time seen + * the Maximum time seen + * the Average time seen + + **Example request**: + + .. sourcecode:: http + + GET /stacky/summary/ HTTP/1.1 + Host: example.com + Accept: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: text/json + + [ + ["Event", "N", "Min", "Max", "Avg"], + ["compute.instance.create", 50, + "0d 00:00:52.88", "0d 01:41:14.27", "0d 00:08:26"], + ["compute.instance.create_ip", 50, + "0d 00:00:06.80", "5d 20:16:47.08", "0d 03:47:17"], + ... + ] + + :query uuid: UUID of desired instance. + :query service: ``nova`` or ``glance``. default="nova" + :query limit: the number of timings to return. + :query offset: offset into query result set to start from. + + stacky/request ============== +.. http:get:: http://example.com/stacky/request/ + + Returns all notifications related to a particular Request ID. + + The ``?`` column will be ``E`` if the event came from the ``.error`` + queue. ``State`` and ``State'`` are the current state and the previous + state, respectively. + + **Example request**: + + .. sourcecode:: http + + GET /stacky/request/?request_id=req-a7517402-6192-4d0a-85a1-e14051790d5a HTTP/1.1 + Host: example.com + Accept: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: text/json + + [ + ["#", "?", "When", "Deployment", "Event", "Host", "State", + "State'", "Task'" + ], + [ + 40368306, + " ", + "2014-01-15 15:39:34.130286", + "region-1", + "compute.instance.update", + "api-1", + "active", + "active", + null + ], + [ + 40368308, + " ", + "2014-01-15 15:39:34.552434", + "region-1", + "compute.instance.update", + "api-1", + "active", + null, + null + ], + + ... + ] + + :query request_id: desired request ID + :query when_min: unixtime to start search + :query when_max: unixtime to end search + :query limit: the number of timings to return. + :query offset: offset into query result set to start from. + + stacky/reports ============== +.. http:get:: http://example.com/stacky/reports/ + + Returns a list of all available reports. + + The ``Start`` and ``End`` columns refer to the time span + the report covers (in unixtime). + + **Example request**: + + .. sourcecode:: http + + GET /stacky/reports/ HTTP/1.1 + Host: example.com + Accept: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: text/json + + [ + ["Id", "Start", "End", "Created", "Name", "Version"], + [ + 5971, + 1389726000.0, + 1389729599.0, + 1389730212.9474499, + "summary for region: all", + 4 + ], + [ + 5972, + 1389729600.0, + 1389733199.0, + 1389733809.979934, + "summary for region: all", + 4 + ], + + ... + ] + + :query created_from: unixtime to start search + :query created_to: unixtime to end search + :query limit: the number of timings to return. + :query offset: offset into query result set to start from. + stacky/report/ ========================= +.. http:get:: http://example.com/stacky/report/ + + Returns a specific report. + + The contents of the report varies by the specific report, but + all are in row/column format with Row 0 being a special *metadata* row. + + Row 0 of each report is a dictionary of metadata about the report. The + actual row/columns of the report start at Row 1 onwards (where Row 1 + is the Column headers and Rows 2+ are the details, as with other result + sets) + + **Example request**: + + .. sourcecode:: http + + GET /stacky/report/1/ HTTP/1.1 + Host: example.com + Accept: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: text/json + + [ + { + "4xx failure count": 0, + "4xx failure percentage": 0.0, + "5xx failure count": 1, + "5xx failure percentage": 0.018284904, + "> 30 failure count": 13, + "> 30 failure percentage": 1.13479794, + "cells": [ + "c0001", + "global", + "c0003", + "c0004", + "c0011", + "c0010", + "a0001", + "c0012", + "b0002", + "a0002" + ], + "end": 1389729599.0, + "failure_grand_rate": 0.2445074415308293, + "failure_grand_total": 14, + "hours": 1, + "pct": 0.014999999999999999, + "percentile": 97, + "region": null, + "start": 1389726000.0, + "state failure count": 0, + "state failure percentage": 0.0, + "total": 411 + }, + ["Operation", "Image", "OS Type", "Min", "Max", "Med", "97%", "Requests", + "4xx", "% 4xx", "5xx", "% 5xx", "> 30", "% > 30", "state", "% state"], + [ + "aux", + "snap", + "windows", + "0s", + "5s", + "0s", + "5s", + 6, + 0, + 0.0, + 0, + 0.0, + 0, + 0.0, + 0, + 0.0 + ], + [ + "resize", + "base", + "linux", + "1s", + "5:44s", + "1:05s", + "3:44s", + 9, + 0, + 0.0, + 0, + 0.0, + 0, + 0.0, + 0, + 0.0 + ], + + ... + ] + stacky/show/ ====================== +.. http:get:: http://example.com/stacky/show// + + Show the details on a specific notification. + + The response of this operation is non-standard. It returns 3 rows: + + * The first row is the traditional row-column result set used by most + commands. + * The second row is a prettied, stringified version of the full JSON payload + of the raw notification. + * The third row is the UUID of the related instance, if any. + + **Example request**: + + .. sourcecode:: http + + GET /stacky/show/1234/ HTTP/1.1 + Host: example.com + Accept: application/json + + **Example response**: + + .. sourcecode:: http + + HTTP/1.1 200 OK + Vary: Accept + Content-Type: text/json + + [ + [ + ["Key", "Value"], + ["#", 1234 ], + ["When", "2014-01-15 20:39:44.277745"], + ["Deployment", "region-1"], + ["Category", "monitor.info"], + ["Publisher", "compute-1"], + ["State", "active"], + ["Event", "compute.instance.update"], + ["Service", "compute"], + ["Host", "compute-1"], + ["UUID", "8eba1a6d-43eb-1343-8d1a-5e596f5233b5"], + ["Req ID", "req-1368539d-f645-4d96-842e-03b5c5c9dc8c"], + ... + ], + "[\n \"monitor.info\", \n {\n \"_context_request_id\": \"req-13685e9d-f645-4d96-842e-03b5c5c9dc8c\", \n \"_context_quota_class\": null, \n \"event_type\": \"compute.instance.update\", \n \"_context_service_catalog\": [], \n \"_context_auth_token\": \"d81a25d03bb340bb82b4b67d105cc42d\", \n \"_context_user_id\": \"b83e2fac644c4215bc449fb4b5c9bbfa\", \n \"payload\": {\n \"state_description\": \"\", \n \"availability_zone\": null, \n \"terminated_at\": \"\", \n \"ephemeral_gb\": 300, \n ...", + "8eba1a6d-43eb-1343-8d1a-5e596f5233b5" + ] + + :query service: ``nova`` or ``glance``. default="nova" + :query event_id: desired Event ID + + stacky/watch/ ============================