stacktach-sandbox/docs/api.html
Levi Blackstone 1efff2974a Update example timestamps to comply with ISO 8601
Change-Id: I066d7bc916fcb1cb42d325bb7530fabf45ab69f9
2015-04-03 09:09:34 -05:00

701 lines
26 KiB
HTML

<!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>
<h2>StackTach.v3 REST API</h2>
<div class="row marketing">
<div class="col-lg-12">
<h3>Streams</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: 2015-02-28T13:30</li>
<li><b>younger_than</b> - returns streams where <code>last_event</code> is younger than supplied date (in ISO 8601 format). ie: 2015-02-28T13: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>
<div class="panel panel-info">
<div class="panel-heading">
<h3 class="panel-title">GET /v1/streams/count</h3>
</div>
<div class="panel-body">
<p>Retrieves the number of streams matching filter criteria.</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: 2015-02-28T13:30</li>
<li><b>younger_than</b> - returns streams where <code>last_event</code> is younger than supplied date (in ISO 8601 format). ie: 2015-02-28T13: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>
</ul>
<h4>Sample return data</h4>
<pre class='pre-scrollable'>
curl http://localhost:8000/v1/streams/count
[23]
</pre>
</div>
</div>
<div class="panel panel-info">
<div class="panel-heading">
<h3 class="panel-title">DELETE /v1/streams/&lt;stream_id&gt;</h3>
</div>
<div class="panel-body">
<p>Delete stream. Associated events are not deleted.
This assumes <code>purge_completed_streams</code> is False
in your winchester config file.</p>
<ul>
<li><b>stream_id</b> - integer stream id</li>
</ul>
<h4>Sample return data</h4>
<pre class='pre-scrollable'>
curl -x DELETE http://localhost:8000/v1/streams/123
</pre>
</div>
</div>
<div class="panel panel-info">
<div class="panel-heading">
<h3 class="panel-title">PUT /v1/streams/&lt;stream_id&gt;</h3>
</div>
<div class="panel-body">
<p>Reset a stream from the error state. Streams in <code>error</code>
state go to <code>retry_fire</code> and <code>expire</code> goes to
<code>retry_expire</code> state.</p>
<ul>
<li><b>stream_id</b> - integer stream id</li>
</ul>
<h4>Sample return data</h4>
<pre class='pre-scrollable'>
curl -H "X-HTTP-Method-Override: PUT" -X POST http://localhost:8000/v1/streams/123
</pre>
</div>
</div>
<h2>Events</h2>
<div class="panel panel-info">
<div class="panel-heading">
<h3 class="panel-title">GET /v1/events</h3>
</div>
<div class="panel-body">
<p>Retrieves events matching filter criteria.</p>
<p>Date filters use the <code>timestamp</code> attribute on the event for comparisons.</p>
<p>Query filter parameters:</p>
<ul>
<li><b>from_datetime</b> - returns events where <code>timestamp</code> is greater than supplied date (in ISO 8601 format). ie: 2015-02-28T13:30</li>
<li><b>to_datetime</b> - returns events where <code>timestamp</code> is less than supplied date (in ISO 8601 format). ie: 2015-02-28T13:30</li>
<li><b>event_name</b> - returns events with a specific <code>event_name</code></li>
<li><b>traits</b> - returns events with matching <code>traits</code>. Trait format is <code>trait_name:trait_value;trait_name:trait_value</code></li>
<li><b>mark</b> - returns events starting with event id greater than <code>mark</code></li>
<li><b>limit</b> - returns this many events maximum. Default: 200</li>
</ul>
<h4>Sample return data</h4>
<div class="alert alert-warning" role="alert"><b>Remember</b>: the traits you get back will depend on the distiller configuration you've established.</div>
<pre class='pre-scrollable'>
curl "http://localhost:8000/v1/events?from_datetime=2015-03-04T22:25&to_datetime=2015-03-04T22:45"
[
{
"_mark": "280",
"disk_gb": 20,
"display_name": "Instance_358720",
"ephemeral_gb": 0,
"event_type": "compute.instance.unrescue.start",
"instance_type": "512MB Standard Instance",
"launched_at": {
"__type__": "datetime",
"datetime": "2015-03-04T22:41:40.771441"
},
"memory_mb": 512,
"message_id": "4e38d6aa-8fd3-4f26-9293-b621735ea322",
"os_architecture": "x64",
"os_distro": "org.centos",
"os_version": "6.4",
"request_id": "req-a71cc334-926a-45cb-9ca2-3644f143d0ad",
"root_gb": 20,
"service": "publisher-15829",
"state": "rescued",
"state_description": "",
"tenant_id": "685053",
"timestamp": {
"__type__": "datetime",
"datetime": "2015-03-04T22:33:55.204441"
},
"user_id": "701363",
"vcpus": 1
},
{
"_mark": "27a",
"disk_gb": 20,
"display_name": "Instance_358720",
"ephemeral_gb": 0,
"event_type": "compute.instance.update",
"instance_flavor": "512MB Standard Instance",
"instance_flavor_id": 2,
"instance_id": "2fd4d09f-b685-4a80-9b6b-793da76db70e",
"instance_type": "512MB Standard Instance",
"launched_at": {
"__type__": "datetime",
"datetime": "2015-03-04T22:41:40.771441"
},
"memory_mb": 512,
"message_id": "b920513c-4dae-474c-b164-71e23349d131",
"os_architecture": "x64",
"os_distro": "org.centos",
"os_version": "6.4",
"request_id": "req-a71cc334-926a-45cb-9ca2-3644f143d0ad",
"root_gb": 20,
"service": "publisher-15829",
"state": "rescued",
"state_description": "unrescuing",
"tenant_id": "685053",
"timestamp": {
"__type__": "datetime",
"datetime": "2015-03-04T22:31:08.131441"
},
"user_id": "701363",
"vcpus": 1
}
]
</pre>
</div>
</div>
<div class="panel panel-info">
<div class="panel-heading">
<h3 class="panel-title">GET /v1/events/&lt;message_id&gt;</h3>
</div>
<div class="panel-body">
<p>Retrieves a single event given the <code>message_id</code></p>
<h4>Sample return data</h4>
<div class="alert alert-warning" role="alert"><b>Remember</b>: the traits you get back will depend on the distiller configuration you've established.</div>
<pre class='pre-scrollable'>
curl "http://localhost:8000/v1/events/b920513c-4dae-474c-b164-71e23349d131"
[
{
"disk_gb": 20,
"display_name": "Instance_358720",
"ephemeral_gb": 0,
"event_type": "compute.instance.update",
"instance_flavor": "512MB Standard Instance",
"instance_flavor_id": 2,
"instance_id": "2fd4d09f-b685-4a80-9b6b-793da76db70e",
"instance_type": "512MB Standard Instance",
"launched_at": {
"__type__": "datetime",
"datetime": "2015-03-04T22:41:40.771441"
},
"memory_mb": 512,
"message_id": "b920513c-4dae-474c-b164-71e23349d131",
"os_architecture": "x64",
"os_distro": "org.centos",
"os_version": "6.4",
"request_id": "req-a71cc334-926a-45cb-9ca2-3644f143d0ad",
"root_gb": 20,
"service": "publisher-15829",
"state": "rescued",
"state_description": "unrescuing",
"tenant_id": "685053",
"timestamp": {
"__type__": "datetime",
"datetime": "2015-03-04T22:31:08.131441"
},
"user_id": "701363",
"vcpus": 1
}
]
</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>