Skip to content

Commit 13eacb5

Browse files
sorenlouvsorenlouv
authored
[APM] Stabilize agent configuration API (#57767)
1 parent 7e08763 commit 13eacb5

File tree

23 files changed

+894
-370
lines changed

23 files changed

+894
-370
lines changed

‎docs/apm/api.asciidoc‎

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
[role="xpack"]
2+
[[apm-api]]
3+
== API
4+
5+
Some APM app features are provided via a REST API:
6+
7+
* <<agent-config-api>>
8+
9+
TIP: Kibana provides additional <<api,REST APIs>>,
10+
and general information on <<using-api,how to use APIs>>.
11+
12+
////
13+
*******************************************************
14+
////
15+
16+
[[agent-config-api]]
17+
=== Agent Configuration API
18+
19+
The Agent configuration API allows you to fine-tune your APM agent configuration,
20+
without needing to redeploy your application.
21+
22+
The following Agent configuration APIs are available:
23+
24+
* <<apm-update-config>> to create or update an Agent configuration
25+
* <<apm-delete-config>> to delete an Agent configuration.
26+
* <<apm-list-config>> to list all Agent configurations.
27+
* <<apm-search-config>> to search for an Agent configuration.
28+
29+
////
30+
*******************************************************
31+
////
32+
33+
[[apm-update-config]]
34+
==== Create or update configuration
35+
36+
[[apm-update-config-req]]
37+
===== Request
38+
39+
`PUT /api/apm/settings/agent-configuration`
40+
41+
[[apm-update-config-req-body]]
42+
===== Request body
43+
44+
`service`::
45+
(required, object) Service identifying the configuration to create or update.
46+
47+
`name` :::
48+
(required, string) Name of service
49+
50+
`environment` :::
51+
(optional, string) Environment of service
52+
53+
`settings`::
54+
(required) Key/value object with settings and their corresponding value.
55+
56+
`agent_name`::
57+
(optional) The agent name is used by the UI to determine which settings to display.
58+
59+
60+
[[apm-update-config-example]]
61+
===== Example
62+
63+
[source,console]
64+
--------------------------------------------------
65+
PUT /api/apm/settings/agent-configuration
66+
{
67+
"service" : {
68+
"name" : "frontend",
69+
"environment" : "production"
70+
},
71+
"settings" : {
72+
"transaction_sample_rate" : 0.4,
73+
"capture_body" : "off",
74+
"transaction_max_spans" : 500
75+
},
76+
"agent_name": "nodejs"
77+
}
78+
--------------------------------------------------
79+
80+
////
81+
*******************************************************
82+
////
83+
84+
85+
[[apm-delete-config]]
86+
==== Delete configuration
87+
88+
[[apm-delete-config-req]]
89+
===== Request
90+
91+
`DELETE /api/apm/settings/agent-configuration`
92+
93+
[[apm-delete-config-req-body]]
94+
===== Request body
95+
`service`::
96+
(required, object) Service identifying the configuration to delete
97+
98+
`name` :::
99+
(required, string) Name of service
100+
101+
`environment` :::
102+
(optional, string) Environment of service
103+
104+
105+
[[apm-delete-config-example]]
106+
===== Example
107+
108+
[source,console]
109+
--------------------------------------------------
110+
DELETE /api/apm/settings/agent-configuration
111+
{
112+
"service" : {
113+
"name" : "frontend",
114+
"environment": "production"
115+
}
116+
}
117+
--------------------------------------------------
118+
119+
////
120+
*******************************************************
121+
////
122+
123+
124+
[[apm-list-config]]
125+
==== List configuration
126+
127+
128+
[[apm-list-config-req]]
129+
===== Request
130+
131+
`GET /api/apm/settings/agent-configuration`
132+
133+
[[apm-list-config-body]]
134+
===== Response body
135+
136+
[source,js]
137+
--------------------------------------------------
138+
[
139+
{
140+
"agent_name": "go",
141+
"service": {
142+
"name": "opbeans-go",
143+
"environment": "production"
144+
},
145+
"settings": {
146+
"transaction_sample_rate": 1,
147+
"capture_body": "off",
148+
"transaction_max_spans": 200
149+
},
150+
"@timestamp": 1581934104843,
151+
"applied_by_agent": false,
152+
"etag": "1e58c178efeebae15c25c539da740d21dee422fc"
153+
},
154+
{
155+
"agent_name": "go",
156+
"service": {
157+
"name": "opbeans-go"
158+
},
159+
"settings": {
160+
"transaction_sample_rate": 1,
161+
"capture_body": "off",
162+
"transaction_max_spans": 300
163+
},
164+
"@timestamp": 1581934111727,
165+
"applied_by_agent": false,
166+
"etag": "3eed916d3db434d9fb7f039daa681c7a04539a64"
167+
},
168+
{
169+
"agent_name": "nodejs",
170+
"service": {
171+
"name": "frontend"
172+
},
173+
"settings": {
174+
"transaction_sample_rate": 1,
175+
},
176+
"@timestamp": 1582031336265,
177+
"applied_by_agent": false,
178+
"etag": "5080ed25785b7b19f32713681e79f46996801a5b"
179+
}
180+
]
181+
--------------------------------------------------
182+
183+
[[apm-list-config-example]]
184+
===== Example
185+
186+
[source,console]
187+
--------------------------------------------------
188+
GET /api/apm/settings/agent-configuration
189+
--------------------------------------------------
190+
191+
////
192+
*******************************************************
193+
////
194+
195+
196+
[[apm-search-config]]
197+
==== Search configuration
198+
199+
[[apm-search-config-req]]
200+
===== Request
201+
202+
`POST /api/apm/settings/agent-configuration/search`
203+
204+
[[apm-search-config-req-body]]
205+
===== Request body
206+
207+
`service`::
208+
(required, object) Service identifying the configuration.
209+
210+
`name` :::
211+
(required, string) Name of service
212+
213+
`environment` :::
214+
(optional, string) Environment of service
215+
216+
`etag`::
217+
(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`.
218+
219+
[[apm-search-config-body]]
220+
===== Response body
221+
222+
[source,js]
223+
--------------------------------------------------
224+
{
225+
"_index": ".apm-agent-configuration",
226+
"_id": "CIaqXXABmQCdPphWj8EJ",
227+
"_score": 2,
228+
"_source": {
229+
"agent_name": "nodejs",
230+
"service": {
231+
"name": "frontend"
232+
},
233+
"settings": {
234+
"transaction_sample_rate": 1,
235+
},
236+
"@timestamp": 1582031336265,
237+
"applied_by_agent": false,
238+
"etag": "5080ed25785b7b19f32713681e79f46996801a5b"
239+
}
240+
}
241+
--------------------------------------------------
242+
243+
[[apm-search-config-example]]
244+
===== Example
245+
246+
[source,console]
247+
--------------------------------------------------
248+
POST /api/apm/settings/agent-configuration/search
249+
{
250+
"etag" : "1e58c178efeebae15c25c539da740d21dee422fc",
251+
"service" : {
252+
"name" : "frontend",
253+
"environment": "production"
254+
}
255+
}
256+
--------------------------------------------------
257+
258+
////
259+
*******************************************************
260+
////

‎docs/apm/index.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,5 @@ include::getting-started.asciidoc[]
2424
include::bottlenecks.asciidoc[]
2525

2626
include::using-the-apm-ui.asciidoc[]
27+
28+
include::api.asciidoc[]

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

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,12 +51,18 @@ async function deleteConfig(
5151
) {
5252
try {
5353
await callApmApi({
54-
pathname: '/api/apm/settings/agent-configuration/{configurationId}',
54+
pathname: '/api/apm/settings/agent-configuration',
5555
method: 'DELETE',
5656
params: {
57-
path: { configurationId: selectedConfig.id }
57+
body: {
58+
service: {
59+
name: selectedConfig.service.name,
60+
environment: selectedConfig.service.environment
61+
}
62+
}
5863
}
5964
});
65+
6066
toasts.addSuccess({
6167
title: i18n.translate(
6268
'xpack.apm.settings.agentConf.flyout.deleteSection.deleteConfigSucceededTitle',

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,8 +135,8 @@ export function AddEditFlyout({
135135
sampleRate,
136136
captureBody,
137137
transactionMaxSpans,
138-
configurationId: selectedConfig ? selectedConfig.id : undefined,
139138
agentName,
139+
isExistingConfig: Boolean(selectedConfig),
140140
toasts,
141141
trackApmEvent
142142
});

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

Lines changed: 10 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,8 @@ export async function saveConfig({
2727
sampleRate,
2828
captureBody,
2929
transactionMaxSpans,
30-
configurationId,
3130
agentName,
31+
isExistingConfig,
3232
toasts,
3333
trackApmEvent
3434
}: {
@@ -38,8 +38,8 @@ export async function saveConfig({
3838
sampleRate: string;
3939
captureBody: string;
4040
transactionMaxSpans: string;
41-
configurationId?: string;
4241
agentName?: string;
42+
isExistingConfig: boolean;
4343
toasts: NotificationsStart['toasts'];
4444
trackApmEvent: UiTracker;
4545
}) {
@@ -64,24 +64,14 @@ export async function saveConfig({
6464
settings
6565
};
6666

67-
if (configurationId) {
68-
await callApmApi({
69-
pathname: '/api/apm/settings/agent-configuration/{configurationId}',
70-
method: 'PUT',
71-
params: {
72-
path: { configurationId },
73-
body: configuration
74-
}
75-
});
76-
} else {
77-
await callApmApi({
78-
pathname: '/api/apm/settings/agent-configuration/new',
79-
method: 'POST',
80-
params: {
81-
body: configuration
82-
}
83-
});
84-
}
67+
await callApmApi({
68+
pathname: '/api/apm/settings/agent-configuration',
69+
method: 'PUT',
70+
params: {
71+
query: { overwrite: isExistingConfig },
72+
body: configuration
73+
}
74+
});
8575

8676
toasts.addSuccess({
8777
title: i18n.translate(

‎x-pack/legacy/plugins/apm/readme.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,28 @@ node scripts/jest.js plugins/apm --watch
7171
node scripts/jest.js plugins/apm --updateSnapshot
7272
```
7373

74+
### Functional tests
75+
76+
**Start server**
77+
`node scripts/functional_tests_server --config x-pack/test/functional/config.js`
78+
79+
**Run tests**
80+
`node scripts/functional_test_runner --config x-pack/test/functional/config.js --grep='APM specs'`
81+
82+
APM tests are located in `x-pack/test/functional/apps/apm`.
83+
For debugging access Elasticsearch on http://localhost:9220` (elastic/changeme)
84+
85+
### API integration tests
86+
87+
**Start server**
88+
`node scripts/functional_tests_server --config x-pack/test/api_integration/config.js`
89+
90+
**Run tests**
91+
`node scripts/functional_test_runner --config x-pack/test/api_integration/config.js --grep='APM specs'`
92+
93+
APM tests are located in `x-pack/test/api_integration/apis/apm`.
94+
For debugging access Elasticsearch on http://localhost:9220` (elastic/changeme)
95+
7496
### Linting
7597

7698
_Note: Run the following commands from `kibana/`._

0 commit comments

Comments
 (0)