Events

The information on this page is written for Vamp v0.9.3

Vamp is a distributed system tied together by a central events stream. Every action in Vamp creates events, which in turn can be used as triggers for new actions. For example, gateway updates are triggered by deployments (synchronisation events), while canary releases and autoscaling actions are based on calculated health and metrics events. Vamp collects events on all running services. Interaction with the API also creates events, like updating blueprints or deleting a deployment. Furthermore, Vamp allows third party applications to create events and trigger Vamp actions. All events are stored and retrieved using the Event API that is part of Vamp.

Example - JSON “deployment create” event

{
  "tags": [
    "deployments",
    "deployments:6ce79a33-5dca-4eb2-b072-d5f65e4eef8a",
    "archiving",
    "archiving:create"
  ],
  "value": "name: sava",
  "timestamp": "2015-04-21T09:15:42Z"
}

Storing events

Vamp events are stored by default in Elasticsearch using the integrated Vamp Pulse module. Elasticsearch indexing is based on the event type and is updated for each event received by the API. Each event type will be indexed individually, including custom event types .

Basic event rules

All events stick to some basic rules:

  • All data in Vamp are events.
  • Events consist of an event type, one or more event tags and an optional event value. They are described in the format ['tag', 'tag1:tag2'], value, event_type
  • Event values can be empty or any JSON object.
  • Event timestamps are in ISO8601/RFC3339.
  • Timestamps are optional. If not provided, Vamp will insert the current time.
  • Timestamps are inclusive for querying.
  • Events can be tagged with metadata. A simple event tag is just single string.
  • Querying data by tag assumes “AND” behaviour when multiple tags are supplied, i.e. [“one”, “two”] would only fetch records that are tagged with both.
  • Supported event aggregations are: average, min, max and count.
  • You can create custom event types, names should only include alphanumerics, ‘_’ and ‘-’

Event type

Vamp works with a number of default event types and custom event types can also be created using the /events API endpoint (more on that later). If no event type is specified when creating an event, the generic event type event will be used. It is advisable to always specify an event type to allow for easy filtering.

Default event types Description
Archive Store/update of static Vamp artifacts (breeds, blueprints etc.)
Synchronisation Successful matching of a desired state with an observed state (for example, a successful update from 3 to 5 running instances)
Event Generic event type, will be used if no event type is specified when creating an event
Health Generated by the health workflow and used by the Vamp UI
Metrics Generated by the metrics workflow and used by the Vamp UI
Allocation Generated by the allocation workflow used to calculate resource usage
Workflow Generated by workflows used in Vamp Runner

Event value

The event value is optional and could be anything you choose to store along with an event. Values are not analysed and can’t be used for search. If no value is specified, it will be blank

Event tags

Each event created by Vamp is given one or more tags. Tags provide meta-information for stored events and are used for filtering searches and listening. Tags can be either a single tag or a combination of two tags separated by a :. The Vamp convention is to use the first tag as a generic label (for example a group) and the second tag as a specific label (i.e. a specific item in a group). generic_tag:specific_tag

How tags are organised

In all of Vamp’s components we follow a REST (resource oriented) schema, for instance:

/deployments/{deployment_name} 
/deployments/{deployment_name}/clusters/{cluster_name}/services/{service_name}

Tagging is done using a very similar schema: “{resource_group}“, “{resource_group}:{name}“. For example:

[
    "deployments", 
    "deployments:{deployment_name}", 
    "clusters", 
    "clusters:{cluster_name}", 
    "services", 
    "services:{service_name}"
]

This schema allows querying per group and per specific name. Getting all events related to all deployments is done by using tag “deployments”. Getting events for specific deployment “deployments:{deployment_name}“.

Query events using tags

Using the tags schema and timestamps, you can do some powerful queries. Either use an exact timestamp or use special range query operators, described on the elastic.co site (elastic.co - Range query).

Note!

the default page size for a set of returned events is 30.

Example queries

Example 1

Get all events

The below query gets ALL metrics events up till now, taking into regard the pagination.

Note!

GET request with body - similar to approach used by Elasticsearch.

GET /api/v1/events

{
  "tags": ["metrics"],
    "timestamp" : {
      "lte" : "now"
    }
}

Example 2

Response time for a cluster

The below query gets the most recent response time events for the “frontend” cluster in the “d9b42796-d8f6-431b-9230-9d316defaf6d” deployment.

Notice the “gateways:”, “metrics:responseTime” and “gateways” tags. This means “give me the response time of this specific gateway at the gateway level”. The response will echo back the events in the time range with the original set of tags associated with the events.

GET /api/v1/events

{
  "tags": ["routes:d9b42796-d8f6-431b-9230-9d316defaf6d_frontend_8080","metrics:rtime","route"],
    "timestamp" : {
      "lte" : "now"
    }
}
[
    {
        "tags": [
            "gateways",
            "gateways:d9b42796-d8f6-431b-9230-9d316defaf6d_frontend_8080",
            "metrics:rate",
            "metrics",
            "gateway"
        ],
        "value": 0,
        "timestamp": "2015-06-08T10:28:35.001Z",
        "type": "gateway-metric"
    },
    {
        "tags": [
            "gateways",
            "gateways:d9b42796-d8f6-431b-9230-9d316defaf6d_frontend_8080",
            "metrics:rate",
            "metrics",
            "gateway"
        ],
        "value": 0,
        "timestamp": "2015-06-08T10:28:32.001Z",
        "type": "gateway-metric"
    }
]    

Example 3

Current sessions for a service

Another example is getting the current sessions for a specific service, in this case the monarch_front:0.2 service that is part of the 214615ec-d5e4-473e-a98e-8aa4998b16f4 deployment and lives in the frontend cluster.

Notice we made the search more specific by specifying the “services” and then “service:” tag. Also, we are using relative timestamps: anything later or equal (lte) than “now”.

GET /api/v1/events

{
  "tags": ["routes:214615ec-d5e4-473e-a98e-8aa4998b16f4_frontend_8080","metrics:scur","services:monarch_front:0.2","service"],
    "timestamp" : {
      "lte" : "now"
    }
}

Example 4

All known events for a service

This below query gives you all the events we have for a specific service, in this case the same service as in example 2. In this way you can get a quick “health snapshot” of service, server, cluster or deployment.

Notice we made the search less specific by just providing the “metrics” tag and not telling the API which specific one we want.

GET /api/v1/events

{
  "tags": ["routes:214615ec-d5e4-473e-a98e-8aa4998b16f4_frontend_8080","metrics","services:monarch_front:0.2","service"],
    "timestamp" : {
      "lte" : "now"
    }
}

Server-sent events (SSE)

Events can be streamed back directly from Vamp.

GET /api/v1/events/stream

In order to narrow down (filter) events, list of tags could be provided in the request body.

{
  "tags": ["routes:214615ec-d5e4-473e-a98e-8aa4998b16f4_frontend_8080","metrics"]
}

GET method can be also used with tag parameter (may be more convenient):

GET /api/v1/events/stream?tag=archiving&tag=breeds

Archiving

All changes in artifacts (creation, update or deletion) triggered by REST API calls are archived. We store the type of event and the original representation of the artifact. It’s a bit like a Git log.

Here is an example event:

{
  "tags": [
    "deployments",
    "deployments:6ce79a33-5dca-4eb2-b072-d5f65e4eef8a",
    "archiving",
    "archiving:delete"
  ],
  "value": "",
  "timestamp": "2015-04-21T09:17:31Z",
  "type": ""
}

Searching through the archive is 100% the same as searching for events. The same tagging scheme applies. The following query gives back the last set of delete actions executed in the Vamp API, regardless of the artifact type.

GET /api/v1/events

{
  "tags": ["archiving","archiving:delete"],
    "timestamp" : {
      "lte" : "now"
    }
}