Events: What, Why, How?
SPM can graph not only performance and custom metrics, but also events. Such events may represent what is happening with a server or cluster, with an application (e.g., application or server restarts, deployments, alerts...), etc, as well as any sort of other event data that you want to correlate to metrics in SPM. Events are graphed in timeseries charts and these charts can be shown next to all SPM metrics charts. This makes it possible to easily correlate events and metrics. In addition to showing events as timeseries charts, a detailed listing of events can be seen and, of course, events can have tags and priority, and can be searched and filtered.
Events are also exposed via a REST API that let's you post, retrieve, and search your events. This REST API matches the Elasticsearch API, so you can use any Elasticsearch tool or client to post, get, and search events.
Event Fields
An event has the following set of fields, some of which are optional:
| Field Name | Field Type | Required | Notes |
|---|---|---|---|
| token | string | no | Your SPM application token. If you don't populate it, Event Receiver will automatically use the token from request URL. |
| timestamp | date | no | Represents time when event happened (if not specified, Event Receiver will populate it with current time). The format is dateOptionalTime e.g.: 2014-02-17T14:15:01.534471+02:00 |
| message | string | yes | Short description of event, e.g. "Elasticsearch node03 on host somehost06 restarted". This is a default search field in SPM UI, so it is good to keep it concise, but search-friendly. |
| name | string | no | Event name, can be used as a short label for event, e.g. "Elasticsearch restart". |
| tags | string array | no | Multivalued field. Each tag should be specified as a separate array element (e.g., "tags":[ "elasticsearch", "restart", "weekend"]) |
| priority | string | no | You can use any values that make sense to you, like "high", "very high" or 7. Note that sorting on this field will sort in lexicographical order. |
| creator | string | no | Person, application, or component that created an event. E.g., "John Smith", "Elasticsearch", "Some Batch Job" |
| data | string | no | Additional event data. It can be anything you may find useful to have along inside of event object. E.g., it could be stacktrace in case of "app_error" event, base64 encoded content of file generated during "user_registered" event, etc. |
Adding Events
To post an event to your event stream use the following base endpoint:
http://event-receiver.sematext.com/APPLICATION_TOKEN/EVENT_TYPE
A single application token must be specified in the URL. Thus, to send multiple events associated with multiple applications, separate call to the API will need to be made for each application. The EVENT_TYPE can have any value (e.g, alert, app_restart, server_restart, reboot, deployment...), but we suggest having a smaller number of distinct event types (1-10) to keep things manageable.
Example 1:
Consider some SPM application whose token (your app tokens are at: https://apps.sematext.com/users-web/services.do) is 1111111-2222-3333-4444-555555555555. To send a server_restart type of event we'd call the Events API with token and event type to:
http://event-receiver.sematext.com/1111111-2222-3333-4444-555555555555/server_restart/
with post content in JSON format like this:
{
"timestamp" : "2014-02-17T15:29:04+0100",
"message": "Application MyApp on MyHost04 restarted"
}
The easiest way to quickly send an event is using curl, so the same event would be sent with the following command:
curl -XPOST "http://event-receiver.sematext.com/1111111-2222-3333-4444-555555555555/server_restart/" -d '{"timestamp" : "2014-02-17T15:29:04+0100", "message" : "Application MyApp on MyHost04 restarted"}'
Example 2:
Same SPM Solr application, but we want to send deployment event which should have more event properties populated. HTTP post would in that case be sent to:
http://event-receiver.sematext.com/1111111-2222-3333-4444-555555555555/deployment
with content like:
{
"timestamp" : "2014-02-17T15:58:04+0100",
"message": "Solr 4.6.1 version deployed on prodhost06",
"name" : "Solr 4.6.1 deployment",
"tags" : ["solr", "4.6.1", "deployment", "upgrade"],
"priority" : "High",
"creator" : "John Smith"
}
or again with curl:
curl -XPOST "http://event-receiver.sematext.com/1111111-2222-3333-4444-555555555555/deployment/" -d '{"timestamp" : "2014-02-17T15:58:04+0100", "message" : "Solr 4.6.1 version deployed on prodhost06", "name" : "Solr 4.6.1 deployment", "tags" : ["solr", "4.6.1", "deployment", "upgrade"], "priority" : "High", "creator" : "John Smith"}'