Skip to content

Commit af47f3f

Browse files
andrewazoresandrewazores
authored
docs(auto-rules): update HTTP_API.md (#562)
* Correct formatting error * Add handler descriptions to quick reference table * Document RulesPostHandler * Respond 409 if rule with given name already exists * Document RuleDeleteHandler, RuleGetHandler, RulesGetHandler * Document TargetCredentialsPostHandler and TargetCredentialsDeleteHandler * fix typo
1 parent 74328d3 commit af47f3f

File tree

3 files changed

+231
-3
lines changed

3 files changed

+231
-3
lines changed

‎HTTP_API.md

+227-3
Original file line numberDiff line numberDiff line change
@@ -1200,7 +1200,7 @@ metadata-wrapped and JSON-encoded response format with the following general
12001200
form:
12011201
12021202
```
1203-
{ "meta:" { "status:" "statusString", "type:" "mime/type"}, "data:" { "someKey:" someValue } }
1203+
{ "meta": { "status": "statusString", "type": "mime/type"}, "data": { "someKey": someValue } }
12041204
```
12051205
12061206
`statusString` will always be `OK` if the response status code is `200`. If the
@@ -1234,14 +1234,22 @@ The handler-specific descriptions below describe how each handler populates the
12341234
12351235
| What you want to do | Which handler you should use |
12361236
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------|
1237-
| **Recordings in target JVMs** | |
1237+
| **Recordings in Target JVMs** | |
12381238
| Search event types that can be produced by a target JVM | [`TargetEventsSearchGetHandler`](#TargetEventsSearchGetHandler) |
12391239
| Get a list of recording options for a target JVM | [`TargetRecordingOptionsListGetHandler`](#TargetRecordingOptionsListGetHandler) |
12401240
| Create a snapshot recording in a target JVM | [`TargetSnapshotPostHandler`](#TargetSnapshotPostHandler-1) |
1241+
| **Automated Rules** | |
1242+
| Create an automated rule definition | [`RulesPostHandler`](#RulesPostHandler) |
1243+
| Delete an automated rule definition | [`RuleDeleteHandler`](#RuleDeleteHandler) |
1244+
| Get an automated rule definition | [`RuleGetHandler`](#RuleGetHandler) |
1245+
| Get all automated rule definitions | [`RulesGetHandler`](#RulesGetHandler) |
1246+
| **Stored Target Credentials** | |
1247+
| Add stored credentials for a target | [`TargetCredentialsPostHandler`](#TargetCredentialsPostHandler) |
1248+
| Delete stored credentials for a target | [`TargetCredentialsDeleteHandler`](#TargetCredentialsDeleteHandler) |
12411249
| **Security** | |
12421250
| Upload an SSL Certificate | [`CertificatePostHandler`](#CertificatePostHandler) |
12431251
1244-
### Flight Recorder
1252+
### Recordings in Target JVMs
12451253
12461254
* #### `TargetEventsSearchGetHandler`
12471255
@@ -1368,6 +1376,222 @@ The handler-specific descriptions below describe how each handler populates the
13681376
{"meta":{"status":"Created","type":"application/json"},"data":{"result":{"downloadUrl":"http://192.168.0.109:8181/api/v1/targets/service:jmx:rmi:%2F%2F%2Fjndi%2Frmi:%2F%2Flocalhost:9091%2Fjmxrmi/recordings/snapshot-1","reportUrl":"http://192.168.0.109:8181/api/v1/targets/service:jmx:rmi:%2F%2F%2Fjndi%2Frmi:%2F%2Flocalhost:9091%2Fjmxrmi/reports/snapshot-1","id":1,"name":"snapshot-1","state":"STOPPED","startTime":1601998841300,"duration":0,"continuous":true,"toDisk":true,"maxSize":0,"maxAge":0}}}
13691377
```
13701378
1379+
### Automated Rules
1380+
1381+
* #### `RulesPostHandler`
1382+
1383+
##### synopsis
1384+
Creates a new automated rule definition. Cryostat processes automated rules
1385+
to start recordings on matching targets as they appear, non-interactively.
1386+
Newly-POSTed rule definitions will also retroactively apply to already-known
1387+
targets, if any.
1388+
1389+
##### request
1390+
`POST /api/v2/rules`
1391+
1392+
The request may be an HTTP form or a JSON document. In either case, the
1393+
attributes `"name"`, `"targetAlias"`, and `"eventSpecifier"` must be
1394+
provided.
1395+
1396+
`"name"`: the name of this rule definition. This must be unique. This name
1397+
will also be used to generate the name of the associated recordings.
1398+
1399+
`"targetAlias"`: targets with an exactly matching `alias` will match this
1400+
rule definition, activating this rule for the target and causing the defined
1401+
recording to be started on the target.
1402+
1403+
`"eventSpecifier"`: a string of the form `template=Foo,type=TYPE`. This
1404+
defines the event template that will be used for creating new recordings in
1405+
matching targets.
1406+
1407+
The following attributes are optional:
1408+
1409+
`"description"`: a textual description of the purpose or reason for this
1410+
rule definition. This is informational and for display only.
1411+
1412+
`"archivalPeriodSeconds"`: a positive integer value that defines how long
1413+
Cryostat should wait, in seconds, between archiving snapshots of the
1414+
recording. The default setting is 30.
1415+
1416+
`"preservedArchives"`: a positive integer value that defines how many
1417+
archived copies of the recording should be kept in storage. When the number
1418+
of archived copies exceeds this number the oldest copies are deleted from
1419+
storage. The default setting is 1.
1420+
1421+
`"maxAgeSeconds"`: a positive integer value that defines the maximum age of
1422+
data to be retained in the active, in-memory Flight Recording within the
1423+
Target JVM. This can be used in combination with `"archivalPeriodSeconds"`
1424+
to minimize or eliminate data overlap between the end of one archived
1425+
recording and the start of the subsequent archived recording. If not
1426+
specified, the default setting is equal to `"archivalPeriodSeconds"`.
1427+
1428+
`"maxSizeBytes"`: a positive integer value that defines the maximum size, in
1429+
bytes, of the active in-memory Flight Recording within the Target JVM. If
1430+
the recording exceeds this memory size then event data will be dropped from
1431+
the recording. The default setting is unlimited.
1432+
1433+
##### response
1434+
`201` - The result is the name of the created rule. The `LOCATION` header
1435+
will be set and its value will be the relative path to the created resource.
1436+
1437+
`400` - The rule definition could not be processed, either because the
1438+
provided document was malformed or invalid.
1439+
1440+
`401` - User authentication failed. The reason is an error message.
1441+
There will be an `X-WWW-Authenticate: $SCHEME` header that indicates
1442+
the authentication scheme that is used.
1443+
1444+
`409` - A rule with the same name already exists.
1445+
1446+
`415` - The request's `Content-Type` was invalid or unrecognized.
1447+
1448+
`500` - There was an unexpected error.
1449+
1450+
##### example
1451+
```
1452+
$ curl -X POST -F name="Test Rule" -F description="This is a rule for testing" -F targetAlias="io.cryostat.Cryostat" -F eventSpecifier="template=Continuous,type=TARGET" http://0.0.0.0:8181/api/v2/rules
1453+
< HTTP/1.1 201 Created
1454+
< location: /api/v2/rules/Test_Rule
1455+
< content-length: 79
1456+
{"meta":{"type":"text/plain","status":"Created"},"data":{"result":"Test_Rule"}}
1457+
```
1458+
1459+
* #### `RuleDeleteHandler`
1460+
1461+
##### synopsis
1462+
Deletes a rule definition.
1463+
1464+
##### request
1465+
`DELETE /api/v2/rules/:name`
1466+
1467+
##### response
1468+
`200` - The result is empty. The rule was successfully deleted.
1469+
1470+
`401` - User authentication failed. The reason is an error message.
1471+
There will be an `X-WWW-Authenticate: $SCHEME` header that indicates
1472+
the authentication scheme that is used.
1473+
1474+
`404` - No rule with the given name exists.
1475+
1476+
`500`- An unexpected IOException occurred while deleting the rule
1477+
definition.
1478+
1479+
##### example
1480+
```
1481+
$ curl -X DELETE http://0.0.0.0:8181/api/v2/rules/Test_Rule
1482+
{"meta":{"type":"text/plain","status":"OK"},"data":{"result":null}}
1483+
```
1484+
1485+
* #### `RuleGetHandler`
1486+
1487+
##### synopsis
1488+
Get a JSON document describing a rule definition with the given name.
1489+
1490+
##### request
1491+
`GET /api/v2/rules/:name`
1492+
1493+
##### response
1494+
`200` - The result is a JSON string representing the rule definition.
1495+
1496+
`401` - User authentication failed. The reason is an error message.
1497+
There will be an `X-WWW-Authenticate: $SCHEME` header that indicates
1498+
the authentication scheme that is used.
1499+
1500+
`404` - No rule with the given name exists.
1501+
1502+
`500` - There was an unexpected error.
1503+
1504+
##### example
1505+
```
1506+
$ curl http://0.0.0.0:8181/api/v2/rules/Test_Rule
1507+
{"meta":{"type":"application/json","status":"OK"},"data":{"result":{"name":"Test_Rule","description":"This is a rule for testing","targetAlias":"io.cryostat.Cryostat","eventSpecifier":"template=Continuous,type=TARGET","archivalPeriodSeconds":30,"preservedArchives":1,"maxAgeSeconds":30,"maxSizeBytes":-1}}}
1508+
```
1509+
1510+
* #### `RulesGetHandler`
1511+
1512+
##### synopsis
1513+
Get a JSON array representing all rule definitions.
1514+
1515+
##### request
1516+
`GET /api/v2/rules`
1517+
1518+
##### response
1519+
`200` - The result is a JSON array representing all rule definitions.
1520+
1521+
`401` - User authentication failed. The reason is an error message.
1522+
There will be an `X-WWW-Authenticate: $SCHEME` header that indicates
1523+
the authentication scheme that is used.
1524+
1525+
`500` - There was an unexpected error.
1526+
1527+
##### example
1528+
```
1529+
$ curl http://0.0.0.0:8181/api/v2/rules
1530+
{"meta":{"type":"application/json","status":"OK"},"data":{"result":[{"name":"Test_Rule","description":"This is a rule for testing","targetAlias":"io.cryostat.Cryostat","eventSpecifier":"template=Continuous,type=TARGET","archivalPeriodSeconds":30,"preservedArchives":1,"maxAgeSeconds":30,"maxSizeBytes":-1}]}}
1531+
```
1532+
1533+
### Stored Target Credentials
1534+
1535+
* #### `TargetCredentialsPostHandler`
1536+
1537+
##### synopsis
1538+
Creates stored credentials for a given target. These are used for automated
1539+
rules processing - if a Target JVM requires JMX authentication, Cryostat
1540+
will use stored credentials when attempting to open JMX connections to the
1541+
target. These are retained in Cryostat's memory only and not persisted to
1542+
disk.
1543+
1544+
##### request
1545+
`POST /api/v2/targets/:targetId/credentials`
1546+
1547+
The request should be an HTTP form with the attributes `"username"` and
1548+
`"password"`. Both are required.
1549+
1550+
##### response
1551+
`200` - The result is null. The request was processed successfully and the
1552+
credentials were stored, potentially overriding previous credentials for the
1553+
same target.
1554+
1555+
`400` - `"username"` and/or `"password"` were not provided.
1556+
1557+
`401` - User authentication failed. The reason is an error message.
1558+
There will be an `X-WWW-Authenticate: $SCHEME` header that indicates
1559+
the authentication scheme that is used.
1560+
1561+
`500` - There was an unexpected error.
1562+
1563+
##### example
1564+
```
1565+
$ curl -F username=user -F password=pass http://0.0.0.0:8181/api/v2/targets/localhost/credentials
1566+
{"meta":{"type":"text/plain","status":"OK"},"data":{"result":null}}
1567+
```
1568+
1569+
* #### `TargetCredentialsDeleteHandler`
1570+
1571+
##### synopsis
1572+
Deletes stored credentials for a given target.
1573+
1574+
##### request
1575+
`DELETE /api/v2/targets/:targetId/credentials`
1576+
1577+
##### response
1578+
`200` - The result is null. The request was processed successfully and the
1579+
credentials were deleted.
1580+
1581+
`404` - The target had no stored credentials.
1582+
1583+
`401` - User authentication failed. The reason is an error message.
1584+
There will be an `X-WWW-Authenticate: $SCHEME` header that indicates
1585+
the authentication scheme that is used.
1586+
1587+
`500` - There was an unexpected error.
1588+
1589+
##### example
1590+
```
1591+
$ curl -X DELETE http://0.0.0.0:8181/api/v2/targets/localhost/credentials
1592+
{"meta":{"type":"text/plain","status":"OK"},"data":{"result":null}}
1593+
```
1594+
13711595
### Security
13721596
13731597
* #### `CertificatePostHandler`

‎src/main/java/io/cryostat/net/web/http/api/v2/RulesPostHandler.java

+3
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@
4646
import io.cryostat.net.web.http.HttpMimeType;
4747
import io.cryostat.net.web.http.api.ApiVersion;
4848
import io.cryostat.rules.Rule;
49+
import io.cryostat.rules.RuleException;
4950
import io.cryostat.rules.RuleRegistry;
5051

5152
import com.google.gson.Gson;
@@ -137,6 +138,8 @@ public IntermediateResponse<String> handle(RequestParameters params) throws ApiE
137138

138139
try {
139140
rule = this.ruleRegistry.addRule(rule);
141+
} catch (RuleException e) {
142+
throw new ApiException(409, e);
140143
} catch (IOException e) {
141144
throw new ApiException(
142145
500,

‎src/main/java/io/cryostat/rules/RuleException.java

+1
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939

4040
import java.io.IOException;
4141

42+
@SuppressWarnings("serial")
4243
public class RuleException extends IOException {
4344
RuleException(String reason) {
4445
super(reason);

0 commit comments

Comments
 (0)