These endpoints provides a means of adding, editing or deleting annotations stored in the OpenTSDB backend. Annotations are very basic objects used to record a note of an arbitrary event at some point, optionally associated with a timeseries. Annotations are not meant to be used as a tracking or event based system, rather they are useful for providing links to such systems by displaying a notice on graphs or via API query calls.
When creating, modifying or deleting annotations, all changes will be propagated to the search plugin if configured.
The default /annotation endpoint deals with one notation at a time. The /annotation/bulk endpoint allows for adding or updating multiple annotations at a time.
All annotations are identified by the startTime field and optionally the tsuid field. Each note can be global, meaning it is associated with all timeseries, or it can be local, meaning it's associated with a specific tsuid. If the tsuid is not supplied or has an empty value, the annotation is considered to be a global note.
| Name | Data Type | Required | Description | Default | QS | RW | Example |
|---|---|---|---|---|---|---|---|
| startTime | Integer | Required | A Unix epoch timestamp, in seconds, marking the time when the annotation event should be recorded | start_time | RW | 1369141261 | |
| endTime | Integer | Optional | An optional end time for the event if it has completed or been resolved | 0 | end_time | RW | 1369141262 |
| tsuid | String | Optional | A TSUID if the annotation is associated with a timeseries. This may be null or empty if the note was for a global event | tsuid | RW | 000001000001000001 | |
| description | String | Optional | A brief description of the event. As this may appear on GnuPlot graphs, the description should be very short, ideally less than 25 characters. | description | RW | Network Outage | |
| notes | String | Optional | Detailed notes about the event | notes | RW | Switch #5 died and was replaced | |
| custom | Map | Optional | A key/value map to store custom fields and values | null | RW | See Below |
Note
Custom fields cannot be passed via query string. You must use the POST or PUT verbs.
Warning
If your request uses PUT, any fields that you do not supply with the request will be overwritten with their default values. For example, the description field will be set to an empty string and the custom field will be reset to null.
http://localhost:4242/api/annotation?start_time=1369141261&tsuid=000001000001000001
{
"startTime":"1369141261",
"tsuid":"000001000001000001",
"description": "Testing Annotations",
"notes": "These would be details about the event, the description is just a summary",
"custom": {
"owner": "jdoe",
"dept": "ops"
}
}
A successful response to a GET, POST or PUT request will return the full object with the requested changes. Successful DELETE calls will return with a 204 status code and no body content. When modifying data, if no changes were present, i.e. the call did not provide any data to store, the response will be a 304 without any body content. If the requested annotation did not exist in the system, a 404 will be returned with an error message. If invalid data was supplied a 400 error will be returned.
{
"tsuid": "000001000001000001",
"description": "Testing Annotations",
"notes": "These would be details about the event, the description is just a summary",
"custom": {
"owner": "jdoe",
"dept": "ops"
},
"endTime": 0,
"startTime": 1369141261
}
© 2010–2016 The OpenTSDB Authors
Licensed under the GNU LGPLv2.1+ and GPLv3+ licenses.
http://opentsdb.net/docs/build/html/api_http/annotation/index.html