The examine command lets you view different data types produced by various streams.
The examination commands, which work only when Event Stream Processor is paused, lets you view different datatypes produced by various streams.
The examination commands return the records in the same format used to send updates to common subscribers. The esp_client command generates records in XML format. The operation types that occur in examined data include the standard types seen by the normal subscribers, and the types that are used exclusively inside Event Stream Processor.
There are two ways in which records returned by the examination commands may be grouped:
If a stream employs an input window, as this windows fills, it begins generating SAFEDELETEs for the earlier records. To distinguish these records from the DELETEs sent by the input streams, esp_client includes the pseudo-field ESP_RETENTION=1 in each record.
These arguments choose the data to be examined:
| Argument | Function |
|---|---|
| kind | Determines the kind of data to be examined. |
| stream | Specifies the stream from which the data is taken. To receive data from all streams, leave this field empty. |
| object | Selects the particular data unit. Use this if there are many units of this kind of data (for example, variables). |
Either the stream, data, or both can be left empty or omitted if it is not applicable to the kind of data requested in the examine command. The kind and stream must match: you cannot request data across the Event Stream Processor from a stream, and you cannot request per-stream data unless you specify a stream.
Some kinds of data are only available from certain streams. For example, the pattern state can be read only from a pattern stream. If the requested kind of data is not available for a certain stream, the error No such kind of data is returned, even if that kind of data is supported for other streams.
Some kinds of data can be used both with and without the stream argument. For example, you can use “var” without a stream to examine global variables, and with a stream to examine that stream's variables.
The groups of data related to the input queues are heterogeneous. Each record receives a tag matching the name of the stream that produced it (records produced from source streams receive tags with the name of the source stream itself). These include: queue, inTrans, inRow, queueHead, queueTail, inHist, lastInTrans, inHistEarliest, and inHistLatest.
There are also groupings of historic data that contain a mix of input and output data. Each of these groups contains one or more pairs of transactions: the first record in each pair is an input transaction, and the second record is the matching output transaction. Each input transaction record is tagged with the name of the stream that produced it; each output transaction record gets the tag currow. If any input stream records are also tagged with row, you can distinguish by looking at the order in which they appear.
Certain kinds of data deal with history, such as the input transactions processed and outputs produced. You can obtain these data sets separately (as input history and output history) or in a combined data set. When the input and output history are examined separately, the transactions are matched by their index: the first input transaction matches the first output transaction, and so on.
The amount of historical data kept for a stream is determined by the stream's history size setting. This setting can be set globally for all streams, or set for individual streams, using the esp_client command history. The default history size limit is 100 transactions. Using large history limits increases the memory usage of the Event Stream Processor.
If trace mode is off, all history is discarded, but the limit is kept. The next time trace mode is enabled, the history begins collecting again.
A record returned by the examine command should be stored in an empty placeholder. If there is no ambiguity with transaction boundaries (such as with outTrans), esp_client returns no data. In other cases, such as hist, a placeholder shows that the transaction occurred, but produced no output. A placeholder record includes all fields, including the key fields; the value of each is set to NULL.
Some types of data records use natural field names. Records, such as "pause", return metadata: the field names in this type of record are defined in the Event Stream Processor. Other types contain a mix of fields defined by the user and added by Event Stream Processor. In this type of record, the fields added by Event Stream Processor have the prefix ESP_. Do not use this prefix for user-defined fields.