Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[apm] docs: add deployment annotation example #67408

Merged
merged 2 commits into from
Jun 4, 2020
Merged

[apm] docs: add deployment annotation example #67408

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bfa118e
docs: add deployment annotation example
bmorelli25 May 26, 2020
cffbc06
Update docs/apm/deployment-annotations.asciidoc
bmorelli25 Jun 4, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 33 additions & 6 deletions docs/apm/deployment-annotations.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 deploy has increased response times for an end-user,
bmorelli25 marked this conversation as resolved.
Show resolved Hide resolved
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dgieselaar Can automatic deployment annotations be disabled? If so, how?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They can't really be disabled. The only thing that you can do to have them not show up is either by not setting service.version, or storing an annotation via the API, and then derived annotations will still be displayed for date ranges without a stored annotation.

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 <<apm-annotation-api,annotation API>> reference for more information.

Deployment annotations are enabled by default, and can be created with the <<apm-annotation-api,annotation API>>.
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dgieselaar Oh, I guess this covers it. Still, users might want to keep automatic annotations even after posting manual annotation, so I think it should be possible to configure this.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you think we should add it now or wait until there's a request from a user to support it?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Waiting is fine


Expand Down