425 lines
10 KiB
Plaintext
425 lines
10 KiB
Plaintext
[role="xpack"]
|
|
[[apm-api]]
|
|
== APM app API
|
|
|
|
++++
|
|
<titleabbrev>REST API</titleabbrev>
|
|
++++
|
|
|
|
Some APM app features are provided via a REST API:
|
|
|
|
* <<agent-config-api>>
|
|
* <<apm-annotation-api>>
|
|
|
|
[float]
|
|
[[apm-api-example]]
|
|
=== Using the APIs
|
|
|
|
Users interacting with APM APIs must have <<apm-app-api-user,sufficient privileges>>.
|
|
In addition, there are request headers to be aware of, like `kbn-xsrf: true`, and `Content-Type: applicaton/json`.
|
|
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"
|
|
]
|
|
}'
|
|
----
|
|
|
|
The Kibana <<api,REST API reference>> provides additional information on how to use Kibana APIs,
|
|
required request headers, and token-based authentication options.
|
|
|
|
////
|
|
*******************************************************
|
|
////
|
|
|
|
[role="xpack"]
|
|
[[agent-config-api]]
|
|
=== Agent Configuration API
|
|
|
|
The Agent configuration API allows you to fine-tune your APM agent configuration,
|
|
without needing to redeploy your application.
|
|
|
|
The following Agent configuration APIs are available:
|
|
|
|
* <<apm-update-config>> to create or update an Agent configuration
|
|
* <<apm-delete-config>> to delete an Agent configuration.
|
|
* <<apm-list-config>> to list all Agent configurations.
|
|
* <<apm-search-config>> to search for an Agent configuration.
|
|
|
|
See <<apm-app-api-config-manager>> for information on the privileges required to use this API endpoint.
|
|
|
|
////
|
|
*******************************************************
|
|
////
|
|
|
|
[[apm-update-config]]
|
|
==== Create or update configuration
|
|
|
|
[[apm-update-config-req]]
|
|
===== Request
|
|
|
|
`PUT /api/apm/settings/agent-configuration`
|
|
|
|
[role="child_attributes"]
|
|
[[apm-update-config-req-body]]
|
|
===== Request body
|
|
|
|
`service`::
|
|
(required, object) Service identifying the configuration to create or update.
|
|
+
|
|
.Properties of `service`
|
|
[%collapsible%open]
|
|
======
|
|
`name` :::
|
|
(required, string) Name of service
|
|
|
|
`environment` :::
|
|
(optional, string) Environment of service
|
|
======
|
|
|
|
`settings`::
|
|
(required) Key/value object with option name and option value.
|
|
|
|
`agent_name`::
|
|
(optional) The agent name is used by the UI to determine which settings to display.
|
|
|
|
|
|
[[apm-update-config-example]]
|
|
===== Example
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /api/apm/settings/agent-configuration
|
|
{
|
|
"service": {
|
|
"name": "frontend",
|
|
"environment": "production"
|
|
},
|
|
"settings": {
|
|
"transaction_sample_rate": "0.4",
|
|
"capture_body": "off",
|
|
"transaction_max_spans": "500"
|
|
},
|
|
"agent_name": "nodejs"
|
|
}
|
|
--------------------------------------------------
|
|
|
|
////
|
|
*******************************************************
|
|
////
|
|
|
|
|
|
[[apm-delete-config]]
|
|
==== Delete configuration
|
|
|
|
[[apm-delete-config-req]]
|
|
===== Request
|
|
|
|
`DELETE /api/apm/settings/agent-configuration`
|
|
|
|
[role="child_attributes"]
|
|
[[apm-delete-config-req-body]]
|
|
===== Request body
|
|
`service`::
|
|
(required, object) Service identifying the configuration to delete
|
|
+
|
|
.Properties of `service`
|
|
[%collapsible%open]
|
|
======
|
|
`name` :::
|
|
(required, string) Name of service
|
|
|
|
`environment` :::
|
|
(optional, string) Environment of service
|
|
======
|
|
|
|
|
|
[[apm-delete-config-example]]
|
|
===== Example
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
DELETE /api/apm/settings/agent-configuration
|
|
{
|
|
"service" : {
|
|
"name": "frontend",
|
|
"environment": "production"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
////
|
|
*******************************************************
|
|
////
|
|
|
|
|
|
[[apm-list-config]]
|
|
==== List configuration
|
|
|
|
|
|
[[apm-list-config-req]]
|
|
===== Request
|
|
|
|
`GET /api/apm/settings/agent-configuration`
|
|
|
|
[[apm-list-config-body]]
|
|
===== Response body
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
[
|
|
{
|
|
"agent_name": "go",
|
|
"service": {
|
|
"name": "opbeans-go",
|
|
"environment": "production"
|
|
},
|
|
"settings": {
|
|
"transaction_sample_rate": "1",
|
|
"capture_body": "off",
|
|
"transaction_max_spans": "200"
|
|
},
|
|
"@timestamp": 1581934104843,
|
|
"applied_by_agent": false,
|
|
"etag": "1e58c178efeebae15c25c539da740d21dee422fc"
|
|
},
|
|
{
|
|
"agent_name": "go",
|
|
"service": {
|
|
"name": "opbeans-go"
|
|
},
|
|
"settings": {
|
|
"transaction_sample_rate": "1",
|
|
"capture_body": "off",
|
|
"transaction_max_spans": "300"
|
|
},
|
|
"@timestamp": 1581934111727,
|
|
"applied_by_agent": false,
|
|
"etag": "3eed916d3db434d9fb7f039daa681c7a04539a64"
|
|
},
|
|
{
|
|
"agent_name": "nodejs",
|
|
"service": {
|
|
"name": "frontend"
|
|
},
|
|
"settings": {
|
|
"transaction_sample_rate": "1",
|
|
},
|
|
"@timestamp": 1582031336265,
|
|
"applied_by_agent": false,
|
|
"etag": "5080ed25785b7b19f32713681e79f46996801a5b"
|
|
}
|
|
]
|
|
--------------------------------------------------
|
|
|
|
[[apm-list-config-example]]
|
|
===== Example
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /api/apm/settings/agent-configuration
|
|
--------------------------------------------------
|
|
|
|
////
|
|
*******************************************************
|
|
////
|
|
|
|
|
|
[[apm-search-config]]
|
|
==== Search configuration
|
|
|
|
[[apm-search-config-req]]
|
|
===== Request
|
|
|
|
`POST /api/apm/settings/agent-configuration/search`
|
|
|
|
[role="child_attributes"]
|
|
[[apm-search-config-req-body]]
|
|
===== Request body
|
|
|
|
`service`::
|
|
(required, object) Service identifying the configuration.
|
|
+
|
|
.Properties of `service`
|
|
[%collapsible%open]
|
|
======
|
|
`name` :::
|
|
(required, string) Name of service
|
|
|
|
`environment` :::
|
|
(optional, string) Environment of service
|
|
======
|
|
|
|
`etag`::
|
|
(required) etag is sent by the agent to indicate the etag of the last successfully applied configuration. If the etag matches an existing configuration its `applied_by_agent` property will be set to `true`. Every time a configuration is edited `applied_by_agent` is reset to `false`.
|
|
|
|
[[apm-search-config-body]]
|
|
===== Response body
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"_index": ".apm-agent-configuration",
|
|
"_id": "CIaqXXABmQCdPphWj8EJ",
|
|
"_score": 2,
|
|
"_source": {
|
|
"agent_name": "nodejs",
|
|
"service": {
|
|
"name": "frontend"
|
|
},
|
|
"settings": {
|
|
"transaction_sample_rate": "1",
|
|
},
|
|
"@timestamp": 1582031336265,
|
|
"applied_by_agent": false,
|
|
"etag": "5080ed25785b7b19f32713681e79f46996801a5b"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[apm-search-config-example]]
|
|
===== Example
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /api/apm/settings/agent-configuration/search
|
|
{
|
|
"etag": "1e58c178efeebae15c25c539da740d21dee422fc",
|
|
"service" : {
|
|
"name": "frontend",
|
|
"environment": "production"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
////
|
|
*******************************************************
|
|
*******************************************************
|
|
////
|
|
|
|
[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`.
|
|
|
|
See <<apm-app-api-annotation-manager>> for information on the privileges required to use this API endpoint.
|
|
|
|
////
|
|
*******************************************************
|
|
////
|
|
|
|
[[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"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|