x/stacktach-sandbox
Code Issues Proposed changes

API docs

Browse Source 
Started on API docs. Particularly the /streams resource.

Change-Id: I082486fd62158fb175f5a22a3cfba141bb7d1fa1
This commit is contained in:
Sandy Walsh 2015-02-27 07:45:27 -08:00
parent a7e600585e
commit d1cacbcee4
6 changed files with 490 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

485
docs/api.html Normal file
View File

@ -0,0 +1,485 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="StackTach.v3">
<meta name="author" content="Sandy Walsh">
<link rel="icon" href="../../favicon.ico">
<title>StackTach.v3</title>
<!-- Latest compiled and minified CSS -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.2/css/bootstrap.min.css">
<link href="stv3-narrow.css" rel="stylesheet">
<!-- Optional theme -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.2/css/bootstrap-theme.min.css">
<!-- Latest compiled and minified JavaScript -->
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.2/js/bootstrap.min.js"></script>
<style>
.bottom_padding {
padding-bottom: 20px;
}
</style>
<!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body>
<div class="container">
<div class="header bottom_padding">
<nav>
<ul class="nav nav-pills pull-right">
<li role="presentation"><a href="index.html">Home</a></li>
<li role="presentation"><a href="about.html">Docs</a></li>
<li role="presentation"><a href="install.html">Getting Started</a></li>
<li role="presentation" class="active"><a href="api.html">API</a></li>
<li role="presentation"><a href="screencasts.html">Screencasts</a></li>
<li role="presentation"><a href="contribute.html">Contribute</a></li>
</ul>
</nav>
<img src="StackTach_160x70.png"/>
</div>
<div class="row marketing">
<div class="col-lg-12">
<h3>StackTach.v3 REST API</h3>
<div class="panel panel-info">
<div class="panel-heading">
<h3 class="panel-title">GET /v1/streams</h3>
</div>
<div class="panel-body">
<p>Retrieves streams.</p>
<p>Date filters use the <code>first_event</code> and <code>last_event</code> attributes on the stream for comparisons.</p>
<p>Query filter parameters:</p>
<ul>
<li><b>older_than</b> - returns streams where <code>first_event</code> is older than supplied date (in ISO 8601 format). ie: 01-31-2015T13:30</li>
<li><b>younger_than</b> - returns streams where <code>last_event</code> is younger than supplied date (in ISO 8601 format). ie: 01-31-2015T13:30</li>
<li><b>state</b> - returns streams where <code>state</code> is one of:</li>
<ul>
<li>active</li>
<li>firing</li>
<li>expiring</li>
<li>error</li>
<li>expire_error</li>
<li>completed</li>
<li>retry_fire</li>
<li>retry_expire</li>
</ul>
<li><b>trigger_name</b> - returns streams with a specific <code>trigger_name</code></li>
<li><b>distinguishing_traits</b> - returns streams with matching <code>distinguishing_traits</code>. Trait format is <code>trait_name:trait_value;trait_name:trait_value</code></li>
<li><b>mark</b> - returns streams starting from a previously supplied <code>mark</code>. The mark is part of the return value from a previous /streams query. All filter criteria must match the previous query.</li>
<li><b>limit</b> - specifies the number of streams to return in this query. The default is 200 streams. Limit should be kept low to reduce load on the API server.</li>
</ul>
<h4>Sample return data</h4>
<p>Note the <code>__type__</code> keys that give hints to the data type of the return values</p>
<pre class='pre-scrollable'>
curl http://localhost:8000/v1/streams
[
{
"_mark": "2",
"distinguishing_traits": {
"instance_id": "8f81562e-70c9-4541-b054-3826121dc75b",
"timestamp": {
"__type__": "timex.TimeRange",
"begin": "2015-02-27T00:00:00",
"end": "2015-02-28T00:00:00"
}
},
"expire_timestamp": {
"__type__": "datetime",
"datetime": "2015-03-02T00:27:18.603932"
},
"fire_timestamp": {
"__type__": "datetime",
"datetime": "2015-02-27T14:57:32.731196"
},
"first_event": {
"__type__": "datetime",
"datetime": "2015-02-27T18:27:18.603932"
},
"id": 2,
"last_event": {
"__type__": "datetime",
"datetime": "2015-02-28T00:27:18.603932"
},
"name": "test_trigger",
"state": "completed"
},
{
"_mark": "1",
"distinguishing_traits": {
"instance_id": "86def971-f2a2-4b1d-b379-fca1b0ddf0d7",
"timestamp": {
"__type__": "timex.TimeRange",
"begin": "2015-02-27T00:00:00",
"end": "2015-02-28T00:00:00"
}
},
"expire_timestamp": {
"__type__": "datetime",
"datetime": "2015-03-02T00:27:18.603932"
},
"fire_timestamp": {
"__type__": "datetime",
"datetime": "2015-02-27T14:57:32.330963"
},
"first_event": {
"__type__": "datetime",
"datetime": "2015-02-27T15:27:18.603932"
},
"id": 1,
"last_event": {
"__type__": "datetime",
"datetime": "2015-02-28T00:27:18.603932"
},
"name": "test_trigger",
"state": "completed"
}
]
</pre>
</div>
</div>
<div class="panel panel-info">
<div class="panel-heading">
<h3 class="panel-title">GET /v1/streams/&lt;stream_id&gt;</h3>
</div>
<div class="panel-body">
<p>Retrieves a particular stream. <code>stream_id</code> is the id of the desired stream.</p>
<p>Optional parameters:</p>
<ul>
<li><b>details</b> - true/false: returns the event data in a stream if true.
</ul>
<h4>Sample return data</h4>
<pre class='pre-scrollable'>
curl http://localhost:8000/v1/streams/1
[
{
"_mark": "1",
"distinguishing_traits": {
"instance_id": "86def971-f2a2-4b1d-b379-fca1b0ddf0d7",
"timestamp": {
"__type__": "timex.TimeRange",
"begin": "2015-02-27T00:00:00",
"end": "2015-02-28T00:00:00"
}
},
"expire_timestamp": {
"__type__": "datetime",
"datetime": "2015-03-02T00:27:18.603932"
},
"fire_timestamp": {
"__type__": "datetime",
"datetime": "2015-02-27T14:57:32.330963"
},
"first_event": {
"__type__": "datetime",
"datetime": "2015-02-27T15:27:18.603932"
},
"id": 1,
"last_event": {
"__type__": "datetime",
"datetime": "2015-02-28T00:27:18.603932"
},
"name": "test_trigger",
"state": "completed"
}
]
</pre>
<p>And with event details</p>
<pre class='pre-scrollable'>
curl http://localhost:8000/v1/streams/1?detail=true
[
{
"_mark": "1",
"distinguishing_traits": {
"instance_id": "86def971-f2a2-4b1d-b379-fca1b0ddf0d7",
"timestamp": {
"__type__": "timex.TimeRange",
"begin": "2015-02-27T00:00:00",
"end": "2015-02-28T00:00:00"
}
},
"events": [
{
"disk_gb": 20,
"ephemeral_gb": 0,
"event_type": "compute.instance.update",
"instance_flavor": "512MB Standard Instance",
"instance_flavor_id": 2,
"instance_id": "86def971-f2a2-4b1d-b379-fca1b0ddf0d7",
"instance_type": "512MB Standard Instance",
"memory_mb": 512,
"message_id": "936a849a-6eb3-4750-a431-7ca1aec9d611",
"os_architecture": "x64",
"os_distro": "com.ubuntu",
"os_version": "12.04",
"request_id": "req-028c51c6-e26e-4fd7-9347-bc1b2a7eb11a",
"root_gb": 20,
"service": "publisher-482147",
"state": "building",
"tenant_id": "408577",
"timestamp": {
"__type__": "datetime",
"datetime": "2015-02-27T15:27:18.603932"
},
"user_id": "863985",
"vcpus": 1
},
{
"disk_gb": 20,
"ephemeral_gb": 0,
"event_type": "compute.instance.create.start",
"instance_flavor": "512MB Standard Instance",
"instance_flavor_id": 2,
"instance_id": "86def971-f2a2-4b1d-b379-fca1b0ddf0d7",
"instance_type": "512MB Standard Instance",
"memory_mb": 512,
"message": "",
"message_id": "d359a6db-a488-4522-8b94-2ad17fb7ac38",
"os_architecture": "x64",
"os_distro": "com.ubuntu",
"os_version": "12.04",
"request_id": "req-028c51c6-e26e-4fd7-9347-bc1b2a7eb11a",
"root_gb": 20,
"service": "publisher-482147",
"state": "building",
"tenant_id": "408577",
"timestamp": {
"__type__": "datetime",
"datetime": "2015-02-27T15:33:22.667932"
},
"user_id": "863985",
"vcpus": 1
},
{
"disk_gb": 20,
"ephemeral_gb": 0,
"event_type": "compute.instance.update",
"instance_flavor": "512MB Standard Instance",
"instance_flavor_id": 2,
"instance_id": "86def971-f2a2-4b1d-b379-fca1b0ddf0d7",
"instance_type": "512MB Standard Instance",
"launched_at": {
"__type__": "datetime",
"datetime": "2015-02-27T15:31:24.473932"
},
"memory_mb": 512,
"message_id": "fa6f6302-e35e-4c21-a69d-5322497526ed",
"os_architecture": "x64",
"os_distro": "com.ubuntu",
"os_version": "12.04",
"request_id": "req-028c51c6-e26e-4fd7-9347-bc1b2a7eb11a",
"root_gb": 20,
"service": "publisher-482147",
"state": "active",
"tenant_id": "408577",
"timestamp": {
"__type__": "datetime",
"datetime": "2015-02-27T15:33:24.565932"
},
"user_id": "863985",
"vcpus": 1
},
{
"disk_gb": 20,
"ephemeral_gb": 0,
"event_type": "compute.instance.create.end",
"instance_flavor": "512MB Standard Instance",
"instance_flavor_id": 2,
"instance_id": "86def971-f2a2-4b1d-b379-fca1b0ddf0d7",
"instance_type": "512MB Standard Instance",
"launched_at": {
"__type__": "datetime",
"datetime": "2015-02-27T15:31:24.473932"
},
"memory_mb": 512,
"message": "Success",
"message_id": "379cbd38-cae6-44cd-ae8e-5fb05777d1e0",
"os_architecture": "x64",
"os_distro": "com.ubuntu",
"os_version": "12.04",
"request_id": "req-028c51c6-e26e-4fd7-9347-bc1b2a7eb11a",
"root_gb": 20,
"service": "publisher-482147",
"state": "active",
"tenant_id": "408577",
"timestamp": {
"__type__": "datetime",
"datetime": "2015-02-27T15:33:56.771932"
},
"user_id": "863985",
"vcpus": 1
},
{
"disk_gb": 20,
"ephemeral_gb": 0,
"event_type": "compute.instance.update",
"instance_flavor": "512MB Standard Instance",
"instance_flavor_id": 2,
"instance_id": "86def971-f2a2-4b1d-b379-fca1b0ddf0d7",
"instance_type": "512MB Standard Instance",
"memory_mb": 512,
"message_id": "c0784af6-deb7-452d-b09e-5a1dc1ac138f",
"os_architecture": "x64",
"os_distro": "com.ubuntu",
"os_version": "12.04",
"request_id": "req-028c51c6-e26e-4fd7-9347-bc1b2a7eb11a",
"root_gb": 20,
"service": "publisher-482147",
"state": "building",
"tenant_id": "408577",
"timestamp": {
"__type__": "datetime",
"datetime": "2015-02-27T15:40:34.186932"
},
"user_id": "863985",
"vcpus": 1
},
{
"disk_gb": 20,
"ephemeral_gb": 0,
"event_type": "compute.instance.update",
"instance_flavor": "512MB Standard Instance",
"instance_flavor_id": 2,
"instance_id": "86def971-f2a2-4b1d-b379-fca1b0ddf0d7",
"instance_type": "512MB Standard Instance",
"memory_mb": 512,
"message_id": "e1c5ec1c-946d-422f-a890-3248fdf58cc0",
"os_architecture": "x64",
"os_distro": "com.ubuntu",
"os_version": "12.04",
"request_id": "req-028c51c6-e26e-4fd7-9347-bc1b2a7eb11a",
"root_gb": 20,
"service": "publisher-482147",
"state": "building",
"tenant_id": "408577",
"timestamp": {
"__type__": "datetime",
"datetime": "2015-02-27T15:42:34.939932"
},
"user_id": "863985",
"vcpus": 1
},
{
"disk_gb": 20,
"ephemeral_gb": 0,
"event_type": "compute.instance.update",
"instance_flavor": "512MB Standard Instance",
"instance_flavor_id": 2,
"instance_id": "86def971-f2a2-4b1d-b379-fca1b0ddf0d7",
"instance_type": "512MB Standard Instance",
"memory_mb": 512,
"message_id": "6df0588b-2cf2-4f0b-96f3-98c2046f29ff",
"os_architecture": "x64",
"os_distro": "com.ubuntu",
"os_version": "12.04",
"request_id": "req-028c51c6-e26e-4fd7-9347-bc1b2a7eb11a",
"root_gb": 20,
"service": "publisher-482147",
"state": "building",
"tenant_id": "408577",
"timestamp": {
"__type__": "datetime",
"datetime": "2015-02-27T15:43:25.091932"
},
"user_id": "863985",
"vcpus": 1
},
{
"audit_period_beginning": {
"__type__": "datetime",
"datetime": "2015-02-27T00:00:00"
},
"audit_period_ending": {
"__type__": "datetime",
"datetime": "2015-02-28T00:00:00"
},
"disk_gb": 620,
"ephemeral_gb": 0,
"event_type": "compute.instance.exists",
"instance_flavor": "15GB Standard Instance",
"instance_flavor_id": 7,
"instance_id": "86def971-f2a2-4b1d-b379-fca1b0ddf0d7",
"instance_type": "15GB Standard Instance",
"launched_at": {
"__type__": "datetime",
"datetime": "2014-12-15T13:22:12.015932"
},
"memory_mb": 15360,
"message_id": "a16aa892-6e62-47fd-8aee-5183ef71d605",
"os_architecture": "x64",
"os_distro": "com.ubuntu",
"os_version": "12.04",
"request_id": "req-d14c8981-db18-4d1e-b17c-e7931fd2a0e9",
"root_gb": 620,
"service": "publisher-262311",
"state": "active",
"tenant_id": "714200",
"timestamp": {
"__type__": "datetime",
"datetime": "2015-02-28T00:27:18.603932"
},
"user_id": "960064",
"vcpus": 6
}
],
"expire_timestamp": {
"__type__": "datetime",
"datetime": "2015-03-02T00:27:18.603932"
},
"fire_timestamp": {
"__type__": "datetime",
"datetime": "2015-02-27T14:57:32.330963"
},
"first_event": {
"__type__": "datetime",
"datetime": "2015-02-27T15:27:18.603932"
},
"id": 1,
"last_event": {
"__type__": "datetime",
"datetime": "2015-02-28T00:27:18.603932"
},
"name": "test_trigger",
"state": "completed"
}
]
</pre>
</div>
</div>
<footer class="footer">
<p>&copy; Dark Secret Software Inc. 2014</p>
</footer>
</div> <!-- /container -->
<!-- IE10 viewport hack for Surface/desktop Windows 8 bug -->
<script src="../../assets/js/ie10-viewport-bug-workaround.js"></script>
</body>
</html>

2
docs/contribute.html
View File

@ -46,7 +46,7 @@
<li role="presentation"><a href="index.html">Home</a></li> <li role="presentation"><a href="index.html">Home</a></li>
<li role="presentation"><a href="about.html">Docs</a></li> <li role="presentation"><a href="about.html">Docs</a></li>
<li role="presentation"><a href="install.html">Getting Started</a></li> <li role="presentation"><a href="install.html">Getting Started</a></li>
<li role="presentation"><a href="#">API</a></li> <li role="presentation"><a href="api.html">API</a></li>
<li role="presentation"><a href="screencasts.html">Screencasts</a></li> <li role="presentation"><a href="screencasts.html">Screencasts</a></li>
<li role="presentation" class="active"><a href="contribute.html">Contribute</a></li> <li role="presentation" class="active"><a href="contribute.html">Contribute</a></li>
</ul> </ul>

2
docs/glossary.html
View File

@ -46,7 +46,7 @@
<li role="presentation"><a href="index.html">Home</a></li> <li role="presentation"><a href="index.html">Home</a></li>
<li role="presentation"><a href="about.html">Docs</a></li> <li role="presentation"><a href="about.html">Docs</a></li>
<li role="presentation"><a href="install.html">Getting Started</a></li> <li role="presentation"><a href="install.html">Getting Started</a></li>
<li role="presentation"><a href="#">API</a></li> <li role="presentation"><a href="api.html">API</a></li>
<li role="presentation"><a href="screencasts.html">Screencasts</a></li> <li role="presentation"><a href="screencasts.html">Screencasts</a></li>
<li role="presentation"><a href="contribute.html">Contribute</a></li> <li role="presentation"><a href="contribute.html">Contribute</a></li>
</ul> </ul>

2
docs/index.html
View File

@ -46,7 +46,7 @@
<li role="presentation" class="active"><a href="#">Home</a></li> <li role="presentation" class="active"><a href="#">Home</a></li>
<li role="presentation"><a href="about.html">Docs</a></li> <li role="presentation"><a href="about.html">Docs</a></li>
<li role="presentation"><a href="install.html">Getting Started</a></li> <li role="presentation"><a href="install.html">Getting Started</a></li>
<li role="presentation"><a href="#">API</a></li> <li role="presentation"><a href="api.html">API</a></li>
<li role="presentation"><a href="screencasts.html">Screencasts</a></li> <li role="presentation"><a href="screencasts.html">Screencasts</a></li>
<li role="presentation"><a href="contribute.html">Contribute</a></li> <li role="presentation"><a href="contribute.html">Contribute</a></li>
</ul> </ul>

2
docs/install.html
View File

@ -46,7 +46,7 @@
<li role="presentation"><a href="index.html">Home</a></li> <li role="presentation"><a href="index.html">Home</a></li>
<li role="presentation"><a href="about.html">Docs</a></li> <li role="presentation"><a href="about.html">Docs</a></li>
<li role="presentation" class="active"><a href="install.html">Getting Started</a></li> <li role="presentation" class="active"><a href="install.html">Getting Started</a></li>
<li role="presentation"><a href="#">API</a></li> <li role="presentation"><a href="api.html">API</a></li>
<li role="presentation"><a href="screencasts.html">Screencasts</a></li> <li role="presentation"><a href="screencasts.html">Screencasts</a></li>
<li role="presentation"><a href="contribute.html">Contribute</a></li> <li role="presentation"><a href="contribute.html">Contribute</a></li>
</ul> </ul>

2
docs/screencasts.html
View File

@ -46,7 +46,7 @@
<li role="presentation"><a href="index.html">Home</a></li> <li role="presentation"><a href="index.html">Home</a></li>
<li role="presentation"><a href="about.html">Docs</a></li> <li role="presentation"><a href="about.html">Docs</a></li>
<li role="presentation"><a href="install.html">Getting Started</a></li> <li role="presentation"><a href="install.html">Getting Started</a></li>
<li role="presentation"><a href="#">API</a></li> <li role="presentation"><a href="api.html">API</a></li>
<li role="presentation" class="active"><a href="screencasts.html">Screencasts</a></li> <li role="presentation" class="active"><a href="screencasts.html">Screencasts</a></li>
<li role="presentation"><a href="contribute.html">Contribute</a></li> <li role="presentation"><a href="contribute.html">Contribute</a></li>
</ul> </ul>