This document provides a brief listing of the commands implemented by this
client, including a short synopsis of any expected arguments. Sample outputs
reflect the human-friendly output produced when running cryostat in
tty or tcp modes. In ws mode the output will be semantically similar but
formatted as a JSON response.
-
helpLists available commands. This may vary depending on various factors, such as whether a recording archive directory exists and has appropriate permissions.
-
scan-targetsScans for discoverable target JVMs. This may use various discovery mechanisms, including Kubernetes service discovery or JDP. For more details see this document.
-
pingUsed to test the connection between
cryostatand whatever end client is in use by the user, whether that is ex. netcat over a TCP socket orcryostat-web. Outputs "pong" unconditionally, signifying the connection is open and working. -
exitExit the client session. Recording option settings will be lost, but recordings themselves will be maintained so long as the containing targets stay alive.
-
ipPrints the IP address of the client container.
-
hostnamePrints the Hostname of the client container.
-
urlPrints the embedded webserver download URL for the client. Recordings can be downloaded from
$URL/$RECORDING, where$URLis the output from this command and$RECORDINGis the name of a recording in the target JVM. -
wait 10Waits for (at least) the specified number of seconds (
10). This cannot be interrupted.
-
start targetId foo template=FooStarts a continuous recording in the target JVM with the given name (
foo), which will record events as configured in the event template.The targetID is a
hostname:portorservice:rmi:jmx://JMX Service URL specifying the location of the remote target JVM to connect to.The event template (
template=Foo) allows preset configurations of events and options to be enabled.For information about the events and options available, see
list-event-typesorsearch-events. -
stop targetId fooStops the given recording (
foo) in the specified target JVM. -
dump targetId foo 30 template=FooStarts a recording in the specified target JVM with the given name (
foo), with a fixed duration of the given number of seconds (30), and recording events as configured in the event template. -
snapshotCreates a recording named
snapshot-n, where n is a sequentially assigned ID, which contains information about all events recorded across all active recordings at the time of invocation. -
save targetId fooSaves the named recording in the specified target JVM to persistent storage attached to the
cryostatcontainer. The saved recording contains a snapshot of its parent in-memory recording at the time of the save and is not updated (unless overwritten by a new save in the future). A saved recording is not tied to the lifecycle of the JVM which produced it - that is, the recording will remain available even if the target JVM dies.For
cryostatto be able to save recordings to persistent storage, there must be persistent storage available to the container. The storage is expected to be mounted at the path/flightrecordingswithin the container. The exact type of persistent storage is not important, so long as it is a writeable directory. -
upload-recording targetId fooUploads the named recording from the specified target JVM to the jfr-datasource instance specified by the environment variable GRAFANA_DATASOURCE_URL, which exposes the information contained within the recording to its associated Grafana instance. For information on setting environment variables to enable uploading, see README.md .
-
delete targetId fooDeletes the named recording, removing it from the target JVM and freeing the buffer memory used. The recording will be stopped automatically if it is running at the time of deletion.
-
delete-saved foo.jfrDeletes the named recording from persistent storage. This does not affect any recordings in any target JVM's JFR buffer.
-
search-events targetId fooSearches for event types that can be produced by the specified target JVM where the event name, category, label, etc. matches the given query (
foo). -
list-event-types targetIdLists event types that can be produced by the specified target JVM.
-
list-event-templates targetIdLists event templates known to the specified target JVM, which are configurations of event types with preset values for their associated options. These may include templates defined and supported by the specified remote target JVM as well as customized templates known to
cryostat. -
recording-option toDisk=true|recording-option -toDiskSets the given option (
toDisk) to the specified value (true), or unsets the option and restores the target JVM default. The currently supported options are toDisk (boolean), maxAge (seconds), maxSize (bytes), destinationCompressed (boolean), and destinationFile (string).These recording options are local to the client session, not any specific target JVM. In practical terms this means, for example, that setting
recording-option toDisk=truewill cause all subsequentstart,dump, andsnapshotcommands to save recording contents to disk, for all subsequent target JVM connections. -
list targetIdLists recordings in the specified target JVM. The name provided in this list is the name to pass to other commands which operate upon recordings.
-
list-savedLists saved recordings in persistent storage attached to
cryostat. -
list-recording-options targetIdLists recording options which may be set for recordings within the specified target JVM. Not all options are guaranteed to be supported by the client.
-
wait-for targetId fooWaits for the given recording (
foo) of the specified target JVM to stop running. If the recording is continuous and not already stopped then the command will refuse to wait for the recording to complete, since this would lock up the client and require another client to be connected in order to stop the recording. Once this command has begun awaiting completion of the recording it cannot be interrupted.