diff --git a/docs/apm/api.asciidoc b/docs/apm/api.asciidoc index b26c7446b91d11..3e4b515e009de1 100644 --- a/docs/apm/api.asciidoc +++ b/docs/apm/api.asciidoc @@ -9,14 +9,45 @@ Some APM app features are provided via a REST API: * <> - -TIP: Kibana provides additional <>, -and general information on <>. +* <> + +Here's an example CURL request that adds an annotation to the APM app: + +[source,curl] +---- +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-11T10:31:30.452Z", + "service": { + "version": "1.2" + }, + "message": "Revert upgrade", + "tags": [ + "elastic.co", "customer" + ] + }' +---- + +For more information, the Kibana <> provides information on how to use Kibana APIs, +like required request headers and authentication options. + +// AGENT CONFIG API +// GET --> Feature (APM) Read +// CREATE/EDIT/DELETE --> Feature (APM) All + +// ANNOTATION API +// Feature (APM) All +// Index: `observability-annotations`. Privileges: `create_index`, `create_doc`, `manage`, and `read`. //// ******************************************************* //// +[role="xpack"] [[agent-config-api]] === Agent Configuration API @@ -274,6 +305,118 @@ POST /api/apm/settings/agent-configuration/search } -------------------------------------------------- +//// +******************************************************* +******************************************************* +//// + +[role="xpack"] +[[apm-annotation-api]] +=== Annotation API + +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. + +The following APIs are available: + +* <> to create an annotation for APM. +// * <> POST /api/observability/annotation +// * <> GET /api/observability/annotation/:id +// * <> DELETE /api/observability/annotation/:id + +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`. + //// ******************************************************* //// + +[[apm-annotation-create]] +==== Create or update annotation + +[[apm-annotation-config-req]] +===== Request + +`POST /api/apm/services/:serviceName/annotation` + +[role="child_attributes"] +[[apm-annotation-config-req-body]] +===== Request body + +`service`:: +(required, object) Service identifying the configuration to create or update. ++ +.Properties of `service` +[%collapsible%open] +====== +`version` ::: + (required, string) Name of service. + +`environment` ::: + (optional, string) Environment of service. +====== + +`@timestamp`:: +(required, string) The date and time of the annotation. Must be in https://www.w3.org/TR/NOTE-datetime[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 the `apm` tag. + +[[apm-annotation-config-example]] +===== Example + +The following example creates an annotation for a service named `opbeans-java`. + +[source,console] +-------------------------------------------------- +POST /api/apm/services/opbeans-java/annotation +{ + "@timestamp": "2020-05-08T10:31:30.452Z", + "service": { + "version": "1.2" + }, + "message": "Deployment 1.2", + "tags": [ + "elastic.co", "customer" + ] +} +-------------------------------------------------- + +[[apm-annotation-config-body]] +===== Response body + +[source,js] +-------------------------------------------------- +{ + "_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" + } + } +} +-------------------------------------------------- diff --git a/docs/apm/deployment-annotations.asciidoc b/docs/apm/deployment-annotations.asciidoc index 6feadf8463226b..9abcd9f6efc740 100644 --- a/docs/apm/deployment-annotations.asciidoc +++ b/docs/apm/deployment-annotations.asciidoc @@ -3,7 +3,7 @@ === Track deployments with annotations ++++ -Track deployments +Track deployments with annotations ++++ For enhanced visibility into your deployments, we offer deployment annotations on all transaction charts. @@ -11,7 +11,11 @@ This feature automatically tags new deployments, so you can easily see if your d 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. -Deployment annotations are automatically enabled, and appear when the `service.version` of your app changes. +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. [role="screenshot"] image::apm/images/apm-transaction-annotation.png[Example view of transactions annotation in the APM app in Kibana] diff --git a/docs/apm/images/apm-transaction-annotation.png b/docs/apm/images/apm-transaction-annotation.png index bc71b1d2169c49..8913770517ff6f 100644 Binary files a/docs/apm/images/apm-transaction-annotation.png and b/docs/apm/images/apm-transaction-annotation.png differ diff --git a/docs/settings/apm-settings.asciidoc b/docs/settings/apm-settings.asciidoc index efc43e5d2f52d8..b7819304852439 100644 --- a/docs/settings/apm-settings.asciidoc +++ b/docs/settings/apm-settings.asciidoc @@ -52,6 +52,9 @@ Changing these settings may disable features of the APM App. | `xpack.apm.ui.maxTraceItems` {ess-icon} | Maximum number of child items displayed when viewing trace details. Defaults to `1000`. +| `xpack.observability.annotations.index` + | Index name where Observability annotations are stored. Defaults to `observability-annotations`. + | `apm_oss.indexPattern` {ess-icon} | The index pattern used for integrations with Machine Learning and Query Bar. It must match all apm indices. Defaults to `apm-*`.