kibana/docs/apm/api.asciidoc

[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>>
* <<rum-sourcemap-api>>
* <<agent-key-api>>

[float]
[[apm-api-example]]
=== Using the APIs

// The following content is reused throughout the API docs
// tag::using-the-APIs[]
Interact with APM APIs using cURL or another API tool.
All APM APIs are Kibana APIs, not Elasticsearch APIs;
because of this, the Kibana dev tools console cannot be used to interact with APM APIs.

For all APM APIs, you must use a request header.
Supported headers are `Authorization`, `kbn-xsrf`, and `Content-Type`.

`Authorization: ApiKey {credentials}`::
Kibana supports token-based authentication with the Elasticsearch API key service.
The API key returned by the  {ref}/security-api-create-api-key.html[Elasticsearch create API key API]
can be used by sending a request with an `Authorization` header that has a value of `ApiKey` followed by the `{credentials}`,
where `{credentials}` is the base64 encoding of `id` and `api_key` joined by a colon.
+
Alternatively, you can create a user and use their username and password to authenticate API access: `-u $USER:$PASSWORD`.
+
Whether using `Authorization: ApiKey {credentials}`, or `-u $USER:$PASSWORD`,
users interacting with APM APIs must have <<apm-app-api-user,sufficient privileges>>.

`kbn-xsrf: true`::
  By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios:

* The API endpoint uses the `GET` or `HEAD` operations
* The path is allowed using the <<settings-xsrf-allowlist, `server.xsrf.allowlist`>> setting
* XSRF protections are disabled using the <<settings-xsrf-disableProtection, `server.xsrf.disableProtection`>> setting

`Content-Type: application/json`::
  Applicable only when you send a payload in the API request.
  {kib} API requests and responses use JSON.
  Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header.
// end::using-the-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"
      ]
    }'
----

[float]
[[kibana-api]]
=== Kibana API

In addition to the APM specific API endpoints, Kibana provides its own <<api,REST API>>
which you can use to automate certain aspects of configuring and deploying Kibana.

////
*******************************************************
*******************************************************
////

[role="xpack"]
[[agent-config-api]]
=== Agent Configuration API

The APM agent configuration API allows you to fine-tune your APM agent configuration,
without needing to redeploy your application.

The following APM agent configuration APIs are available:

* <<apm-update-config>> to create or update an APM agent configuration
* <<apm-delete-config>> to delete an APM agent configuration.
* <<apm-list-config>> to list all APM agent configurations.
* <<apm-search-config>> to search for an APM agent configuration.

[float]
[[use-agent-config-api]]
==== How to use APM APIs

.Expand for required headers, privileges, and usage details
[%collapsible%closed]
======
include::api.asciidoc[tag=using-the-APIs]
======

////
*******************************************************
////

[[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,curl]
--------------------------------------------------
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,curl]
--------------------------------------------------
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,curl]
--------------------------------------------------
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 APM 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,curl]
--------------------------------------------------
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.

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`.
If you change the default index name, you'll also need to <<apm-app-annotation-user-create,update your user privileges>> accordingly.

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

[float]
[[use-annotation-api]]
==== How to use APM APIs

.Expand for required headers, privileges, and usage details
[%collapsible%closed]
======
include::api.asciidoc[tag=using-the-APIs]
======

////
*******************************************************
////

[[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) Version 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,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-08T10:31:30.452Z",
      "service": {
        "version": "1.2"
      },
      "message": "Deployment 1.2"
    }'
--------------------------------------------------

[[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"
    }
  }
}
--------------------------------------------------

////
*******************************************************
*******************************************************
////

[role="xpack"]
[[rum-sourcemap-api]]
=== RUM source map API

IMPORTANT: This endpoint is only compatible with the
{apm-guide-ref}/index.html[APM integration for Elastic Agent].

A source map allows minified files to be mapped back to original source code --
allowing you to maintain the speed advantage of minified code,
without losing the ability to quickly and easily debug your application.

For best results, uploading source maps should become a part of your deployment procedure,
and not something you only do when you see unhelpful errors.
That’s because uploading source maps after errors happen won’t make old errors magically readable --
errors must occur again for source mapping to occur.

The following APIs are available:

* <<rum-sourcemap-post>>
* <<rum-sourcemap-get>>
* <<rum-sourcemap-delete>>

[float]
[[limit-sourcemap-api]]
==== Max payload size

{kib}'s maximum payload size is 1mb.
If you attempt to upload a source map that exceeds the max payload size, you will get a `413` error.

Before uploading source maps that exceed this default, change the maximum payload size allowed by {kib}
with the <<server-maxPayload,`server.maxPayload`>> variable.

[float]
[[use-sourcemap-api]]
==== How to use APM APIs

.Expand for required headers, privileges, and usage details
[%collapsible%closed]
======
include::api.asciidoc[tag=using-the-APIs]
======

////
*******************************************************
////

[[rum-sourcemap-post]]
==== Create or update source map

Create or update a source map for a specific service and version.

[[rum-sourcemap-post-privs]]
===== Privileges

The user accessing this endpoint requires `All` Kibana privileges for the {beat_kib_app} feature.
For more information, see <<kibana-privileges>>.

[[apm-sourcemap-post-req]]
===== Request

`POST /api/apm/sourcemaps`

[role="child_attributes"]
[[apm-sourcemap-post-req-body]]
===== Request body

`service_name`::
(required, string) The name of the service that the service map should apply to.

`service_version`::
(required, string) The version of the service that the service map should apply to.

`bundle_filepath`::
(required, string) The absolute path of the final bundle as used in the web application.

`sourcemap`::
(required, string or file upload) The source map. It must follow the
https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k[source map revision 3 proposal].

[[apm-sourcemap-post-example]]
===== Examples

The following example uploads a source map for a service named `foo` and a service version of `1.0.0`:

[source,curl]
--------------------------------------------------
curl -X POST "http://localhost:5601/api/apm/sourcemaps" \
-H 'Content-Type: multipart/form-data' \
-H 'kbn-xsrf: true' \
-H 'Authorization: ApiKey ${YOUR_API_KEY}' \
-F 'service_name="foo"' \
-F 'service_version="1.0.0"' \
-F 'bundle_filepath="/test/e2e/general-usecase/bundle.js.map"' \
-F 'sourcemap="{\"version\":3,\"file\":\"static/js/main.chunk.js\",\"sources\":[\"fleet-source-map-client/src/index.css\",\"fleet-source-map-client/src/App.js\",\"webpack:///./src/index.css?bb0a\",\"fleet-source-map-client/src/index.js\",\"fleet-source-map-client/src/reportWebVitals.js\"],\"sourcesContent\":[\"content\"],\"mappings\":\"mapping\",\"sourceRoot\":\"\"}"' <1>
--------------------------------------------------
<1> Alternatively, upload the source map as a file with `-F 'sourcemap=@path/to/source_map/bundle.js.map'`

[[apm-sourcemap-post-body]]
===== Response body

[source,js]
--------------------------------------------------
{
  "type": "sourcemap",
  "identifier": "foo-1.0.0",
  "relative_url": "/api/fleet/artifacts/foo-1.0.0/644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
  "body": "eJyFkL1OwzAUhd/Fc+MbYMuCEBIbHRjKgBgc96R16tiWr1OQqr47NwqJxEK3q/PzWccXxchnZ7E1A1SjuhjVZtF2yOxiEPlO17oWox3D3uPFeSRTjmJQARfCPeiAgGx8NTKsYdAc1T3rwaSJGcds8Sp3c1HnhfywUZ3QhMTFFGepZxqMC9oex3CS9tpk1XyozgOlmoVKuJX1DqEQZ0su7PGtLU+V/3JPKc3cL7TJ2FNDRPov4bFta3MDM4f7W69lpJjLO9qdK8bzVPhcJz3HUCQ4LbO/p5hCSC4cZPByrp/wFqOklbpefwAhzpqI",
  "created": "2021-07-09T20:47:44.812Z",
  "id": "apm:foo-1.0.0-644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
  "compressionAlgorithm": "zlib",
  "decodedSha256": "644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
  "decodedSize": 441,
  "encodedSha256": "024c72749c3e3dd411b103f7040ae62633558608f480bce4b108cf5b2275bd24",
  "encodedSize": 237,
  "encryptionAlgorithm": "none",
  "packageName": "apm"
}
--------------------------------------------------

////
*******************************************************
////

[[rum-sourcemap-get]]
==== Get source maps

Returns an array of Fleet artifacts, including source map uploads.

[[rum-sourcemap-get-privs]]
===== Privileges

The user accessing this endpoint requires `Read` or `All` Kibana privileges for the {beat_kib_app} feature.
For more information, see <<kibana-privileges>>.

[[apm-sourcemap-get-req]]
===== Request

`GET /api/apm/sourcemaps`

[[apm-sourcemap-get-example]]
===== Example

The following example requests all uploaded source maps:

[source,curl]
--------------------------------------------------
curl -X GET "http://localhost:5601/api/apm/sourcemaps" \
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'Authorization: ApiKey ${YOUR_API_KEY}'
--------------------------------------------------

[[apm-sourcemap-get-body]]
===== Response body

[source,js]
--------------------------------------------------
{
  "artifacts": [
    {
      "type": "sourcemap",
      "identifier": "foo-1.0.0",
      "relative_url": "/api/fleet/artifacts/foo-1.0.0/644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
      "body": {
        "serviceName": "foo",
        "serviceVersion": "1.0.0",
        "bundleFilepath": "/test/e2e/general-usecase/bundle.js.map",
        "sourceMap": {
          "version": 3,
          "file": "static/js/main.chunk.js",
          "sources": [
            "fleet-source-map-client/src/index.css",
            "fleet-source-map-client/src/App.js",
            "webpack:///./src/index.css?bb0a",
            "fleet-source-map-client/src/index.js",
            "fleet-source-map-client/src/reportWebVitals.js"
          ],
          "sourcesContent": [
            "content"
          ],
          "mappings": "mapping",
          "sourceRoot": ""
        }
      },
      "created": "2021-07-09T20:47:44.812Z",
      "id": "apm:foo-1.0.0-644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
      "compressionAlgorithm": "zlib",
      "decodedSha256": "644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
      "decodedSize": 441,
      "encodedSha256": "024c72749c3e3dd411b103f7040ae62633558608f480bce4b108cf5b2275bd24",
      "encodedSize": 237,
      "encryptionAlgorithm": "none",
      "packageName": "apm"
    }
  ]
}
--------------------------------------------------

////
*******************************************************
////

[[rum-sourcemap-delete]]
==== Delete source map

Delete a previously uploaded source map.

[[rum-sourcemap-delete-privs]]
===== Privileges

The user accessing this endpoint requires `All` Kibana privileges for the {beat_kib_app} feature.
For more information, see <<kibana-privileges>>.

[[apm-sourcemap-delete-req]]
===== Request

`DELETE /api/apm/sourcemaps/:id`

[[apm-sourcemap-delete-example]]
===== Example

The following example deletes a source map with an id of `apm:foo-1.0.0-644fd5a9`:

[source,curl]
--------------------------------------------------
curl -X DELETE "http://localhost:5601/api/apm/sourcemaps/apm:foo-1.0.0-644fd5a9" \
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'Authorization: ApiKey ${YOUR_API_KEY}'
--------------------------------------------------

[[apm-sourcemap-delete-body]]
===== Response body

[source,js]
--------------------------------------------------
{}
--------------------------------------------------

////
*******************************************************
*******************************************************
////

[role="xpack"]
[[agent-key-api]]
=== APM agent Key API

The APM agent Key API allows you to configure APM agent keys to authorize requests from APM agents to the APM Server.

The following APM agent key APIs are available:

* <<apm-create-agent-key>> to create an APM agent key

[float]
[[use-agent-key-api]]
==== How to use APM APIs

.Expand for required headers, privileges, and usage details
[%collapsible%closed]
======
include::api.asciidoc[tag=using-the-APIs]
======

////
*******************************************************
////

[[apm-create-agent-key]]
==== Create agent key

Create an APM agent API key. Specify API key privileges in the request body at creation time.

[[apm-create-agent-key-privileges]]
===== Privileges

The user creating an APM agent API key must have at least the `manage_own_api_key` cluster privilege
and the APM application-level privileges that it wishes to grant.

====== Example role

The example below uses the Kibana <<role-management-api,role management API>> to create a role named `apm_agent_key_user`.
Create and assign this role to a user that wishes to create APM agent API keys.

[source,js]
--------------------------------------------------
POST /_security/role/apm_agent_key_user
{
  "cluster": ["manage_own_api_key"],
  "applications": [{
    "application": "apm",
    "privileges": ["event:write", "config_agent:read"],
    "resources": ["*"]
  }]
}
--------------------------------------------------

[[apm-create-agent-key-req]]
===== Request

`POST /api/apm/agent_keys`

[role="child_attributes"]
[[apm-create-agent-key-req-body]]
===== Request body

`name`::
(required, string) Name of the APM agent key.

`privileges`::
(required, array) APM agent key privileges. It can take one or more of the following values:

  - `event:write`. Required for ingesting APM agent events.
  - `config_agent:read`. Required for APM agents to read agent configuration remotely.

[[apm-agent-key-create-example]]
===== Example

[source,curl]
--------------------------------------------------
POST /api/apm/agent_keys
{
    "name": "apm-key",
    "privileges": ["event:write", "config_agent:read"]
}
--------------------------------------------------

[[apm-agent-key-create-body]]
===== Response body

[source,js]
--------------------------------------------------
{
  "agentKey": {
    "id": "3DCLmn0B3ZMhLUa7WBG9",
    "name": "apm-key",
    "api_key": "PjGloCGOTzaZr8ilUPvkjA",
    "encoded": "M0RDTG1uMEIzWk1oTFVhN1dCRzk6UGpHbG9DR09UemFacjhpbFVQdmtqQQ=="
  }
}
--------------------------------------------------

Once created, you can copy the API key (Base64 encoded) and use it to to authorize requests from APM agents to the APM Server.