The StackTach REST Interface

JSON Response Format

StackTach uses an tabular JSON response format to make it easier for Stacky to display generic results.

The JSON response format is as follows:

[
  ['column header', 'column header', 'column header', ...],
  ['row 1, col 1', 'row 1, col 2', 'row 1, col 3', ...],
  ['row 2, col 1', 'row 2, col 2', 'row 2, col 3', ...],
  ['row 3, col 1', 'row 3, col 2', 'row 3, col 3', ...],
  ...
]

stacky/deployments

GET http://example.com/stacky/deployments/

The list of all available deployments

Example request:

GET /stacky/deployments/ HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/json

[
  ['#', 'Name'],
  [1, 'deployment name'],
  [2, 'deployment name'],
  ...
]

stacky/events

GET http://example.com/stacky/events/

The distinct list of all event names

Example request:

GET /stacky/events/ HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/json

[
  ['Event Name'],
  ["add_fixed_ip_to_instance"],
  ["attach_volume"],
  ["change_instance_metadata"],
  ["compute.instance.create.end"],
  ["compute.instance.create.error"],
  ["compute.instance.create.start"],
  ["compute.instance.create_ip.end"],
  ...
]
Query Parameters:
 
  • servicenova or glance. default=”nova”

stacky/hosts

GET http://example.com/stacky/hosts/

The distinct list of all hosts sending notifications.

Example request:

GET /stacky/hosts/ HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/json

[
  ['Host Name'],
  ["compute-1"],
  ["compute-2"],
  ["scheduler-x"],
  ["api-88"],
  ...
Query Parameters:
 
  • servicenova or glance. default=”nova” ]

stacky/uuid

GET http://example.com/stacky/uuid/

Retrieve all notifications for instances with a given UUID.

Example request:

GET /stacky/uuid/?uuid=77e0f192-00a2-4f14-ad56-7467897828ea  HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/json

[
  ["#", "?", "When", "Deployment", "Event", "Host", "State",
   "State'", "Task"],
  [
      40065869,
      " ",
      "2014-01-14 15:39:22.574829",
      "region-1",
      "compute.instance.snapshot.start",
      "compute-99",
      "active",
      "",
      ""
  ],
  [
      40065879,
      " ",
      "2014-01-14 15:39:23.599298",
      "region-1",
      "compute.instance.update",
      "compute-99",
      "active",
      "active",
      "image_snapshot"
  ],
  ...
]
Query Parameters:
 
  • uuid – UUID of desired instance.
  • servicenova or glance. default=”nova”

stacky/timings/uuid/

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. This url works only for nova.

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:

GET /stacky/timings/uuid/?uuid=77e0f192-00a2-4f14-ad56-7467897828ea  HTTP/1.1
Host: example.com
Accept: application/json

Example response:

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 Parameters:
 
  • uuid – UUID of desired instance.

stacky/summary

GET http://example.com/stacky/summary/

Returns timing summary information for each event type collected. Only notifications with .start/.end pairs are considered. This url works only for nova.

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:

GET /stacky/summary/  HTTP/1.1
Host: example.com
Accept: application/json

Example response:

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 Parameters:
 
  • uuid – UUID of desired instance.
  • limit – the number of timings to return.
  • offset – offset into query result set to start from.

stacky/request

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. This url works only for nova.

Example request:

GET /stacky/request/?request_id=req-a7517402-6192-4d0a-85a1-e14051790d5a  HTTP/1.1
Host: example.com
Accept: application/json

Example response:

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 Parameters:
 
  • request_id – desired request ID
  • when_min – unixtime to start search
  • when_max – unixtime to end search
  • limit – the number of timings to return.
  • offset – offset into query result set to start from.

stacky/reports

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:

GET /stacky/reports/ HTTP/1.1
Host: example.com
Accept: application/json

Example response:

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 Parameters:
 
  • created_from – unixtime to start search
  • created_to – unixtime to end search
  • limit – the number of timings to return.
  • offset – offset into query result set to start from.

stacky/report/<report_id>

GET http://example.com/stacky/report/<report_id>

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:

GET /stacky/report/1/ HTTP/1.1
Host: example.com
Accept: application/json

Example response:

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/<event_id>

GET http://example.com/stacky/show/<event_id>/

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:

GET /stacky/show/1234/  HTTP/1.1
Host: example.com
Accept: application/json

Example response:

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 Parameters:
 
  • servicenova or glance. default=”nova”
  • event_id – desired Event ID

stacky/watch/<deployment_id>

GET http://example.com/stacky/watch/<deployment_id>/

Get a real-time feed of notifications.

Once again, this is a non-standard response (not the typical row-column format). This call returns a tuple of information:

  • A list of column widths, to be used as a hint for formatting.

  • A list of events that meet the query criteria. * the db id of the event * the type of event (E for errors, . otherwise) * stringified date of the event * stringified time of the event * deployment name * the event name * the instance UUID, if available

  • The ending unixtime timestamp. The last time covered by this query (utcnow, essentially)

    Example request:

GET /stacky/watch/14/  HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/json

[
  [10, 1, 15, 20, 50, 36],
  [
  ... events ...
  ]
  "1389892207"
]
Query Parameters:
 
  • servicenova or glance. default=”nova”
  • since – get all events since unixtime. Defaults to 2 seconds ago.
  • event_name – only watch for event_name notifications. Defaults to all events.