StackTach.v3 REST API
Streams
GET /v1/streams
Retrieves streams.
Date filters use the first_event and last_event attributes on the stream for comparisons.
Query filter parameters:
- older_than - returns streams where
first_eventis older than supplied date (in ISO 8601 format). ie: 2015-02-28T13:30 - younger_than - returns streams where
last_eventis younger than supplied date (in ISO 8601 format). ie: 2015-02-28T13:30 - state - returns streams where
stateis one of: - active
- firing
- expiring
- error
- expire_error
- completed
- retry_fire
- retry_expire
- trigger_name - returns streams with a specific
trigger_name - distinguishing_traits - returns streams with matching
distinguishing_traits. Trait format istrait_name:trait_value;trait_name:trait_value - mark - returns streams starting from a previously supplied
mark. The mark is part of the return value from a previous /streams query. All filter criteria must match the previous query. - limit - 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.
Sample return data
Note the __type__ keys that give hints to the data type of the return values
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"
}
]
GET /v1/streams/<stream_id>
Retrieves a particular stream. stream_id is the id of the desired stream.
Optional parameters:
- details - true/false: returns the event data in a stream if true.
Sample return data
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"
}
]
And with event details
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"
}
]
GET /v1/streams/count
Retrieves the number of streams matching filter criteria.
Date filters use the first_event and last_event attributes on the stream for comparisons.
Query filter parameters:
- older_than - returns streams where
first_eventis older than supplied date (in ISO 8601 format). ie: 2015-02-28T13:30 - younger_than - returns streams where
last_eventis younger than supplied date (in ISO 8601 format). ie: 2015-02-28T13:30 - state - returns streams where
stateis one of: - active
- firing
- expiring
- error
- expire_error
- completed
- retry_fire
- retry_expire
- trigger_name - returns streams with a specific
trigger_name - distinguishing_traits - returns streams with matching
distinguishing_traits. Trait format istrait_name:trait_value;trait_name:trait_value
Sample return data
curl http://localhost:8000/v1/streams/count
[23]
DELETE /v1/streams/<stream_id>
Delete stream. Associated events are not deleted.
This assumes purge_completed_streams is False
in your winchester config file.
- stream_id - integer stream id
Sample return data
curl -x DELETE http://localhost:8000/v1/streams/123
PUT /v1/streams/<stream_id>
Reset a stream from the error state. Streams in error
state go to retry_fire and expire goes to
retry_expire state.
- stream_id - integer stream id
Sample return data
curl -H "X-HTTP-Method-Override: PUT" -X POST http://localhost:8000/v1/streams/123
Events
GET /v1/events
Retrieves events matching filter criteria.
Date filters use the timestamp attribute on the event for comparisons.
Query filter parameters:
- from_datetime - returns events where
timestampis greater than supplied date (in ISO 8601 format). ie: 2015-02-28T13:30 - to_datetime - returns events where
timestampis less than supplied date (in ISO 8601 format). ie: 2015-02-28T13:30 - event_name - returns events with a specific
event_name - traits - returns events with matching
traits. Trait format istrait_name:trait_value;trait_name:trait_value - mark - returns events starting with event id greater than
mark - limit - returns this many events maximum. Default: 200
Sample return data
Remember: the traits you get back will depend on the distiller configuration you've established.
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
}
]
GET /v1/events/<message_id>
Retrieves a single event given the message_id
Sample return data
Remember: the traits you get back will depend on the distiller configuration you've established.
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
}
]