[apm] Annotation API documentation (#65963)

docs/apm/api.asciidoc

@@ -9,14 +9,45 @@
 Some APM app features are provided via a REST API:
 
 * <<agent-config-api>>
+* <<apm-annotation-api>>
 
-TIP: Kibana provides additional <<api,REST APIs>>,
-and general information on <<using-api,how to use APIs>>.
+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 <<api,REST API reference>> 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
 
@@ -276,4 +307,116 @@ 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:
+
+* <<apm-annotation-create>> to create an annotation for APM.
+// * <<obs-annotation-create>> POST /api/observability/annotation
+// * <<obs-annotation-get>> GET /api/observability/annotation/:id
+// * <<obs-annotation-delete>> 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"
+    }
+  }
+}
+--------------------------------------------------

docs/apm/deployment-annotations.asciidoc

@@ -3,7 +3,7 @@
 === Track deployments with annotations
 
 ++++
-<titleabbrev>Track deployments</titleabbrev>
+<titleabbrev>Track deployments with annotations</titleabbrev>
 ++++
 
 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 <<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.
 
 [role="screenshot"]
 image::apm/images/apm-transaction-annotation.png[Example view of transactions annotation in the APM app in Kibana]

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-*`.