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.

Query formatting

A query contains the following elements:

  • A query command: checkpoint.
  • 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:

  • flowClass and flowStartMethod are filtering fields - checkpoints that match all of the filtering fields will be returned.
  • flowId and flowStartTimeBefore are reporting fields - only the flowId and flowStartTimeBefore data from each checkpoint will be returned.

Queryable fields

All dates and timestamps must be formatted as per the ISO 8601 standard using the following pattern yyyy-MM-dd'T'HH:mm:ss.SSSZ. For example, 2001-07-04 12:08:56 local time in the U.S. Pacific Time time zone is represented as 2001-07-04T12:08:56.235-07:00.

Field nameDescriptionFormatFiltering or reporting field
flowIdUnique string identifying the flow.StringBoth
flowClassShortened classname of the flow.StringBoth
flowStartTimeBeforeIf 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.TimestampBoth
flowStartTimeAfterIf 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.TimestampBoth
checkpointTimeBeforeIf 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.TimestampBoth
checkpointTimeAfterIf 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.TimestampBoth
platformVersionCorda platform version used to process the flow.Positive IntegerBoth
corDappNameThe name of the CorDapp to which the flow belongs.StringBoth
corDappVersionThe version of the CorDapp to which flow belongs.StringBoth
flowStatusThe status of the flow at the time the checkpoint was createdStringBoth
checkpointCreationReasonThe reason why the checkpoint was created. For example, send or sendAndReceive.StringBoth
pendingPartyThe X.500 name of the party the checkpoint is waiting on. Empty if the checkpoint is not waiting for a party.X.500 stringBoth
flowStartMethodThe method used to start the flow. For example, RPC, SubFlow, Initiated.StringBoth
compatibleIf 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 StringBoth
progressTrackerStepLast known progress tracker step. If there is no known progress tracker step, an empty string will be returned.StringBoth
flowStartContextSpecifies the creator of the flow: RPC user, parent, or initiating flow ID for initiated flows.StringReporting
checkpointSizeThe size of the checkpoint binary, returned as a string.StringReporting
flowParametersThe parameters passed into the flow, returned as a string.StringReporting
callStackThe invocation stack at the time the checkpoint was created, returned as a string.StringReporting
checkpointSeqNumCheckpoint sequence number.Positive IntegerReporting
jsonReturns a long JSON string representing the whole checkpoint.Long JSON stringReporting