Annotations
Annotations are objects associated with a timestamp and, optionally, a time series. Annotations are used for recording an event, which can be used to link a time series to an external event.
You can view annotations separately via the [REST endpoint](annotation resource), or you can associate it with a time series. To have an alert notification automatically add an annotation to a time series, specify the metrics to annotate field. When a notification is sent, an annotation is recorded on the corresponding time series.
An annotation includes the metric, scope, source, tags, timestamp, type, and user.
| Component | Description |
|---|---|
| Metric | Metric name |
| Scope | Scope of the annotation object |
| Source | Data source from which the annotation was collected |
| Tags | Additional information in form of tag-key value pair |
| Timestamp | Timestamp at which the annotated event occurs |
| Type | Annotation category |
| User | User associated with the annotation |
The process of writing annotation data to Argus is called publishing annotations. A POST request is issued to the /collection/annotations web service endpoint with a JSON payload describing the annotation data to be written.
Annotation data published to Argus is validated immediately but not committed immediately. The data is enqueued internally and persisted asynchronously using a distributed commit mechanism. The write endpoint method’s latency is in the range of 100 milliseconds. The latency on the commit of annotation data to persistent storage is less than 1 minute. The total time from when an annotation is written to the endpoint to the time it's available in a query result is less than 1 minute. The timing depends on the write load and how your Argus deployment is configured.
NOTE: Detailed information about metric publishing is in the description of the /collection/annotations endpoint section of the Web Services section.
[
{
"source":"NA1",
"scope":"scope",
"metric":"metric",
"id":"someUniqueId",
"fields": {
"field1":"value1",
"user":"user1"
},
"tags": {
"tag1":"tag1"
},
"timestamp": 1456350741000,
"type": "ERELEASE"
}
]You query an annotation via an annotation expression consisting of the time range of interest, scope, metric, and type associated with the annotation.
-4h:scope:metric{tagk=tagv}:type
When no user information is specified, the annotation for all users is displayed.
-4h:scope:metric{tagk=tagv}:type:user1
Scoped annotations display information specific to a user. So only annotations belonging to “user1” are displayed.
Note: Annotations cannot be aggregated so you must use complete tags when querying for annotations.
