document JMC agent probes/templates

Author: andrewazores

schema/openapi.yaml

@@ -1619,9 +1619,15 @@ paths:
                   $ref: '#/components/schemas/ProbeTemplateResponse'
                 type: array
           description: OK
+      summary: List defined probe templates
       tags:
         - JMC Agent Templates
     post:
+      description: |2
+            Create a probe template. This requires a probe template file upload in XML format. See
+            https://github.com/openjdk/jmc/blob/master/agent/README.md and
+            https://github.com/openjdk/jmc/blob/master/agent/src/main/resources/org/openjdk/jmc/agent/impl/jfrprobes_schema.xsd
+            for more information about this file format.
       requestBody:
         content:
           application/x-www-form-urlencoded:
@@ -1639,6 +1645,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/ProbeTemplate'
           description: OK
+      summary: Create a probe template
       tags:
         - JMC Agent Templates
   /api/v4/probes/{probeTemplateName}:
@@ -1652,6 +1659,7 @@ paths:
       responses:
         "204":
           description: No Content
+      summary: Delete the specified probe template
       tags:
         - JMC Agent Templates
   /api/v4/recordings:
@@ -2168,6 +2176,7 @@ paths:
       responses:
         "204":
           description: No Content
+      summary: Remove all loaded probes from the specified target
       tags:
         - JMC Agent Probes
     get:
@@ -2187,10 +2196,13 @@ paths:
                   $ref: '#/components/schemas/ProbeResponse'
                 type: array
           description: OK
+      summary: List loaded probes on the specified target
       tags:
         - JMC Agent Probes
   /api/v4/targets/{id}/probes/{probeTemplateName}:
     post:
+      description: |
+        Activate a probe template (specified by template name) on the specified target (specified by ID).
       parameters:
         - in: path
           name: id
@@ -2206,6 +2218,7 @@ paths:
       responses:
         "201":
           description: Created
+      summary: Activate a probe template on the specified target
       tags:
         - JMC Agent Probes
   /api/v4/targets/{targetId}/recordingOptions:

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

@@ -40,6 +40,7 @@
 import jakarta.ws.rs.InternalServerErrorException;
 import jakarta.ws.rs.POST;
 import jakarta.ws.rs.Path;
+import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.jboss.logging.Logger;
 import org.jboss.resteasy.reactive.RestPath;
 
@@ -59,6 +60,12 @@ public class JMCAgentProbes {
     @Blocking
     @POST
     @Path("/api/v4/targets/{id}/probes/{probeTemplateName}")
+    @Operation(
+            summary = "Activate a probe template on the specified target",
+            description =
+                    """
+                    Activate a probe template (specified by template name) on the specified target (specified by ID).
+                    """)
     public void postProbe(@RestPath long id, @RestPath String probeTemplateName) {
         try {
             Target target = Target.getTargetById(id);
@@ -102,6 +109,7 @@ public void postProbe(@RestPath long id, @RestPath String probeTemplateName) {
     @Blocking
     @DELETE
     @Path("/api/v4/targets/{id}/probes")
+    @Operation(summary = "Remove all loaded probes from the specified target")
     public void deleteProbe(@RestPath long id) {
         try {
             Target target = Target.getTargetById(id);
@@ -133,6 +141,7 @@ public void deleteProbe(@RestPath long id) {
     @Blocking
     @GET
     @Path("/api/v4/targets/{id}/probes")
+    @Operation(summary = "List loaded probes on the specified target")
     public List<ProbeResponse> getProbes(@RestPath long id) {
         try {
             Target target = Target.getTargetById(id);

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

@@ -31,6 +31,7 @@
 import jakarta.ws.rs.core.Context;
 import jakarta.ws.rs.core.UriInfo;
 import org.apache.commons.lang3.StringUtils;
+import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.jboss.logging.Logger;
 import org.jboss.resteasy.reactive.RestForm;
 import org.jboss.resteasy.reactive.RestPath;
@@ -48,6 +49,7 @@ public class JMCAgentTemplates {
 
     @Blocking
     @GET
+    @Operation(summary = "List defined probe templates")
     public List<ProbeTemplateResponse> getProbeTemplates() {
         return service.getTemplates().stream()
                 .map(SerializableProbeTemplateInfo::fromProbeTemplate)
@@ -58,12 +60,22 @@ public List<ProbeTemplateResponse> getProbeTemplates() {
     @Blocking
     @DELETE
     @Path("/{probeTemplateName}")
+    @Operation(summary = "Delete the specified probe template")
     public void deleteProbeTemplate(@RestPath String probeTemplateName) {
         service.deleteTemplate(probeTemplateName);
     }
 
     @Blocking
     @POST
+    @Operation(
+            summary = "Create a probe template",
+            description =
+                    """
+                        Create a probe template. This requires a probe template file upload in XML format. See
+                        https://github.com/openjdk/jmc/blob/master/agent/README.md and
+                        https://github.com/openjdk/jmc/blob/master/agent/src/main/resources/org/openjdk/jmc/agent/impl/jfrprobes_schema.xsd
+                        for more information about this file format.
+                    """)
     public RestResponse<ProbeTemplate> uploadProbeTemplate(
             @Context UriInfo uriInfo,
             @RestForm("probeTemplate") FileUpload body,

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

@@ -55,6 +55,10 @@
 import software.amazon.awssdk.services.s3.model.Tag;
 import software.amazon.awssdk.services.s3.model.Tagging;
 
+/**
+ * Implementation for JMC Agent event probe templates stored in S3 object storage.
+ * @see io.cryostat.events.S3TemplateService
+ */
 public class S3ProbeTemplateService implements ProbeTemplateService {
 
     @ConfigProperty(name = ConfigProperties.AWS_BUCKET_NAME_PROBE_TEMPLATES)