From c9f71dd7174b7a1f3b51f4a45bda83d63d007dfc Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 3 Jun 2020 21:03:04 -0700 Subject: [PATCH] [apm] docs: add deployment annotation example (#67408) --- docs/apm/deployment-annotations.asciidoc | 39 ++++++++++++++++++++---- 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/docs/apm/deployment-annotations.asciidoc b/docs/apm/deployment-annotations.asciidoc index 9abcd9f6efc74..142b0c0193d74 100644 --- a/docs/apm/deployment-annotations.asciidoc +++ b/docs/apm/deployment-annotations.asciidoc @@ -7,13 +7,40 @@ ++++ For enhanced visibility into your deployments, we offer deployment annotations on all transaction charts. -This feature automatically tags new deployments, so you can easily see if your deploy has increased response times -for an end-user, or if the memory/CPU footprint of your application has changed. -Being able to identify bad deployments quickly enables you to rollback and fix issues without causing costly outages. +This feature enables you to easily determine if your deployment has increased response times for an end-user, +or if the memory/CPU footprint of your application has changed. +Being able to quickly identify bad deployments enables you to rollback and fix issues without causing costly outages. + +By default, automatic deployment annotations are enabled. +This means the APM app will create an annotation on your data when the `service.version` of your application changes. + +Alternatively, you can explicitly create deployment annotations with our annotation API. +The API can integrate into your CI/CD pipeline, +so that each time you deploy, a POST request is sent to the annotation API endpoint: + +[source,console] +---- +curl -X POST \ + http://localhost:5601/api/apm/services/${SERVICE_NAME}/annotation \ <1> +-H 'Content-Type: application/json' \ +-H 'kbn-xsrf: true' \ +-H 'Authorization: Basic ${API_KEY}' \ <2> +-d '{ + "@timestamp": "${DEPLOY_TIME}", <3> + "service": { + "version": "${SERVICE_VERSION}" <4> + }, + "message": "${MESSAGE}" <5> + }' +---- +<1> The `service.name` of your application +<2> An APM app API key with sufficient privileges +<3> The time of the deployment +<4> The `service.version` to be displayed in the annotation +<5> A custom message to be displayed in the annotation + +See the <> reference for more information. -Deployment annotations are enabled by default, and can be created with the <>. -If there are no created annotations for the selected time period, -the APM app will automatically annotate your data if the `service.version` of your application changes. NOTE: If custom annotations have been created for the selected time period, any derived annotations, i.e., those created automatically when `service.version` changes, will not be shown.