Skip to content

Commit de7510b

Browse files
committed
document events
1 parent 7d3a7c1 commit de7510b

File tree

6 files changed

+98
-0
lines changed

6 files changed

+98
-0
lines changed

schema/openapi.yaml

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1331,6 +1331,10 @@ paths:
13311331
- Archived Recordings
13321332
/api/v4/event_templates:
13331333
get:
1334+
description: |
1335+
Retrieve a list of templates available on this Cryostat server. These templates can be applied to
1336+
recordings started on any discovered target, but any event configurations within the template which
1337+
reference events that do not exist on the target will be ignored.
13341338
responses:
13351339
"200":
13361340
content:
@@ -1346,9 +1350,12 @@ paths:
13461350
description: Not Allowed
13471351
security:
13481352
- SecurityScheme: []
1353+
summary: List server event templates
13491354
tags:
13501355
- Event Templates
13511356
post:
1357+
description: |
1358+
Upload a new custom event template to the server. This must be in OpenJDK .jfc (XML) format.
13521359
requestBody:
13531360
content:
13541361
application/x-www-form-urlencoded:
@@ -1370,10 +1377,14 @@ paths:
13701377
description: Not Allowed
13711378
security:
13721379
- SecurityScheme: []
1380+
summary: Upload a custom event template
13731381
tags:
13741382
- Event Templates
13751383
/api/v4/event_templates/{templateName}:
13761384
delete:
1385+
description: |
1386+
Delete a custom event template from the server. Only previously uploaded custom event templates can
1387+
be deleted.
13771388
parameters:
13781389
- in: path
13791390
name: templateName
@@ -1389,6 +1400,7 @@ paths:
13891400
description: Not Allowed
13901401
security:
13911402
- SecurityScheme: []
1403+
summary: Delete a custom event template
13921404
tags:
13931405
- Event Templates
13941406
/api/v4/event_templates/{templateType}:
@@ -1414,10 +1426,14 @@ paths:
14141426
description: Not Allowed
14151427
security:
14161428
- SecurityScheme: []
1429+
summary: List server event templates of the given type
14171430
tags:
14181431
- Event Templates
14191432
/api/v4/event_templates/{templateType}/{templateName}:
14201433
get:
1434+
description: |
1435+
Get the .jfc (XML) file definition for the given server event template. This is the same type of
1436+
event configuration file that ships with OpenJDK distributions.
14211437
parameters:
14221438
- in: path
14231439
name: templateName
@@ -1442,6 +1458,7 @@ paths:
14421458
description: Not Allowed
14431459
security:
14441460
- SecurityScheme: []
1461+
summary: Get a specific event template
14451462
tags:
14461463
- Event Templates
14471464
/api/v4/grafana/{encodedKey}:
@@ -2025,6 +2042,10 @@ paths:
20252042
- Targets
20262043
/api/v4/targets/{id}/event_templates:
20272044
get:
2045+
description: |
2046+
Retrieve a list of event templates available on the given target when starting recordings on the
2047+
same target. This includes all of the server's available templates, plus the templates available
2048+
specifically from the target (ex. within /usr/lib/jvm/java/lib/jfr).
20282049
parameters:
20292050
- in: path
20302051
name: id
@@ -2047,10 +2068,13 @@ paths:
20472068
description: Not Allowed
20482069
security:
20492070
- SecurityScheme: []
2071+
summary: Retrieve a list of event templates available on the given target
20502072
tags:
20512073
- Target Event Templates
20522074
/api/v4/targets/{id}/event_templates/{templateType}/{templateName}:
20532075
get:
2076+
description: |
2077+
Get the .jfc (XML) file definition for the given target event template.
20542078
parameters:
20552079
- in: path
20562080
name: id
@@ -2081,10 +2105,16 @@ paths:
20812105
description: Not Allowed
20822106
security:
20832107
- SecurityScheme: []
2108+
summary: Get a specific event template
20842109
tags:
20852110
- Target Event Templates
20862111
/api/v4/targets/{id}/events:
20872112
get:
2113+
description: |
2114+
Retrieve a list of JFR event types registered within the given target. This will include all
2115+
built-in JFR types emitted by the target JVM, as well as custom event types specific to that
2116+
target JVM if they are correctly registered. Custom event types, or event types emitted by plugins
2117+
and extensions, may not always appear in this list.
20882118
parameters:
20892119
- in: path
20902120
name: id
@@ -2111,6 +2141,7 @@ paths:
21112141
description: Not Allowed
21122142
security:
21132143
- SecurityScheme: []
2144+
summary: List JFR event types registered within the given target
21142145
tags:
21152146
- Events
21162147
/api/v4/targets/{id}/probes:

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@
4141
import jakarta.ws.rs.core.MediaType;
4242
import jakarta.ws.rs.core.UriInfo;
4343
import org.apache.commons.lang3.StringUtils;
44+
import org.eclipse.microprofile.openapi.annotations.Operation;
4445
import org.jboss.logging.Logger;
4546
import org.jboss.resteasy.reactive.RestForm;
4647
import org.jboss.resteasy.reactive.RestPath;
@@ -69,6 +70,14 @@ public class EventTemplates {
6970
@GET
7071
@Blocking
7172
@RolesAllowed("read")
73+
@Operation(
74+
summary = "List server event templates",
75+
description =
76+
"""
77+
Retrieve a list of templates available on this Cryostat server. These templates can be applied to
78+
recordings started on any discovered target, but any event configurations within the template which
79+
reference events that do not exist on the target will be ignored.
80+
""")
7281
public List<Template> listTemplates() throws Exception {
7382
var list = new ArrayList<Template>();
7483
list.add(ALL_EVENTS_TEMPLATE);
@@ -81,6 +90,7 @@ public List<Template> listTemplates() throws Exception {
8190
@Path("/{templateType}")
8291
@Blocking
8392
@RolesAllowed("read")
93+
@Operation(summary = "List server event templates of the given type")
8494
public List<Template> getTemplates(@RestPath String templateType)
8595
throws IOException, FlightRecorderException {
8696
TemplateType tt = TemplateType.valueOf(templateType);
@@ -99,6 +109,13 @@ public List<Template> getTemplates(@RestPath String templateType)
99109
@Blocking
100110
@RolesAllowed("read")
101111
@Produces(MediaType.APPLICATION_XML)
112+
@Operation(
113+
summary = "Get a specific event template",
114+
description =
115+
"""
116+
Get the .jfc (XML) file definition for the given server event template. This is the same type of
117+
event configuration file that ships with OpenJDK distributions.
118+
""")
102119
public String getTemplate(@RestPath String templateType, @RestPath String templateName)
103120
throws IOException, FlightRecorderException {
104121
TemplateType tt = TemplateType.valueOf(templateType);
@@ -118,6 +135,12 @@ public String getTemplate(@RestPath String templateType, @RestPath String templa
118135

119136
@POST
120137
@RolesAllowed("write")
138+
@Operation(
139+
summary = "Upload a custom event template",
140+
description =
141+
"""
142+
Upload a new custom event template to the server. This must be in OpenJDK .jfc (XML) format.
143+
""")
121144
public RestResponse<Template> postTemplates(
122145
@Context UriInfo uriInfo, @RestForm("template") FileUpload body) throws IOException {
123146
if (body == null || body.filePath() == null || !"template".equals(body.name())) {
@@ -138,6 +161,13 @@ public RestResponse<Template> postTemplates(
138161
@Blocking
139162
@Path("/{templateName}")
140163
@RolesAllowed("write")
164+
@Operation(
165+
summary = "Delete a custom event template",
166+
description =
167+
"""
168+
Delete a custom event template from the server. Only previously uploaded custom event templates can
169+
be deleted.
170+
""")
141171
public void deleteTemplate(@RestPath String templateName) throws FlightRecorderException {
142172
if (StringUtils.isBlank(templateName)) {
143173
throw new BadRequestException();

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
import jakarta.ws.rs.GET;
3131
import jakarta.ws.rs.Path;
3232
import org.apache.commons.lang3.StringUtils;
33+
import org.eclipse.microprofile.openapi.annotations.Operation;
3334
import org.jboss.logging.Logger;
3435
import org.jboss.resteasy.reactive.RestPath;
3536
import org.jboss.resteasy.reactive.RestQuery;
@@ -43,6 +44,15 @@ public class Events {
4344
@GET
4445
@Path("/api/v4/targets/{id}/events")
4546
@RolesAllowed("read")
47+
@Operation(
48+
summary = "List JFR event types registered within the given target",
49+
description =
50+
"""
51+
Retrieve a list of JFR event types registered within the given target. This will include all
52+
built-in JFR types emitted by the target JVM, as well as custom event types specific to that
53+
target JVM if they are correctly registered. Custom event types, or event types emitted by plugins
54+
and extensions, may not always appear in this list.
55+
""")
4656
public List<SerializableEventTypeInfo> listEvents(@RestPath long id, @RestQuery String q)
4757
throws Exception {
4858
return searchEvents(Target.find("id", id).singleResult(), q);

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,13 @@
5757
import org.jsoup.Jsoup;
5858
import org.jsoup.parser.Parser;
5959

60+
/**
61+
* Event Template service implementation for Preset templates. Preset templates are ones located in
62+
* src/main/docker/include/template_presets and are available to be applied to any discovered
63+
* target. These behave similarly to {@link io.cryostat.events.S3TemplateService} Custom Event
64+
* Templates, except Presets are shipped with the Cryostat distribution and cannot be deleted by end
65+
* users at runtime.
66+
*/
6067
@ApplicationScoped
6168
public class PresetTemplateService implements TemplateService {
6269

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,11 @@
7373
import software.amazon.awssdk.services.s3.model.Tag;
7474
import software.amazon.awssdk.services.s3.model.Tagging;
7575

76+
/**
77+
* Event Template service implementation for Custom Event Templates. Custom Event Templates are ones
78+
* that users can create and delete at runtime. These must be in conventional .jfc XML format. This
79+
* implementation uses an S3 object storage service to house the XML files.
80+
*/
7681
@ApplicationScoped
7782
public class S3TemplateService implements MutableTemplateService {
7883

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
import jakarta.ws.rs.Path;
3636
import jakarta.ws.rs.Produces;
3737
import jakarta.ws.rs.core.MediaType;
38+
import org.eclipse.microprofile.openapi.annotations.Operation;
3839
import org.jboss.logging.Logger;
3940
import org.jboss.resteasy.reactive.RestPath;
4041

@@ -59,6 +60,14 @@ public class TargetEventTemplates {
5960
@GET
6061
@Blocking
6162
@RolesAllowed("read")
63+
@Operation(
64+
summary = "Retrieve a list of event templates available on the given target",
65+
description =
66+
"""
67+
Retrieve a list of event templates available on the given target when starting recordings on the
68+
same target. This includes all of the server's available templates, plus the templates available
69+
specifically from the target (ex. within /usr/lib/jvm/java/lib/jfr).
70+
""")
6271
public List<Template> listTargetTemplates(@RestPath long id) throws Exception {
6372
Target target = Target.find("id", id).singleResult();
6473
var list = new ArrayList<Template>();
@@ -79,6 +88,12 @@ public List<Template> listTargetTemplates(@RestPath long id) throws Exception {
7988
@Path("/{templateType}/{templateName}")
8089
@RolesAllowed("read")
8190
@Produces(MediaType.APPLICATION_XML)
91+
@Operation(
92+
summary = "Get a specific event template",
93+
description =
94+
"""
95+
Get the .jfc (XML) file definition for the given target event template.
96+
""")
8297
public String getTargetTemplate(
8398
@RestPath long id, @RestPath TemplateType templateType, @RestPath String templateName)
8499
throws Exception {

0 commit comments

Comments
 (0)