maxmustermann/kibana
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
kibana/docs/apm/api.asciidoc

425 lines
10 KiB
Plaintext
Raw Blame History

[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"
}
}
}
--------------------------------------------------
Reference in a new issue View git blame Copy permalink