Skip to content

Commit f8b589b

Browse files
committed
document JMC agent probes/templates
1 parent a58d641 commit f8b589b

File tree

4 files changed

+38
-0
lines changed

4 files changed

+38
-0
lines changed

schema/openapi.yaml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1619,9 +1619,15 @@ paths:
16191619
$ref: '#/components/schemas/ProbeTemplateResponse'
16201620
type: array
16211621
description: OK
1622+
summary: List defined probe templates
16221623
tags:
16231624
- JMC Agent Templates
16241625
post:
1626+
description: |2
1627+
Create a probe template. This requires a probe template file upload in XML format. See
1628+
https://github.com/openjdk/jmc/blob/master/agent/README.md and
1629+
https://github.com/openjdk/jmc/blob/master/agent/src/main/resources/org/openjdk/jmc/agent/impl/jfrprobes_schema.xsd
1630+
for more information about this file format.
16251631
requestBody:
16261632
content:
16271633
application/x-www-form-urlencoded:
@@ -1639,6 +1645,7 @@ paths:
16391645
schema:
16401646
$ref: '#/components/schemas/ProbeTemplate'
16411647
description: OK
1648+
summary: Create a probe template
16421649
tags:
16431650
- JMC Agent Templates
16441651
/api/v4/probes/{probeTemplateName}:
@@ -1652,6 +1659,7 @@ paths:
16521659
responses:
16531660
"204":
16541661
description: No Content
1662+
summary: Delete the specified probe template
16551663
tags:
16561664
- JMC Agent Templates
16571665
/api/v4/recordings:
@@ -2168,6 +2176,7 @@ paths:
21682176
responses:
21692177
"204":
21702178
description: No Content
2179+
summary: Remove all loaded probes from the specified target
21712180
tags:
21722181
- JMC Agent Probes
21732182
get:
@@ -2187,10 +2196,13 @@ paths:
21872196
$ref: '#/components/schemas/ProbeResponse'
21882197
type: array
21892198
description: OK
2199+
summary: List loaded probes on the specified target
21902200
tags:
21912201
- JMC Agent Probes
21922202
/api/v4/targets/{id}/probes/{probeTemplateName}:
21932203
post:
2204+
description: |
2205+
Activate a probe template (specified by template name) on the specified target (specified by ID).
21942206
parameters:
21952207
- in: path
21962208
name: id
@@ -2206,6 +2218,7 @@ paths:
22062218
responses:
22072219
"201":
22082220
description: Created
2221+
summary: Activate a probe template on the specified target
22092222
tags:
22102223
- JMC Agent Probes
22112224
/api/v4/targets/{targetId}/recordingOptions:

src/main/java/io/cryostat/jmcagent/JMCAgentProbes.java

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@
4040
import jakarta.ws.rs.InternalServerErrorException;
4141
import jakarta.ws.rs.POST;
4242
import jakarta.ws.rs.Path;
43+
import org.eclipse.microprofile.openapi.annotations.Operation;
4344
import org.jboss.logging.Logger;
4445
import org.jboss.resteasy.reactive.RestPath;
4546

@@ -59,6 +60,12 @@ public class JMCAgentProbes {
5960
@Blocking
6061
@POST
6162
@Path("/api/v4/targets/{id}/probes/{probeTemplateName}")
63+
@Operation(
64+
summary = "Activate a probe template on the specified target",
65+
description =
66+
"""
67+
Activate a probe template (specified by template name) on the specified target (specified by ID).
68+
""")
6269
public void postProbe(@RestPath long id, @RestPath String probeTemplateName) {
6370
try {
6471
Target target = Target.getTargetById(id);
@@ -102,6 +109,7 @@ public void postProbe(@RestPath long id, @RestPath String probeTemplateName) {
102109
@Blocking
103110
@DELETE
104111
@Path("/api/v4/targets/{id}/probes")
112+
@Operation(summary = "Remove all loaded probes from the specified target")
105113
public void deleteProbe(@RestPath long id) {
106114
try {
107115
Target target = Target.getTargetById(id);
@@ -133,6 +141,7 @@ public void deleteProbe(@RestPath long id) {
133141
@Blocking
134142
@GET
135143
@Path("/api/v4/targets/{id}/probes")
144+
@Operation(summary = "List loaded probes on the specified target")
136145
public List<ProbeResponse> getProbes(@RestPath long id) {
137146
try {
138147
Target target = Target.getTargetById(id);

src/main/java/io/cryostat/jmcagent/JMCAgentTemplates.java

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
import jakarta.ws.rs.core.Context;
3232
import jakarta.ws.rs.core.UriInfo;
3333
import org.apache.commons.lang3.StringUtils;
34+
import org.eclipse.microprofile.openapi.annotations.Operation;
3435
import org.jboss.logging.Logger;
3536
import org.jboss.resteasy.reactive.RestForm;
3637
import org.jboss.resteasy.reactive.RestPath;
@@ -48,6 +49,7 @@ public class JMCAgentTemplates {
4849

4950
@Blocking
5051
@GET
52+
@Operation(summary = "List defined probe templates")
5153
public List<ProbeTemplateResponse> getProbeTemplates() {
5254
return service.getTemplates().stream()
5355
.map(SerializableProbeTemplateInfo::fromProbeTemplate)
@@ -58,12 +60,22 @@ public List<ProbeTemplateResponse> getProbeTemplates() {
5860
@Blocking
5961
@DELETE
6062
@Path("/{probeTemplateName}")
63+
@Operation(summary = "Delete the specified probe template")
6164
public void deleteProbeTemplate(@RestPath String probeTemplateName) {
6265
service.deleteTemplate(probeTemplateName);
6366
}
6467

6568
@Blocking
6669
@POST
70+
@Operation(
71+
summary = "Create a probe template",
72+
description =
73+
"""
74+
Create a probe template. This requires a probe template file upload in XML format. See
75+
https://github.com/openjdk/jmc/blob/master/agent/README.md and
76+
https://github.com/openjdk/jmc/blob/master/agent/src/main/resources/org/openjdk/jmc/agent/impl/jfrprobes_schema.xsd
77+
for more information about this file format.
78+
""")
6779
public RestResponse<ProbeTemplate> uploadProbeTemplate(
6880
@Context UriInfo uriInfo,
6981
@RestForm("probeTemplate") FileUpload body,

src/main/java/io/cryostat/jmcagent/S3ProbeTemplateService.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,10 @@
5555
import software.amazon.awssdk.services.s3.model.Tag;
5656
import software.amazon.awssdk.services.s3.model.Tagging;
5757

58+
/**
59+
* Implementation for JMC Agent event probe templates stored in S3 object storage.
60+
* @see io.cryostat.events.S3TemplateService
61+
*/
5862
public class S3ProbeTemplateService implements ProbeTemplateService {
5963

6064
@ConfigProperty(name = ConfigProperties.AWS_BUCKET_NAME_PROBE_TEMPLATES)

0 commit comments

Comments
 (0)