|
9 | 9 | Some APM app features are provided via a REST API: |
10 | 10 |
|
11 | 11 | * <<agent-config-api>> |
12 | | - |
13 | | -TIP: Kibana provides additional <<api,REST APIs>>, |
14 | | -and general information on <<using-api,how to use APIs>>. |
| 12 | +* <<apm-annotation-api>> |
| 13 | + |
| 14 | +Here's an example CURL request that adds an annotation to the APM app: |
| 15 | + |
| 16 | +[source,curl] |
| 17 | +---- |
| 18 | +curl -X POST \ |
| 19 | + http://localhost:5601/api/apm/services/opbeans-java/annotation \ |
| 20 | +-H 'Content-Type: application/json' \ |
| 21 | +-H 'kbn-xsrf: true' \ |
| 22 | +-H 'Authorization: Basic YhUlubWZhM0FDbnlQeE6WRtaW49FQmSGZ4RUWXdX' \ |
| 23 | +-d '{ |
| 24 | + "@timestamp": "2020-05-11T10:31:30.452Z", |
| 25 | + "service": { |
| 26 | + "version": "1.2" |
| 27 | + }, |
| 28 | + "message": "Revert upgrade", |
| 29 | + "tags": [ |
| 30 | + "elastic.co", "customer" |
| 31 | + ] |
| 32 | + }' |
| 33 | +---- |
| 34 | + |
| 35 | +For more information, the Kibana <<api,REST API reference>> provides information on how to use Kibana APIs, |
| 36 | +like required request headers and authentication options. |
| 37 | + |
| 38 | +// AGENT CONFIG API |
| 39 | +// GET --> Feature (APM) Read |
| 40 | +// CREATE/EDIT/DELETE --> Feature (APM) All |
| 41 | + |
| 42 | +// ANNOTATION API |
| 43 | +// Feature (APM) All |
| 44 | +// Index: `observability-annotations`. Privileges: `create_index`, `create_doc`, `manage`, and `read`. |
15 | 45 |
|
16 | 46 | //// |
17 | 47 | ******************************************************* |
18 | 48 | //// |
19 | 49 |
|
| 50 | +[role="xpack"] |
20 | 51 | [[agent-config-api]] |
21 | 52 | === Agent Configuration API |
22 | 53 |
|
@@ -274,6 +305,118 @@ POST /api/apm/settings/agent-configuration/search |
274 | 305 | } |
275 | 306 | -------------------------------------------------- |
276 | 307 |
|
| 308 | +//// |
| 309 | +******************************************************* |
| 310 | +******************************************************* |
| 311 | +//// |
| 312 | + |
| 313 | +[role="xpack"] |
| 314 | +[[apm-annotation-api]] |
| 315 | +=== Annotation API |
| 316 | + |
| 317 | +The Annotation API allows you to annotate visualizations in the APM app with significant events, like deployments, |
| 318 | +allowing you to easily see how these events are impacting the performance of your existing applications. |
| 319 | + |
| 320 | +The following APIs are available: |
| 321 | + |
| 322 | +* <<apm-annotation-create>> to create an annotation for APM. |
| 323 | +// * <<obs-annotation-create>> POST /api/observability/annotation |
| 324 | +// * <<obs-annotation-get>> GET /api/observability/annotation/:id |
| 325 | +// * <<obs-annotation-delete>> DELETE /api/observability/annotation/:id |
| 326 | + |
| 327 | +By default, annotations are stored in a newly created `observability-annotations` index. |
| 328 | +The name of this index can be changed in your `config.yml` by editing `xpack.observability.annotations.index`. |
| 329 | + |
277 | 330 | //// |
278 | 331 | ******************************************************* |
279 | 332 | //// |
| 333 | + |
| 334 | +[[apm-annotation-create]] |
| 335 | +==== Create or update annotation |
| 336 | + |
| 337 | +[[apm-annotation-config-req]] |
| 338 | +===== Request |
| 339 | + |
| 340 | +`POST /api/apm/services/:serviceName/annotation` |
| 341 | + |
| 342 | +[role="child_attributes"] |
| 343 | +[[apm-annotation-config-req-body]] |
| 344 | +===== Request body |
| 345 | + |
| 346 | +`service`:: |
| 347 | +(required, object) Service identifying the configuration to create or update. |
| 348 | ++ |
| 349 | +.Properties of `service` |
| 350 | +[%collapsible%open] |
| 351 | +====== |
| 352 | +`version` ::: |
| 353 | + (required, string) Name of service. |
| 354 | +
|
| 355 | +`environment` ::: |
| 356 | + (optional, string) Environment of service. |
| 357 | +====== |
| 358 | + |
| 359 | +`@timestamp`:: |
| 360 | +(required, string) The date and time of the annotation. Must be in https://www.w3.org/TR/NOTE-datetime[ISO 8601] format. |
| 361 | + |
| 362 | +`message`:: |
| 363 | +(optional, string) The message displayed in the annotation. Defaults to `service.version`. |
| 364 | + |
| 365 | +`tags`:: |
| 366 | +(optional, array) Tags are used by the APM app to distinguish APM annotations from other annotations. |
| 367 | +Tags may have additional functionality in future releases. Defaults to `[apm]`. |
| 368 | +While you can add additional tags, you cannot remove the `apm` tag. |
| 369 | + |
| 370 | +[[apm-annotation-config-example]] |
| 371 | +===== Example |
| 372 | + |
| 373 | +The following example creates an annotation for a service named `opbeans-java`. |
| 374 | + |
| 375 | +[source,console] |
| 376 | +-------------------------------------------------- |
| 377 | +POST /api/apm/services/opbeans-java/annotation |
| 378 | +{ |
| 379 | + "@timestamp": "2020-05-08T10:31:30.452Z", |
| 380 | + "service": { |
| 381 | + "version": "1.2" |
| 382 | + }, |
| 383 | + "message": "Deployment 1.2", |
| 384 | + "tags": [ |
| 385 | + "elastic.co", "customer" |
| 386 | + ] |
| 387 | +} |
| 388 | +-------------------------------------------------- |
| 389 | + |
| 390 | +[[apm-annotation-config-body]] |
| 391 | +===== Response body |
| 392 | + |
| 393 | +[source,js] |
| 394 | +-------------------------------------------------- |
| 395 | +{ |
| 396 | + "_index": "observability-annotations", |
| 397 | + "_id": "Lc9I93EBh6DbmkeV7nFX", |
| 398 | + "_version": 1, |
| 399 | + "_seq_no": 12, |
| 400 | + "_primary_term": 1, |
| 401 | + "found": true, |
| 402 | + "_source": { |
| 403 | + "message": "Deployment 1.2", |
| 404 | + "@timestamp": "2020-05-08T10:31:30.452Z", |
| 405 | + "service": { |
| 406 | + "version": "1.2", |
| 407 | + "name": "opbeans-java" |
| 408 | + }, |
| 409 | + "tags": [ |
| 410 | + "apm", |
| 411 | + "elastic.co", |
| 412 | + "customer" |
| 413 | + ], |
| 414 | + "annotation": { |
| 415 | + "type": "deployment" |
| 416 | + }, |
| 417 | + "event": { |
| 418 | + "created": "2020-05-09T02:34:43.937Z" |
| 419 | + } |
| 420 | + } |
| 421 | +} |
| 422 | +-------------------------------------------------- |
0 commit comments