Starting the Domino® Diagnostic Probe

The Domino® Diagnostic Probe (DDP) is started from a command prompt and runs as a standalone process, not as a Domino® server process.

Before you begin

You must use the Eclipse OpenJ9 Java™ that comes with Domino®. The probe is not supported with SUN Java™.

CAUTION: You should not restart the Domino® server while the probe is running. The probe must be shut down before restarting the Domino® server, or else certain Domino® processes may hang during shutdown. (These processes would eventually be cleaned up, and an NSD created.)

About this task

The probe uses the identity of the Domino® server and attempts to open a session and a database as specified by the -database [-d] parameter every n seconds as specified by the -polling [-p] parameter. If the time it takes to open the database exceeds the time specified by the -threshold [-t] parameter, then the NSD program is launched to collect diagnostic data. An NSD log file is generated in the domino_data_directory\IBM_TECHNICAL_SUPPORT directory. You can also specify optional parameters for the probe, listed in a table in the following procedure.

Procedure

  1. For each database that you want to monitor using the probe, open the database and select File > Application > Access Control.
  2. In the Access Control List, add and then highlight the Domino® server name and, under Attributes, change the User type to Unspecified. Save the access control list.
  3. To run the probe on Windows™ or UNIX™, make sure the dbopen.jar is present in the Domino® program directory where it is installed by default.
  4. From a command prompt, switch to the directory where the server's NOTES.INI is located (typically the data directory on UNIX™ and the program directory on Windows™). Start the probe from a command prompt using the syntax example provided in the table.
    Table 1. Commands for Domino® Diagnostic Probe on windows and UNIX™
    Platform Command syntax
    Windows™ jvm\bin\java -jar dbopen.jar -d mail\domprobe.nsf -t 3 -p 30 -nsdoptions "-nomemcheck" -outfile C:\Domino\data\IBM_TECHNICAL_SUPPORT\DomPerfMon.txt
    Note: If you use Windows™ 2008, set Run this program as an administrator on the Compatibility tab in the file properties for jvm/bin/java.exe.
    UNIX™ (in data directory) /opt/ibm/lotus/bin/java -jar /opt/ibm/lotus/bin/dbopen.jar -d mail/domprobe.nsf -t 3 -polling 45 -nsdoptions "-stacks" -outfile domperfmon.log
    Note: UNIX™ and IBM® i platform command examples are case-sensitive. The probe will connect to the server by name.
  5. To run the probe on IBM i, perform the following steps to use QShell (STRQSH).
    Note: UNIX™ and IBM® i platform command examples are case sensitive. The probe will connect to the server by name. On IBM® i, use the command Configure TCP/IP (CFGTCP) and select Work with TCP/IP host table entries (Option 10) to display the host table. Use Add TCP/IP Host Table Entry (ADDTCPHTE) to add the server name and IP@ to the host table if needed.
    1. Start QShell using the following RUNDOMCMD command, replacing servername with the name of the Domino® server: RUNDOMCMD SERVER(servername) CMD(STRQSH) BATCH(*NO)
    2. Change to the server's data directory (for example, cd /domino/data)
    3. Start the probe using the following command, entered as one line, and replacing filename.nsf with the file name of the database being evaulated: /QOpenSys/usr/bin/java -Djava.library.path=/QIBM/ProdData/LOTUS/domino100001 -jar /QIBM/ProdData/LOTUS/domino100001/dbopen.jar -database mail/filename.nsf
  6. Optional: Include any desired optional parameters for the probe. All parameters listed in the following table are optional except for the -database [-d] parameter.
    Table 2. Options for the Domino® Diagnostic Probe utility
    Parameter Default Purpose
    -database [-d] (required) none Database to open; for example, mail/test.nsf
    -threshold [-t] 30 Run NSD if the database open takes longer than threshold. Value in seconds.
    -polling [-p] 60 The frequency the database is polled to open in seconds.
    -nsdoptions ALL Options to pass to NSD. Must be in quotes; for example, "-nomecheck -stacks" The default "ALL" will run all of the following commands: DUMP, MEMCHECK, PERF, HANDLES, WALKMEM, and PS.

    Type nsd -help to see all available NSD parameters.
    -outfile none Prints output to the specified log file, for example, c:\temp\DDPlog.txt, and to the display. The file name must be surrounded by quotes if the file path contains 'space' character(s). If the path is not specified, the file will be created in the Domino® program directory. If an existing log file is specified on subsequent runs, the output is appended to the log file.
    -help - Displays help text.

Results

The Domino® server console will show sessions opened and closed by the server (one session opened by the server for each polling cycle - the previous session will be closed on the Domino® server each time a new session is opened.) The output of the probe will print to the local command window and also a log file (if specified). If the database open exceeds the specified threshold, an NSD is created. Once the NSD completes, you'll see a message indicating that it is done and then logging will resume.

Example

Example of Domino server console output for the diagnostic probe session:

07/12/2010 04:45:48 PM  Opened session for vlap2/vTest (Release 8.5.2 [Build 379])
07/12/2010 04:45:48 PM  Closed session for vlap2/vTest Databases accessed:     1   Documents read:     0   Documents written:     0 
07/12/2010 04:45:49 PM  Opened session for vlap2/vTest (Release 8.5.2 [Build 379])
07/12/2010 04:45:49 PM  Closed session for vlap2/vTest Databases accessed:     1   Documents read:     0   Documents written:     0
07/12/2010 04:45:54 PM  Opened session for vlap2/vTest (Release 8.5.2 [Build 379])    
07/12/2010 04:45:54 PM  Closed session for vlap2/vTest Databases accessed:     1   Documents read:     0   Documents written:    0
07/12/2010 04:45:59 PM  Opened session for vlap2/vTest (Release 8.5.2 [Build 379])

07/12/2010 04:45:59 PM  Closed session for vlap2/vTest Databases accessed:     1   Documents read:     0   Documents written:     0
Note: Any session for the probe will be closed when the probe is shut down. The end of the session occurs when the probe issues the following message: Shut down complete.

Example of command prompt activity for a DDP session:

[C:\Domino] jvm\bin\java -jar dbopen.jar -d mail\domprobe.nsf -threshold 3 -polling 45 -nsdoptions "-nomemcheck" -outfile C:\Domino\data\IBM_TECHNICAL_SUPPORT\perfmon.txt
11/09/2009 5:46:10 AM Opening database mail\domprobe.nsf has taken 3.001 seconds. This exceeds the set threshold of 3.0 seconds.

The DB open exceeded the threshold of 3 seconds so NSD was kicked off immediately.

11/09/2009 5:46:10 AM Running NSD...

NSD being created.

11/09/2009 5:47:44 AM NSD completed with exit status 0

NSD completed.

11/09/2009 5:47:45 AM Opening database mail\domprobe.nsf took a total of 4.001 seconds

With the NSD done, DDP records the total time of the database open, in this case, 4.001 seconds. The NSD captured the state of the server at the time of the delayed DB open (at 3.001 seconds).

11/09/2009 5:48:33 AM Opening database mail\domprobe.nsf has taken 3.001 seconds. This exceeds the set threshold of 3.0 seconds.
11/09/2009 5:48:33 AM Running NSD...
11/09/2009 5:48:59 AM NSD completed with exit status 0
11/09/2009 5:49:00 AM Opening database mail\domprobe.nsf took a total of 5.354 seconds

This DB open took 5.354 seconds.

...
Quit

The administrator issued a quit commmand to stop the probe. You must use quit to stop the probe.

11/09/2009 5:51:42 AM Shut down in progress...

Shut down of the probe begins.

11/09/2009 05:52:18 AM Shut down complete.
 Shut down of probe is complete. It can take several minutes to complete shut down if an NSD is in progress.