Annotations

[User Guide](User guide)

---

#Working With 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.

##View Annotations You can view annotations separately via the [REST endpoint](annotation resource), or you 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.

##Annotation Structure 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

##Publishing Annotations 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](Web Service API).

######Example: Annotation Payload

[
 {
  "source":"NA1",
  "scope":"scope",
  "metric":"metric",  
  "id":"someUniqueId",
  "fields": {
   "field1":"value1",
   "user":"user1"
  },
  "tags": {
   "tag1":"tag1"
  },
  "timestamp": 1456350741000,
  "type": "ERELEASE"
 }
]

##Querying Annotations You query an annotation via an annotation expression consisting of the time range of interest, scope, metric, and type associated with the annotation.

######Example: Annotation expression with no user specified -4h:scope:metric{tagk=tagv}:type

When no user information is specified, the annotation is visible to all users.

######Example: Annotation expression with user specified information -4h:scope:metric{tagk=tagv}:type:user1

Scoped annotations display information specific to a user. So only annotations belonging to “user1” are displayed.