cxDBprof.exe knows 5 command line parameters. Everything is optional, so the program can also be started without a parameter. The parameters can be indicated in any order. There are the following parameters:
cxDBprof.exe -HServer-Hostname -TTerminalServer-Hostname -DDatabase -LLogging.ini -S[Interval]
Information:
The parameter values have to be written directly behind the parameter name.
For example "-LC:\Temp\Logging.ini".
If the parameter "-S" has been indicated, the (cumulated) server statistics are
started immediately. Therefore it doesn't need to be started via menu. The
interval (in milliseconds) has to indicated as a number and is optional. For
example "-S60000" for a minute. Default is 200. Parameter "-D"
(database) needs to contain the complete database path. This can be a UNC
path if the database is on another computer (e.g. "\\Server\Freigabe\Classix\Projects\classix.cxd").
Activating TerminalServer Support
To execute the assignment between client name and TerminalServer with a running ClassiX® application, the TerminalServer needs to be registered first. This - and with it the name assignment - is only possible if a TerminalServer server version had been installed on the computer with ProfServ.
A TerminalServer can be registered via menu item "View/TerminalServer options". TerminalServer are added here (button "Add") or deleted (button "Del").
During adding process, two other options will be queried: TerminalServers type (Windows TerminalServer, Citrix meta frame or automatic identification) and hostname. If the indicated computer gets identified as a TerminalServer, it will appear in the list.
Comment: Due to a missing documentation, Citrix does not get supported, yet!
Server Display
Under "File", it is possible to establish a connection to DB servers and to clients which access the database. The server dynamically displays the client states of all clients who are currently accessing the server. To open a server display, please select "File/Connection to DB Server". Now, the server name will be entered into the field "DB-Server". The server name can be entered as a pure host name (such as "CL"), as a complete FQDN (Fully Qualified Domain Name) (such as "CL.CX.DE") or as an IP address (such as 192.168.1.34). The resolve button tries to resolve the name.
Additionally, it is possible to define query speed and database. Segment names that are required in the client view (see below) to display locking conflicts are exported from the database specification. These specifications can be changed later with the DB server options. The database specification can either be a locally accessible file name (from the server as well as from the DBProf computer) or the server database path (<server name>:<local path>, meaning the path locally from server perspective).
The overview checkbox also opens next to the window with all access details (next screenshot) an overview, which displays all active clients with their status and locking conflicts - especially locking pattern - are highlighted in a different colour.
Overview
The overview window title displays the according database server. If possible, the clients are listed in the server window by name, otherwise by IP address or process ID. The following states are possible:
|
Without Status |
The client currently causes no database activity and has no open server transaction. A client transaction (it is only known in the cache manager) can still be open. |
|
Idle (Txn Open) |
The client currently causes no database activity, but there is an open transaction in the server. |
|
Working |
The client currently causes database activity. It has locks for at least one database object. The work that has been caused by the client will be displayed and so will the time that it has taken so far. |
|
Dead |
The client is involved in a deadlock. |
|
Wait... |
The client waits for the assignment to a lock, which is currently stopped by another application. Further information refers to the fact, whether the client wants to have the lock for reading (R) or writing (W) and whether a lock should be taken for a certain area inside a segment (range, normal case), for a complete segment or for the entire database. |
Colours are additionally used to display locking clusters. If for example client A is waiting for client B and client B for client C, then A, B and C are displayed in the same colour. If now client D is waiting for client E, D and E will be displayed in another colour.
Since data can change really fast, it is possible to freeze the display. This happens via stop button in the toolbar or via menu "Edit/Stop". The display comes alive again via "Run" button or via menu "Edit/Start". This setting affects the collection process and the client display.
Detail Display
Server window with 2 active and one dead client
The server window title displays the equivalent database server and the number of connected clients. The clients are listed - if possible - by name, otherwise by IP address. For each client, a number of details will be displayed (see image). The displayed values are cumulated values since the client has logged into the database server. Therefore not cumulated values since cxBDProf start. Double-clicking the client name navigates to the Client Display.
At the start, the list contains only active clients. When a client logs off, their list entry will be highlighted in grey. By clicking on "Delete dead clients" (red "X") the inactive (dead) clients can be deleted from the list.
If a client has to wait for one (or more) clients (Locking), their list entry needs to be highlighted in red and the column "Locking Conflict with" lists all client(s) which the client has to be waiting for.
Client Display
The client display will be opened with "File/Connection to Client". Please enter the name of the monitored client computer into the field "Client". The resolve button is equivalent to the field "DB Server" for the server display (see above).
The "maximum depth" is currently not considered, but later, it defines that InstantView® commands are displayed only up to a specified nesting depth.
Under "Server Infos", it is listed which DB server the client accesses. The field "DB Server" is only activated, when status information is supposed to be taken from the DB server.
The client display is divided into two. In the middle of the window, there is a slider, which can be dragged left and right. If the client remote profiling has been activated, the InstantView® profile statements will be displayed on the left side.
The server displays the extended status information on the right side, in case it has been selected in the client option. The lock entries would be the most interesting displays. For a better understanding: "Read lock" doesn't mean, that an application contains a read lock. Instead it waits for a read-lock. Read- and write-locks contain an application in the working segments.
In the example (image below), an application on the computer CL.CX.DE waits for a read lock for segment 1080 ("salesOrderSlaveS"). The area starts with sector 104 and goes on for 8 sectors. There can be no read lock, because an application on MOBIL2.CX.DE has aleready locked one of the objects in this area with a higher priority.
There is an InstantView® application, which can - based on this information - display all objects inside the indicated area (also see "Display objects that are causing a locking conflict").
In case "unknown" gets displayed instead of a segment name, the database needs to get introduced to the DB server display via menu item "Display/DB server options". Now, the database segments can be loaded (see server display).
Logging
Statistic data about the server and all clients can be kept in a log file. The same applies to locking conflicts. At first, a configuration file needs to be generated:
log4cplus.rootLogger=INFO, FILE_LOGGER
log4cplus.appender.FILE_LOGGER=log4cplus::RollingFileAppender
log4cplus.appender.FILE_LOGGER.MaxFileSize=1MB
log4cplus.appender.FILE_LOGGER.MaxBackupIndex=1
log4cplus.appender.FILE_LOGGER.File=cxdbprof.log
log4cplus.appender.FILE_LOGGER.ImmediateFlush=true
log4cplus.appender.FILE_LOGGER.Append=true
log4cplus.appender.FILE_LOGGER.layout=log4cplus::PatternLayout
log4cplus.appender.FILE_LOGGER.layout.ConversionPattern=%D{%Y-%m-%d %H:%M:%S,%%q} %5p %c - %m%n
log4cplus.logger.cxdbprof=INFOThe file name might need to be indicated here (relative to the current directory). Environment variables can be accessed above ${VARIABLE}, absolute paths are certainly possible too.
cxDBprof records events of three different categories:
| Category | Meaning | Example |
|---|---|---|
| cxdbprof.main | start and end | ClassiX profile server 1.35 started ClassiX profile server terminated |
| cxdbprof.stat | statistics | see below |
| cxdbprof.lock | locking conflict | see below |
Statistic data via server or client are written into the protocol after something has changed:
2006-05-11 15:37:59,762 INFO cxdbprof.stat - ; client, clientID, time, receive_msgs, callback_msgs, KB_read, KB_written, commit, readonly_commit, abort,lock_timeouts, lock_waits, deadlocks, total_lock_wait_time [,propagations, KB_propagated, KB_direct]
2006-05-11 15:38:08,762 INFO cxdbprof.stat - . 9 84 0 276 0 0 1 0 0 0 0 0 0 0 0
2006-05-11 15:38:09,762 INFO cxdbprof.stat - . 10 2 0 0 0 0 0 0 0 0 0 0 0 0 0
2006-05-11 15:38:12,980 INFO cxdbprof.stat - . 13 792 0 1267 0 0 5 0 0 0 0 0 0 0 0
2006-05-11 15:38:13,980 INFO cxdbprof.stat - md 231 14 792 0 1267 0 0 5 0 0 0 0 0
2006-05-11 15:38:13,980 INFO cxdbprof.stat - . 14 65 0 247 0 0 1 0 0 0 0 0 0 0 0
2006-05-11 15:38:14,980 INFO cxdbprof.stat - md 231 15 64 0 247 0 0 1 0 0 0 0 0The first line describes single data fields. In the log file, they are separated via tabulator character.
| Data Field | Description |
|---|---|
| client | client name; full stop represents the server |
| clientID | ID, which gets assigned to each client by the ObjectStore server. Not to be mistaken for the process ID! |
| time | Since program start (by cxDBprof) passed time in seconds |
| receive_msgs | Number of messages which the server has received by the clients. A message can be a request for an action, such as DB opening, getting a page, DB updating, transaction execution, transaction abort, DB closing as well as other things. The number indicates, how often clients communicate with the server. That way, the server requirements are low if the number is small. |
| callback_msgs | Number of call-back messages that the
server sends to the client. A call-back message is a message, which gets
sent from the server to client A, whenever client B requests page data that
has been cached by client A. In case the number is high, this means that an application often wants to write on data, which other clients will read or write on. |
| KB_read |
Number of kilobytes of data which the server has sent
to clients for reading.
Monitor this statistic to help determine whether you need to enlarge
client cache files. Compare kilobytes read for a given client with the
number of commits and the size of the client cache file.
|
| KB_written |
Number of kilobytes of modified data that the clients sent to the server.
Written data is data involved in a commit. It must be buffered, and it
is logged if it cannot go directly to a database because it is not being
written past the current end of a cluster. When analysis is concerned
with the number of transactions per second, the number of kilobytes
written is an important factor.
|
| commit | Number of commits (completed R/W
transaction) known by the server. In case a client doesn't change data
during a transaction, the client eventually doesn't inform the server, that
a transaction has been completed. With this number, it is possible to calculate the number of transactions per second. |
| readonly_commit | Number of read-only commits:
Executed transactions which have not been involved in data modifications. The client usually doesn't inform the server about such commits. Therefore the number should stay small. Read-only commits are similar to simple aborts and don't take much time? |
| abort | Number of cancelled transactions recorded
by the the server. If the client has sent no message to the server, it can
cancel a transaction without informing the server. Does ClassiX® cancel transactions only because of lock conflicts? (Timeouts?) |
| lock_timeouts | Number of lock timeouts:
Number of all client attempts to lock a page that has
already been locked, since the defined waiting time has already run out.
|
| lock_waits | Number of blockades that did not lead to
a timeout Number of all client attempts to lock a page that has already been locked by another client. Next to the lock waits the average waiting time for a lock is indicated in parenthesis. (ObjectStore divides the the entire time by the number of lock waits). |
| deadlocks | Number of Deadlocks Amount of times that the server declares a client for a as a deadlock "victim" and recognizes that it needs to end a single transaction, so other clients can complete their transaction. |
| total_lock_wait_time | waiting time for locks, cumulated (in msec) |
Events such as deadlocks or blockades (reading operation blocks writing operation and vice versa) are blocked as well:
2006-05-11 14:37:35,740 INFO cxdbprof.lock - md_219_md (564)_205_Segment 32
2006-05-11 14:37:35,740 INFO cxdbprof.lock - md_207_md (564)_205_Segment 32
2006-05-11 15:39:11,245 INFO cxdbprof.lock - md_234_md (2148)_233_md (1868)_231_Segment 32The single columns are separated via tabulator sign (represented in the example via _).
In the first example, a writing client (md
205) blocks two reading clients (md 219 and md 207). In the second example two
reading clients (md 233 and md 231) block a writing client (md 234).
Reading from left to right: Client xxx gets blocked by client(s) yyy
(and zzz and ...) in segment abc. The number in parenthesis is the process
number, the number right from the client name is the ObjectStore client ID.