Using debugging variables

Improving system performance is always a topic that generates a lot of questions, and we have addressed some NOTES.INI settings related to performance in recent articles. We know, though, that one of the best ways to improve performance is by debugging your applications to figure out why some actions take so long while others take practically no time at all. So this month, we take a look at some of the NOTES.INI settings related to debugging.

Some important caveats
Before we talk about specific debugging variables, it's important to note that these variables are generally intended for short-term, internal Notes/Domino development use only. This is the primary reason that they are generally undocumented. Remember, even if you're an experienced Notes user, you should modify NOTES.INI only when necessary and only if there is no other way to accomplish what you're trying to do—for example, by setting a preference within Notes. We strongly recommend that you never work with undocumented variables unless under the direction of Lotus Support.

Also note that, for servers, the safest way to modify the NOTES.INI file is through the NOTES.INI Settings tab in the Server Configuration document of the Domino Directory. This method lets you add or change variables in the server's NOTES.INI file without having to open and edit the file itself, which could be dangerous if some or all of the file is accidentally changed or deleted. If you do choose to edit the file directly, be sure to create a backup copy you can restore if something goes wrong.

That said, let's look at some NOTES.INI debugging-type variables.

Debug_Outfile
The Debug_Outfile setting allows you to create a more complete debugging log by capturing information sent to the server console. Its syntax is:

Debug_Outfile=filename

Depending on what type of problem your server is experiencing, you use the Debug_Outfile parameter in conjunction with appropriate debugging parameters. For example, if you are having semaphore timeout issues, you would want to turn on semaphore debugging:

Debug_ThreadID=1
Debug_Capture_Timeout=1
Debug_Show_Timeout=1

Adding these parameters to NOTES.INI results in additional information being sent to the server console, but not to the Notes log file (log.nsf). To capture a history of what appears on the console, you need to add the Debug_Outfile parameter to NOTES.INI, as in the following example:

Debug_Outfile=C:\TEMP\DEBUG.TXT
Debug_ThreadID=1
Debug_Capture_Timeout=1
Debug_Show_Timeout=1

Note that Debug_Outfile can be at either the beginning of your debugging parameters or at the end; it is important, however, to insert a carriage return after the last NOTES.INI entry.

When you specify the path for the debug file in Debug_Outfile, the directory must already exist; Notes will not automatically create the directory for you. Also, it is strongly recommended that the Debug_Outfile parameter be configured to save the log file in a location that is isolated from the partition where the operating system, Domino server, and other applications may potentially create files that are necessary for those programs to function correctly (for example, SWAP files, data files, and so on). Placing the log file on an isolated partition avoids any potential problems.

When the log file is placed on an isolated partition not being used by any currently running applications, if that partition runs out of disk space, the Domino server will stop logging to the file specified in the Debug_Outfile parameter. With no disk space to write the log file to, the Domino server's overall performance is not affected and it continues to function. If some hard drive space is cleared, the server will continue to add entries to the log file specified in the Debug_Outfile parameter. Be aware that this log file may grow significantly in size over a period of time on a Domino server that has a high rate of activity. The log file cannot be deleted while the Domino server is running; if an attempt is made to delete the file, a sharing violation will occur.

Once the Debug_Outfile parameter has been added to the NOTES.INI file, the Domino server must be shut down and restarted for logging to begin. Also be aware that, even though the Domino server has been restarted, the log will not be written if the server's Notes client has been left running.

Debug_Directory_Assistance and Debug_NameLookup
When using Directory Assistance, including LDAP (which is configured to use a Master Address Book), you can add the following lines in the NOTES.INI file of the server that is using Directory Assistance, in order to supply more than the usual amount of information:

Debug_Directory_Assistance=1
Debug_NameLookup=1

Remember to add the Debug_Outfile parameter to capture the data. We recommend that these parameters be run separately to make the data easier to view.

Note: When these parameters are placed within the server's NOTES.INI file, the server must be cycled for the changes to take effect.

Debug_AdminP
The Debug_AdminP setting lists AdminP schedule information. When Debug_AdminP=1, AdminP will dump out its schedule information every time the schedule is updated.

Remember, you will also need to provide the Debug_Outfile parameter to capture a history of what appears on the console. The Debug_AdminP setting is only available on R5 servers.

Debug_Repl_All
Debug_Repl_All allows you to view the order (or sequence) in which documents are replicated in a Notes database. When there is no sort order in a view column in a Notes database, documents are sorted/replicated in order of NoteID.

Debug_Repl_All=1 gives information for each document that is replicated, for example:

10-12-94 08:43:19 AM REPLICA: Updating NoteID 0x216E in Discuss.nsf
10-12-94 08:43:19 AM REPLICA: Deleting NoteID 0x2162 in Discuss.nsf

Debug_Repl_All=2 provides information for each document that is not replicating, for example:

10-12-94 05:31:00 AM REPLICA: ...Skipping note in Destination list (UNID OFCCADF6EB:E1B3F184-ON852560A6:OF2867N9P3)
10-12-94 05:31:00 AM REPLICA: ...(Con't) Destination has same or newer note. Src Time/SeqNo=10-11-94 05:31:00 AM
10-12-94 05:31:00 AM REPLICA: ...Skipping note in Destination list (UNID OF282B7FF5:B72B7102-ON852560A6:OF2867N9P3)

Either Debug_Repl_All setting lets you see the order of replication. (Note that this order will be different in every replica copy of the database.) Remember to use Debug_Outfile to display the list of documents.

Debug_Btree_Errors
The Debug_Btree_Errors setting was enabled as a default NOTES.INI setting in release 5.0.5 to capture additional information when Btree corruption occurs. The intent was to obtain relevant information when Btree corruption occurred instead of having to set it and wait for the issue to occur again. Although this parameter has not been put into the NOTES.INI file on a fresh install of 5.0.6a or later, if a customer previously installed 5.0.5 and does an incremental upgrade to 5.0.6a or later, the setting will remain.

The Debug_Btree_Errors=1 setting displays Btree error messages on the server console. If there is a significant time lapse between a Btree error being detected and the user noticing the error message on the console (as may happen if the error occurs overnight), the only troubleshooting information available is the current error message on the console.

Note: If the Debug_Btree_Errors parameter is in your NOTES.INI file, you may want to remove it. When this parameter is enabled (set to 1), you may receive a large number of Btree error messages displayed on the server console. In many cases, these Btree errors are informational only, and you will not need to capture additional information about them.

Debug_FTV_Search
You can use the setting Debug_FTV_Search=1 to capture an end-user's keyword searches. If you want to capture the searches on a server database, use the server's NOTES.INI file; to capture the searches on a local database, use the Notes client's NOTES.INI file. Remember to use Debug_Outfile to properly capture the information.

Here is an example of the output from Debug_FTV_Search:

API handle obtained in 49 ms.
Query: (TIME)
Verity Query: (<MANY><STEM>`TIME`)
Setup for retrieval in 43 ms.
Retrieval performed in 7 ms. 7 documents found
Built result tables (incl. refinement) in 2 ms. 6 documents Left
Total search time 101 ms.

Debug_AMGR
Debug_AMGR is a setting that allows the Domino server to report Agent Manager (AMGR) activities. As of the Domino 4.6.1 server, the server will also record AMGR activity for databases that do not contain agents, when those databases have new documents added to them, existing documents are modified, or new mail is delivered to them.

Keep in mind that it is the activity itself that AMGR is reporting; it is not necessarily reporting that an agent will be executed as a result of an activity. So even if there are no agents in the database, AMGR may report that an activity occurred in that database.

The following table describes which Debug_AMGR flags can be set:

Flag	Description
c	To output agent control parameters
e	To output information about Agent Manager events (new in 4.6.1)
l	To output agent loading reports
m	To output agent memory warnings
p	To output agent performance statistics
r	To output agent execution reports
s	To output information about AMGR scheduling
v	Verbose mode, which outputs more messages about agent loading, scheduling, and queues
*	To output all of the above

The NOTES.INI setting Debug_AMGR=* will generate a large amount of extraneous information. Therefore, to limit the amount of information returned by AMGR, do not use the * (asterisk) flag. Instead, use only the flag that you need for troubleshooting.


Do you have a NOTES.INI questions? Send it in to Professor INI. We'll answer as many questions as we can in future "Ask Professor INI" columns. Keep in mind, however, that we may not be able to answer every question, nor can we quickly respond to requests that require immediate attention. If you need an immediate response to a question, we recommend you post it in the Iris Cafe Notes/Domino Gold Release Forum where someone from the general Notes community might be able to help, or contact Lotus Customer Support.