[APM] Stabilize agent configuration API (#57767) (#58416)

docs/apm/api.asciidoc

@@ -0,0 +1,260 @@
+[role="xpack"]
+[[apm-api]]
+== API
+
+Some APM app features are provided via a REST API:
+
+* <<agent-config-api>>
+
+TIP: Kibana provides additional <<api,REST APIs>>,
+and general information on <<using-api,how to use APIs>>.
+
+////
+*******************************************************
+////
+
+[[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.
+
+////
+*******************************************************
+////
+
+[[apm-update-config]]
+==== Create or update configuration
+
+[[apm-update-config-req]]
+===== Request
+
+`PUT /api/apm/settings/agent-configuration`
+
+[[apm-update-config-req-body]]
+===== Request body
+
+`service`::
+(required, object) Service identifying the configuration to create or update.
+
+`name` :::
+  (required, string) Name of service
+
+`environment` :::
+  (optional, string) Environment of service
+
+`settings`::
+(required) Key/value object with settings and their corresponding 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`
+
+[[apm-delete-config-req-body]]
+===== Request body
+`service`::
+(required, object) Service identifying the configuration to delete
+
+`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`
+
+[[apm-search-config-req-body]]
+===== Request body
+
+`service`::
+(required, object) Service identifying the configuration.
+
+`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"
+    }
+}
+--------------------------------------------------
+
+////
+*******************************************************
+////

docs/apm/index.asciidoc

@@ -30,3 +30,5 @@ include::getting-started.asciidoc[]
 include::bottlenecks.asciidoc[]
 
 include::using-the-apm-ui.asciidoc[]
+
+include::api.asciidoc[]

x-pack/legacy/plugins/apm/public/components/app/Settings/AgentConfigurations/AddEditFlyout/DeleteButton.tsx

@@ -51,12 +51,18 @@ async function deleteConfig(
 ) {
   try {
     await callApmApi({
-      pathname: '/api/apm/settings/agent-configuration/{configurationId}',
+      pathname: '/api/apm/settings/agent-configuration',
       method: 'DELETE',
       params: {
-        path: { configurationId: selectedConfig.id }
+        body: {
+          service: {
+            name: selectedConfig.service.name,
+            environment: selectedConfig.service.environment
+          }
+        }
       }
     });
+
     toasts.addSuccess({
       title: i18n.translate(
         'xpack.apm.settings.agentConf.flyout.deleteSection.deleteConfigSucceededTitle',

x-pack/legacy/plugins/apm/public/components/app/Settings/AgentConfigurations/AddEditFlyout/index.tsx

@@ -135,8 +135,8 @@ export function AddEditFlyout({
       sampleRate,
       captureBody,
       transactionMaxSpans,
-      configurationId: selectedConfig ? selectedConfig.id : undefined,
       agentName,
+      isExistingConfig: Boolean(selectedConfig),
       toasts,
       trackApmEvent
     });

x-pack/legacy/plugins/apm/public/components/app/Settings/AgentConfigurations/AddEditFlyout/saveConfig.ts

@@ -27,8 +27,8 @@ export async function saveConfig({
   sampleRate,
   captureBody,
   transactionMaxSpans,
-  configurationId,
   agentName,
+  isExistingConfig,
   toasts,
   trackApmEvent
 }: {
@@ -38,8 +38,8 @@ export async function saveConfig({
   sampleRate: string;
   captureBody: string;
   transactionMaxSpans: string;
-  configurationId?: string;
   agentName?: string;
+  isExistingConfig: boolean;
   toasts: NotificationsStart['toasts'];
   trackApmEvent: UiTracker;
 }) {
@@ -64,24 +64,14 @@ export async function saveConfig({
       settings
     };
 
-    if (configurationId) {
-      await callApmApi({
-        pathname: '/api/apm/settings/agent-configuration/{configurationId}',
-        method: 'PUT',
-        params: {
-          path: { configurationId },
-          body: configuration
-        }
-      });
-    } else {
-      await callApmApi({
-        pathname: '/api/apm/settings/agent-configuration/new',
-        method: 'POST',
-        params: {
-          body: configuration
-        }
-      });
-    }
+    await callApmApi({
+      pathname: '/api/apm/settings/agent-configuration',
+      method: 'PUT',
+      params: {
+        query: { overwrite: isExistingConfig },
+        body: configuration
+      }
+    });
 
     toasts.addSuccess({
       title: i18n.translate(