Reading Event Data
Event data in AIX® Event Infrastructure consists of keyword-value pairs.
Event data may only be read once and no more than one event occurrence worth of data will be returned in a single read() call. For example, say that two events have occurred before the consumer reads from the monitor file and each event has 256 bytes worth of data. If the consumer calls read() for 4096 bytes, only the 256 bytes of the first event will be returned to the user. A second read() call will need to be performed to obtain the data from the second event. Any offset given will be ignored and data will be read starting from the last unread byte.
Event data will be at the most 4096 bytes, although most events will be much smaller ( < 512 bytes). It is recommended that when reading events, a large enough buffer should be used so as to avoid only reading part of an event.
Event data in AHAFS consists of keyword = value pairs, with the exception of BUF_WRAP, EVENT_OVERFLOW, BEGIN_EVENT_INFO, END_EVENT_INFO, BEGIN_EVPROD_INFO, END_EVPROD_INFO and STACK_TRACE which are special keywords without any values. Here are the keywords you may see in event data:
| Key | Value | Details |
|---|---|---|
| BUF_WRAP | None | The consumer buffer is handled like a circular buffer. If any unread data is overwritten by the latest event data, this keyword will be the next string returned by the read() call even if the consumer has partially read the previous entry. The subsequent call to read() will return the next whole event. |
| EVENT_OVERFLOW | None | If the event data is too large to fit inside the consumer's event data buffer, this keyword will be returned from the first read(). A subsequent read() will return what event data was able to fit inside the buffer. Note: If EVENT_OVERFLOW is
encountered, the end string END_EVENT_INFO will not be present.
|
| BEGIN_EVENT_INFO | None | This keyword signifies the beginning of the data for an event occurrence. |
| END_EVENT_INFO | None | This keyword signifies the end of the data for this specific event occurrence. |
| TIME_tvsec TIME_tvnsec | Integer | These two fields record the timestamp of the event occurrence as seconds and nano-seconds since the Epoch. |
| SEQUENCE_NUM | Integer | This field records the number of times the event has occurred since the first successful select() or blocking read(). This number is reset to 0 if the select() or blocking read() call fails, or if the consumer ceases to monitor the event (through overwriting of the event monitoring specifications, or through reaching an event occurrence count equal to the NOTIFY_CNT specified). |
| PID | Integer | Process ID of the process which triggered the event occurrence. Only available with an event producer who has specified the AHAFS_STKTRACE_AVAILABLE capability, but not the AHAFS_CALLBACK_INTRCNTX capability. |
| UID | Integer | Effective user ID of the user who triggered the event occurrence. Only available with an event producer who has specified the AHAFS_STKTRACE_AVAILABLE capability, but not the AHAFS_CALLBACK_INTRCNTX capability. |
| UID_LOGIN | Integer | Login user ID of the user who triggered the event occurrence. Only available with an event producer who has specified the AHAFS_STKTRACE_AVAILABLE capability, but not the AHAFS_CALLBACK_INTRCNTX capability. |
| GID | Integer | Effective group ID of the user who triggered the event occurrence. Only available with an event producer who has specified the AHAFS_STKTRACE_AVAILABLE capability, but not the AHAFS_CALLBACK_INTRCNTX capability. |
| PROG_NAME | String | Name of the process which triggered the event occurrence. Only available with an event producer who has specified the AHAFS_STKTRACE_AVAILABLE capability, but not the AHAFS_CALLBACK_INTRCNTX capability. |
| CURRENT_VALUE | 64 bit unsigned integer, in decimal | This key is only for AHAFS_THRESHOLD_VALUE event producers and will return the current value of the event at the time the event occurrence was detected. Note that due to delay between the time a process is notified and the time they read the event data, the actual current value of the event may have changed. |
| RC_FROM_EVPROD | 32 bit integer, in decimal | This return code comes from the event producer either as the result of an error when trying to set up the event, or as the result of an event occurrence. Generally, return codes less than 256 indicate an error when attempting to register the event with the event producer. Some event producers will return codes greater than 256 to provide more information about the event occurrence. These return codes are documented in sys/ahafs_evProds.h |
| BEGIN_EVPROD_INFO END_EVPROD_INFO | String* | These two keywords mark the beginning and end of the string returned by the event producer. There will always be a newline after BEGIN_EVPROD_INFO and before END_EVPROD_INFO. For consumers who have specified CLUSTER=YES, this is where node information will be given. |
| STACK_TRACE | String* | For consumers who have specified INFO_LVL=3 with an event producer who has specified the AHAFS_STKTRACE_AVAILABLE capability, but not the AHAFS_CALLBACK_INTRCNTX capability, the stack trace of the event occurrence will be provided. The keyword STACK_TRACE indicates that the remaining event data, until the string END_EVENT_INFO is the stack of the event occurrence. |
| NUM_EVDROPS_INTRCNTX | Integer | This keyword represents the number of interrupt-context event occurrences that are dropped since the time that is specified by the TIME0_tvsec and TIME0_tvnsec keywords in the report. The event occurrences are dropped only when the frequency of the event occurrence is high. |
| TIME0_tvsec TIME0_tvnsec |
Integer | These keywords record the time stamp of the first event-occurrence drop in seconds and nano-seconds since the Epoch. These keywords are reported along with the NUM_EVDROPS_INTRCNTX keyword. |