System::beginObjectTracking Method

Signature beginObjectTracking(fileName: String);

The System class beginObjectTracking method starts recording persistent object activity on the database server.

The information is recorded in a file on the database server node specified by the fileName parameter.

The recorded information distinguishes between read, lock, create, update, delete, and unlock operations.

This does not necessarily record every time an application uses an object, because if the object resides in the persistent object cache, it may not have to be fetched from the database.

Object tracking is terminated by calling the System class endObjectTracking method.

The file is a standard text (.txt) file. The first line is a header record and the last line is a trailer record. The lines in-between represent individual object accesses. In each line, fields are separated by spaces.

The format of the three types of records is similar to that used for node sampling files, documented under "Statistics File Format", later in this chapter.

The format of the header record is shown in the following table.

Field Description
Record type 21 (object tracking header record)
Node instance id Instance id of the database server node
Node type 1 for the database server, 3 for the application server in single user mode, and 5 for standard client in single user mode
Computer name The name of the machine on which the database server node is running
Jade version number In the format major-release-num.minor-release-num.build-num.patch-num; for example, 7.1.03.3
Current date Current date in Julian day format
Current time Current time in milliseconds from midnight UTC
Current UTC bias UTC bias for the location in which the database server node is executing, in minutes
Current date and time Text representation of the date and time
Clock ticks Microseconds elapsed since the database server node was started

The format of the trailer record is shown in the following table.

Field Description
Record type 23 (object tracking trailer record)
Node instance id Instance id of the database server node
Current date Current date in Julian day format
Current time Current time in milliseconds from midnight UTC
Current date and time Text representation of the date and time
Current UTC bias UTC bias for the location in which the database server node is executing, in minutes
Clock ticks Microseconds elapsed since the database server node was started

The format of the data records is shown in the following table.

Field Description
Record type 22 (object tracking data record)
Node instance id Instance id of the node from which the access request initiated
Process number The identifying number of the process making the request
Clock ticks Microseconds elapsed since the database server node was started
Request type 1 for get object, 2 for lock object, 3 for unlock object, 20 for create object, 21 for update object, and 22 for delete object
Class id Class id of the object being accessed
Instance id Instance id of the object being accessed
Parent class id Parent class id of the object being accessed
Sub level Sub-level of the object being accessed
Sub id Sub-id of the object being accessed
Edition Edition of the object being accessed
Process instance id Instance id of the process making the request
Lock type The lock type, which is 1 for shared, 2 for reserved, and 3 for exclusive
Duration The lock duration, which is zero (0) for transaction and 1 for session
Kind The lock kind (transaction or session), which is zero (0) for normal and 2 for a node lock
Millisecond The length of time the lock was held

The following is an example of the data record for the unlocking of a shared lock, transaction duration on object 127.206.5.4.14:2 held by process 187.3 running on node 186.2. The lock was held for at least 15 milliseconds.

22 2 2 169691499 3 127 206 5 4 14 2 3 1 0 0 15

For node locks, the process instance id is that of the background process of the associated node. When a server application unlocks a shared lock on a stable object, the unlock request does not normally appear in the file because only the release of node locks is recorded for stable objects.

The type, duration, kind, and millisecond values are present only for unlock object requests (that is, request type 3).

Only one object tracking session can be active at a time. If the beginObjectTracking method is called when object tracking is already active, exception 1138 (Object tracking is already active) is raised.

Use the beginObjectTracking method judiciously. When object tracking is active, the tracking file can fill very rapidly. You should therefore use object tracking in short bursts.