document events

Author: andrewazores

schema/openapi.yaml

@@ -1331,6 +1331,10 @@ paths:
         - Archived Recordings
   /api/v4/event_templates:
     get:
+      description: |
+        Retrieve a list of templates available on this Cryostat server. These templates can be applied to
+        recordings started on any discovered target, but any event configurations within the template which
+        reference events that do not exist on the target will be ignored.
       responses:
         "200":
           content:
@@ -1346,9 +1350,12 @@ paths:
           description: Not Allowed
       security:
         - SecurityScheme: []
+      summary: List server event templates
       tags:
         - Event Templates
     post:
+      description: |
+        Upload a new custom event template to the server. This must be in OpenJDK .jfc (XML) format.
       requestBody:
         content:
           application/x-www-form-urlencoded:
@@ -1370,10 +1377,14 @@ paths:
           description: Not Allowed
       security:
         - SecurityScheme: []
+      summary: Upload a custom event template
       tags:
         - Event Templates
   /api/v4/event_templates/{templateName}:
     delete:
+      description: |
+        Delete a custom event template from the server. Only previously uploaded custom event templates can
+        be deleted.
       parameters:
         - in: path
           name: templateName
@@ -1389,6 +1400,7 @@ paths:
           description: Not Allowed
       security:
         - SecurityScheme: []
+      summary: Delete a custom event template
       tags:
         - Event Templates
   /api/v4/event_templates/{templateType}:
@@ -1414,10 +1426,14 @@ paths:
           description: Not Allowed
       security:
         - SecurityScheme: []
+      summary: List server event templates of the given type
       tags:
         - Event Templates
   /api/v4/event_templates/{templateType}/{templateName}:
     get:
+      description: |
+        Get the .jfc (XML) file definition for the given server event template. This is the same type of
+        event configuration file that ships with OpenJDK distributions.
       parameters:
         - in: path
           name: templateName
@@ -1442,6 +1458,7 @@ paths:
           description: Not Allowed
       security:
         - SecurityScheme: []
+      summary: Get a specific event template
       tags:
         - Event Templates
   /api/v4/grafana/{encodedKey}:
@@ -2025,6 +2042,10 @@ paths:
         - Targets
   /api/v4/targets/{id}/event_templates:
     get:
+      description: |
+        Retrieve a list of event templates available on the given target when starting recordings on the
+        same target. This includes all of the server's available templates, plus the templates available
+        specifically from the target (ex. within /usr/lib/jvm/java/lib/jfr).
       parameters:
         - in: path
           name: id
@@ -2047,10 +2068,13 @@ paths:
           description: Not Allowed
       security:
         - SecurityScheme: []
+      summary: Retrieve a list of event templates available on the given target
       tags:
         - Target Event Templates
   /api/v4/targets/{id}/event_templates/{templateType}/{templateName}:
     get:
+      description: |
+        Get the .jfc (XML) file definition for the given target event template.
       parameters:
         - in: path
           name: id
@@ -2081,10 +2105,16 @@ paths:
           description: Not Allowed
       security:
         - SecurityScheme: []
+      summary: Get a specific event template
       tags:
         - Target Event Templates
   /api/v4/targets/{id}/events:
     get:
+      description: |
+        Retrieve a list of JFR event types registered within the given target. This will include all
+        built-in JFR types emitted by the target JVM, as well as custom event types specific to that
+        target JVM if they are correctly registered. Custom event types, or event types emitted by plugins
+        and extensions, may not always appear in this list.
       parameters:
         - in: path
           name: id
@@ -2111,6 +2141,7 @@ paths:
           description: Not Allowed
       security:
         - SecurityScheme: []
+      summary: List JFR event types registered within the given target
       tags:
         - Events
   /api/v4/targets/{id}/probes:

src/main/java/io/cryostat/events/EventTemplates.java

@@ -41,6 +41,7 @@
 import jakarta.ws.rs.core.MediaType;
 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;
@@ -69,6 +70,14 @@ public class EventTemplates {
     @GET
     @Blocking
     @RolesAllowed("read")
+    @Operation(
+            summary = "List server event templates",
+            description =
+                    """
+                    Retrieve a list of templates available on this Cryostat server. These templates can be applied to
+                    recordings started on any discovered target, but any event configurations within the template which
+                    reference events that do not exist on the target will be ignored.
+                    """)
     public List<Template> listTemplates() throws Exception {
         var list = new ArrayList<Template>();
         list.add(ALL_EVENTS_TEMPLATE);
@@ -81,6 +90,7 @@ public List<Template> listTemplates() throws Exception {
     @Path("/{templateType}")
     @Blocking
     @RolesAllowed("read")
+    @Operation(summary = "List server event templates of the given type")
     public List<Template> getTemplates(@RestPath String templateType)
             throws IOException, FlightRecorderException {
         TemplateType tt = TemplateType.valueOf(templateType);
@@ -99,6 +109,13 @@ public List<Template> getTemplates(@RestPath String templateType)
     @Blocking
     @RolesAllowed("read")
     @Produces(MediaType.APPLICATION_XML)
+    @Operation(
+            summary = "Get a specific event template",
+            description =
+                    """
+                    Get the .jfc (XML) file definition for the given server event template. This is the same type of
+                    event configuration file that ships with OpenJDK distributions.
+                    """)
     public String getTemplate(@RestPath String templateType, @RestPath String templateName)
             throws IOException, FlightRecorderException {
         TemplateType tt = TemplateType.valueOf(templateType);
@@ -118,6 +135,12 @@ public String getTemplate(@RestPath String templateType, @RestPath String templa
 
     @POST
     @RolesAllowed("write")
+    @Operation(
+            summary = "Upload a custom event template",
+            description =
+                    """
+                    Upload a new custom event template to the server. This must be in OpenJDK .jfc (XML) format.
+                    """)
     public RestResponse<Template> postTemplates(
             @Context UriInfo uriInfo, @RestForm("template") FileUpload body) throws IOException {
         if (body == null || body.filePath() == null || !"template".equals(body.name())) {
@@ -138,6 +161,13 @@ public RestResponse<Template> postTemplates(
     @Blocking
     @Path("/{templateName}")
     @RolesAllowed("write")
+    @Operation(
+            summary = "Delete a custom event template",
+            description =
+                    """
+                    Delete a custom event template from the server. Only previously uploaded custom event templates can
+                    be deleted.
+                    """)
     public void deleteTemplate(@RestPath String templateName) throws FlightRecorderException {
         if (StringUtils.isBlank(templateName)) {
             throw new BadRequestException();

src/main/java/io/cryostat/events/Events.java

@@ -30,6 +30,7 @@
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.Path;
 import org.apache.commons.lang3.StringUtils;
+import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.jboss.logging.Logger;
 import org.jboss.resteasy.reactive.RestPath;
 import org.jboss.resteasy.reactive.RestQuery;
@@ -43,6 +44,15 @@ public class Events {
     @GET
     @Path("/api/v4/targets/{id}/events")
     @RolesAllowed("read")
+    @Operation(
+            summary = "List JFR event types registered within the given target",
+            description =
+                    """
+                    Retrieve a list of JFR event types registered within the given target. This will include all
+                    built-in JFR types emitted by the target JVM, as well as custom event types specific to that
+                    target JVM if they are correctly registered. Custom event types, or event types emitted by plugins
+                    and extensions, may not always appear in this list.
+                    """)
     public List<SerializableEventTypeInfo> listEvents(@RestPath long id, @RestQuery String q)
             throws Exception {
         return searchEvents(Target.find("id", id).singleResult(), q);

src/main/java/io/cryostat/events/PresetTemplateService.java

@@ -57,6 +57,13 @@
 import org.jsoup.Jsoup;
 import org.jsoup.parser.Parser;
 
+/**
+ * Event Template service implementation for Preset templates. Preset templates are ones located in
+ * src/main/docker/include/template_presets and are available to be applied to any discovered
+ * target. These behave similarly to {@link io.cryostat.events.S3TemplateService} Custom Event
+ * Templates, except Presets are shipped with the Cryostat distribution and cannot be deleted by end
+ * users at runtime.
+ */
 @ApplicationScoped
 public class PresetTemplateService implements TemplateService {
 

src/main/java/io/cryostat/events/S3TemplateService.java

@@ -73,6 +73,11 @@
 import software.amazon.awssdk.services.s3.model.Tag;
 import software.amazon.awssdk.services.s3.model.Tagging;
 
+/**
+ * Event Template service implementation for Custom Event Templates. Custom Event Templates are ones
+ * that users can create and delete at runtime. These must be in conventional .jfc XML format. This
+ * implementation uses an S3 object storage service to house the XML files.
+ */
 @ApplicationScoped
 public class S3TemplateService implements MutableTemplateService {
 

src/main/java/io/cryostat/events/TargetEventTemplates.java

@@ -35,6 +35,7 @@
 import jakarta.ws.rs.Path;
 import jakarta.ws.rs.Produces;
 import jakarta.ws.rs.core.MediaType;
+import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.jboss.logging.Logger;
 import org.jboss.resteasy.reactive.RestPath;
 
@@ -59,6 +60,14 @@ public class TargetEventTemplates {
     @GET
     @Blocking
     @RolesAllowed("read")
+    @Operation(
+            summary = "Retrieve a list of event templates available on the given target",
+            description =
+                    """
+                    Retrieve a list of event templates available on the given target when starting recordings on the
+                    same target. This includes all of the server's available templates, plus the templates available
+                    specifically from the target (ex. within /usr/lib/jvm/java/lib/jfr).
+                    """)
     public List<Template> listTargetTemplates(@RestPath long id) throws Exception {
         Target target = Target.find("id", id).singleResult();
         var list = new ArrayList<Template>();
@@ -79,6 +88,12 @@ public List<Template> listTargetTemplates(@RestPath long id) throws Exception {
     @Path("/{templateType}/{templateName}")
     @RolesAllowed("read")
     @Produces(MediaType.APPLICATION_XML)
+    @Operation(
+            summary = "Get a specific event template",
+            description =
+                    """
+                    Get the .jfc (XML) file definition for the given target event template.
+                    """)
     public String getTargetTemplate(
             @RestPath long id, @RestPath TemplateType templateType, @RestPath String templateName)
             throws Exception {