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:

How to use APM APIs

Expand for required headers, privileges, and usage details

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 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 sufficient privileges.

kbn-xsrf: true

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

Content-Type: application/json

Applicable only when you send a payload in the API request. Kibana API requests and responses use JSON. Typically, if you include the kbn-xsrf header, you must also include the Content-Type header.

Create or update configuration

Request

PUT /api/apm/settings/agent-configuration

Request body

service

(required, object) Service identifying the configuration to create or update.

Properties of service

  • 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.

Example

  1. PUT /api/apm/settings/agent-configuration
  2. {
  3.     "service": {
  4.         "name": "frontend",
  5.         "environment": "production"
  6.     },
  7.     "settings": {
  8.         "transaction_sample_rate": "0.4",
  9.         "capture_body": "off",
  10.         "transaction_max_spans": "500"
  11.     },
  12.     "agent_name": "nodejs"
  13. }

Delete configuration

Request

DELETE /api/apm/settings/agent-configuration

Request body

service

(required, object) Service identifying the configuration to delete

Properties of service

  • name

    (required, string) Name of service

    environment

    (optional, string) Environment of service

Example

  1. DELETE /api/apm/settings/agent-configuration
  2. {
  3.     "service" : {
  4.         "name": "frontend",
  5.         "environment": "production"
  6.     }
  7. }

List configuration

Request

GET /api/apm/settings/agent-configuration

Response body

  1. [
  2.   {
  3.     "agent_name": "go",
  4.     "service": {
  5.       "name": "opbeans-go",
  6.       "environment": "production"
  7.     },
  8.     "settings": {
  9.       "transaction_sample_rate": "1",
  10.       "capture_body": "off",
  11.       "transaction_max_spans": "200"
  12.     },
  13.     "@timestamp": 1581934104843,
  14.     "applied_by_agent": false,
  15.     "etag": "1e58c178efeebae15c25c539da740d21dee422fc"
  16.   },
  17.   {
  18.     "agent_name": "go",
  19.     "service": {
  20.       "name": "opbeans-go"
  21.     },
  22.     "settings": {
  23.       "transaction_sample_rate": "1",
  24.       "capture_body": "off",
  25.       "transaction_max_spans": "300"
  26.     },
  27.     "@timestamp": 1581934111727,
  28.     "applied_by_agent": false,
  29.     "etag": "3eed916d3db434d9fb7f039daa681c7a04539a64"
  30.   },
  31.   {
  32.     "agent_name": "nodejs",
  33.     "service": {
  34.       "name": "frontend"
  35.     },
  36.     "settings": {
  37.       "transaction_sample_rate": "1",
  38.     },
  39.     "@timestamp": 1582031336265,
  40.     "applied_by_agent": false,
  41.     "etag": "5080ed25785b7b19f32713681e79f46996801a5b"
  42.   }
  43. ]

Example

  1. GET  /api/apm/settings/agent-configuration

Search configuration

Request

POST /api/apm/settings/agent-configuration/search

Request body

service

(required, object) Service identifying the configuration.

Properties of service

  • 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.

Response body

  1. {
  2.   "_index": ".apm-agent-configuration",
  3.   "_id": "CIaqXXABmQCdPphWj8EJ",
  4.   "_score": 2,
  5.   "_source": {
  6.     "agent_name": "nodejs",
  7.     "service": {
  8.       "name": "frontend"
  9.     },
  10.     "settings": {
  11.       "transaction_sample_rate": "1",
  12.     },
  13.     "@timestamp": 1582031336265,
  14.     "applied_by_agent": false,
  15.     "etag": "5080ed25785b7b19f32713681e79f46996801a5b"
  16.   }
  17. }

Example

  1. POST /api/apm/settings/agent-configuration/search
  2. {
  3.     "etag": "1e58c178efeebae15c25c539da740d21dee422fc",
  4.     "service" : {
  5.         "name": "frontend",
  6.         "environment": "production"
  7.     }
  8. }

Most Popular