Querying flow data
You can query a node to retrieve flow checkpoint data that can be useful for troubleshooting flows.
A checkpoint is a record of flow data taken at key points during a flow’s operation, typically whenever the flow is suspended and waiting for a response or message.
To query the node for flow data, you must use the Corda Shell.
A query contains the following elements:
- A query command:
- Filtering fields:
queryBy <fields>. Filtering fields define what checkpoints are returned by the query.
- Reporting fields:
reportBy <fields>. Reporting fields define what data is returned from each returned checkpoint.
A complete query might look like this:
checkpoint queryBy flowClass=CashIssueAndPaymentFlow,flowStartMethod=RPC reportBy flowId,flowStartTimeBefore
In this example:
flowStartMethodare filtering fields - checkpoints that match all of the filtering fields will be returned.
flowStartTimeBeforeare reporting fields - only the
flowStartTimeBeforedata from each checkpoint will be returned.
jsonfields can only be used as reporting fields.
All dates and timestamps must be formatted as per the
ISO 8601 standard using the following pattern
For example, 2001-07-04 12:08:56 local time in the U.S. Pacific Time time zone is represented as
|Field name||Description||Format||Filtering or reporting field|
|flowId||Unique string identifying the flow.||String||Both|
|flowClass||Shortened classname of the flow.||String||Both|
|flowStartTimeBefore||If used as a filtering field, returns all flows started before the given time. If used as a reporting field, returns the exact time when the flow was started.||Timestamp||Both|
|flowStartTimeAfter||If used as a filtering field, returns all flows started after the given time. If used as a reporting field, returns the exact time when the flow was started.||Timestamp||Both|
|checkpointTimeBefore||If used as a filtering field, returns all checkpoints created before the given time. If used as a reporting field, returns the exact time when the checkpoint was created.||Timestamp||Both|
|checkpointTimeAfter||If used as a filtering field, returns all checkpoints created after the given time. If used as a reporting field, returns the exact time when the checkpoint was created.||Timestamp||Both|
|platformVersion||Corda platform version used to process the flow.||Positive Integer||Both|
|corDappName||The name of the CorDapp to which the flow belongs.||String||Both|
|corDappVersion||The version of the CorDapp to which flow belongs.||String||Both|
|flowStatus||The status of the flow at the time the checkpoint was created||String||Both|
|checkpointCreationReason||The reason why the checkpoint was created. For example, ||String||Both|
|pendingParty||The X.500 name of the party the checkpoint is waiting on. Empty if the checkpoint is not waiting for a party.||X.500 string||Both|
|flowStartMethod||The method used to start the flow. For example, RPC, SubFlow, Initiated.||String||Both|
|compatible||If used as a filtering field, returns compatible or incompatible checkpoints. If used as a reporting field, returns the compatibility of returned checkpoints as a boolean.||Boolean String||Both|
|progressTrackerStep||Last known progress tracker step. If there is no known progress tracker step, an empty string will be returned.||String||Both|
|flowStartContext||Specifies the creator of the flow: RPC user, parent, or initiating flow ID for initiated flows.||String||Reporting|
|checkpointSize||The size of the checkpoint binary, returned as a string.||String||Reporting|
|flowParameters||The parameters passed into the flow, returned as a string.||String||Reporting|
|callStack||The invocation stack at the time the checkpoint was created, returned as a string.||String||Reporting|
|checkpointSeqNum||Checkpoint sequence number.||Positive Integer||Reporting|
|json||Returns a long JSON string representing the whole checkpoint.||Long JSON string||Reporting|