Agent Configuration API
editAgent Configuration API
editThe 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:
- Create or update configuration to create or update an Agent configuration
- Delete configuration to delete an Agent configuration.
- List configuration to list all Agent configurations.
- Search configuration to search for an Agent configuration.
How to use APM APIs
editExpand 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 ofApiKey
followed by the{credentials}
, where{credentials}
is the base64 encoding ofid
andapi_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:-
The API endpoint uses the
GET
orHEAD
operations -
The path is whitelisted using the
server.xsrf.whitelist
setting -
XSRF protections are disabled using the
server.xsrf.disableProtection
setting
-
The API endpoint uses the
-
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 theContent-Type
header.
Create or update configuration
editRequest
editPUT /api/apm/settings/agent-configuration
Request body
edit-
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
editPUT /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" }
Delete configuration
editRequest
editDELETE /api/apm/settings/agent-configuration
Request body
edit-
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
editDELETE /api/apm/settings/agent-configuration { "service" : { "name": "frontend", "environment": "production" } }
List configuration
editRequest
editGET /api/apm/settings/agent-configuration
Response body
edit[ { "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" } ]
Example
editGET /api/apm/settings/agent-configuration
Search configuration
editRequest
editPOST /api/apm/settings/agent-configuration/search
Request body
edit-
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 totrue
. Every time a configuration is editedapplied_by_agent
is reset tofalse
.
Response body
edit{ "_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" } }
Example
editPOST /api/apm/settings/agent-configuration/search { "etag": "1e58c178efeebae15c25c539da740d21dee422fc", "service" : { "name": "frontend", "environment": "production" } }