Annotation APIedit
The Annotation API allows you to annotate visualizations in the APM app with significant events, like deployments, allowing you to easily see how these events are impacting the performance of your existing applications.
By default, annotations are stored in a newly created observability-annotations index.
The name of this index can be changed in your config.yml by editing xpack.observability.annotations.index.
If you change the default index name, you’ll also need to update your user privileges accordingly.
The following APIs are available:
- Create or update annotation to create an annotation for APM.
How to use APM APIsedit
Expand for required headers, privileges, and usage details
Interact with APM APIs using cURL or another API tool. All APM APIs are Kibana APIs, not Elasticsearch APIs; because of this, the Kibana dev tools console cannot be used to interact with APM APIs.
For all APM APIs, you must use a request header.
Supported headers are Authorization, kbn-xsrf, and Content-Type.
-
Authorization: ApiKey {credentials} -
Kibana supports token-based authentication with the Elasticsearch API key service. The API key returned by the Elasticsearch create API key API can be used by sending a request with an
Authorizationheader that has a value ofApiKeyfollowed by the{credentials}, where{credentials}is the base64 encoding ofidandapi_keyjoined by a colon.Alternatively, you can create a user and use their username and password to authenticate API access:
-u $USER:$PASSWORD.Whether using
Authorization: ApiKey {credentials}, or-u $USER:$PASSWORD, users interacting with APM APIs must have sufficient privileges. -
kbn-xsrf: true -
By default, you must use
kbn-xsrffor all API calls, except in the following scenarios:-
The API endpoint uses the
GETorHEADoperations -
The path is allowed using the
server.xsrf.allowlistsetting -
XSRF protections are disabled using the
server.xsrf.disableProtectionsetting
-
The API endpoint uses the
-
Content-Type: application/json -
Applicable only when you send a payload in the API request.
Kibana API requests and responses use JSON.
Typically, if you include the
kbn-xsrfheader, you must also include theContent-Typeheader.
Create or update annotationedit
Requestedit
POST /api/apm/services/:serviceName/annotation
Request bodyedit
-
service -
(required, object) Service identifying the configuration to create or update.
Properties of
service-
version - (required, string) Version of service.
-
environment - (optional, string) Environment of service.
-
-
@timestamp - (required, string) The date and time of the annotation. Must be in ISO 8601 format.
-
message -
(optional, string) The message displayed in the annotation. Defaults to
service.version. -
tags -
(optional, array) Tags are used by the APM app to distinguish APM annotations from other annotations.
Tags may have additional functionality in future releases. Defaults to
[apm]. While you can add additional tags, you cannot remove theapmtag.
Exampleedit
The following example creates an annotation for a service named opbeans-java.
curl -X POST \
http://localhost:5601/api/apm/services/opbeans-java/annotation \
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'Authorization: Basic YhUlubWZhM0FDbnlQeE6WRtaW49FQmSGZ4RUWXdX' \
-d '{
"@timestamp": "2020-05-08T10:31:30.452Z",
"service": {
"version": "1.2"
},
"message": "Deployment 1.2"
}'
Response bodyedit
{
"_index": "observability-annotations",
"_id": "Lc9I93EBh6DbmkeV7nFX",
"_version": 1,
"_seq_no": 12,
"_primary_term": 1,
"found": true,
"_source": {
"message": "Deployment 1.2",
"@timestamp": "2020-05-08T10:31:30.452Z",
"service": {
"version": "1.2",
"name": "opbeans-java"
},
"tags": [
"apm",
"elastic.co",
"customer"
],
"annotation": {
"type": "deployment"
},
"event": {
"created": "2020-05-09T02:34:43.937Z"
}
}
}