Turning Up Tracing

Introduction

The Cisco Intelligent Contact Management (ICM) Event Management System (EMS) provides an application program interface (API) for ICM processes to use in order to report events. This document discusses how to turn up tracing in order to help troubleshoot issues in Cisco ICM.

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

• Cisco ICM

• Microsoft Windows NT version 4 and Windows 2000

Components Used

The information in this document is based on these software and hardware versions:

• Cisco ICM version 4.6.2 and later

• Microsoft Windows version 4 and Windows 2000

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, make sure that you understand the potential impact of any command.

Conventions

Refer to Cisco Technical Tips Conventions for more information on document conventions.

Turn Up Tracing

There are two ways in order to document problems in Cisco ICM, with the API or by turning up tracing.

API

Use the API in order to:

• Log an event to the local EMS log file.

• Log an event to the Microsoft Windows NT/2000 Application Event Log.

• Send an event to the database server for storage in the Cisco ICM database.

• Send an event to the central customer service forwarding service for delivery to Cisco Technical Assistance Center (TAC).

Turn Up Tracing

In order to troubleshoot ICM problems, you can turn up tracing with one of these procedures:

• Microsoft Windows NT or Windows 2000 Registry Editor

• Regacc Utility

• OPCTest

• rttest

• Procmon

Note: Be sure to turn off all tracing when finished. Also, more importantly, do not leave process command windows open when you finish testing. This severely impacts system resources, especially CPU utilization and memory.

Windows NT or Windows 2000 Registry Editor

Complete these steps in order to run regedit32:

1. Choose Start > Run.

2. Type regedt32 in order to open the Windows NT or Windows 2000 Registry Editor.

   Here is an example of the Registry Editor and the EMS Peripheral Interface Manager (PIM) settings. In order to view these settings, navigate to this path:

   • Cisco ICM version 4.6 and earlier:

     Software\geotel\icr\cust_inst\ICRcomponenttype\EMS\CurrentVersion\
       Library\Processes

   • Cisco ICM version 5.0 and later:

     Software\Cisco Systems,Inc.\icm\cust_inst\ICMcomponenttype\EMS\
       CurrentVersion\Library\Processes

   Ideally, you see keys on the left side of the Registry Editor window, and values on the right.

3. Double-click the value you want to change, and the DWORD Editor dialog box displays.

4. In the Radix panel, click Hex.

5. Change the value.

6. Click OK.

This table shows the values you can change in the Registry Editor. The most common values to change are the AllLogFileMax, LogFileMax, and TraceMask. The log file count must never be changed.

Value	Path
EMSAllLogFileMax	Total maximum size of all EMS log files for the process. The default is either 6000000/6 MB or 2000000/2 MB.
EMSAllLogFileCount	Number of EMS log files for the process. The default is 20 and does not usually need to be changed.
EMSLogFileMax	The maximum size of each EMS log file. The default is 100000 or 100K.
EMSTraceMask	Trace Bit for the process to have more data logged to the EMS log files. The default is 0.
EMSUserData	Leave this blank. Setting trace bits in procmon auto-populates this field.
EMSDisplayToScreen	Default is 1. Set to 0 in order to not display the data in the process window. This is less CPU intensive, and allows easier pcAnywhere access.

If you need to increase tracing in order to troubleshoot, first determine the amount of free disk space on the machine. If there is enough disk space available, make these changes:

• Set EMSAllLogFileMax to 100 MB.

  Note: First make sure you have enough disk space on the drive where Cisco ICM is installed.

• Set EMSLogFileMax to 10 MB.

• Set EMSDisplayToScreen to 0.

• The registry changes must be made for each process from which you plan to gather logs.

  Note: Remember EMSAllLogfilesMTax is cumulative. If you set EMSAllLogfilesMax to 100 MB for OPC, PIM1, PIM2, and CTISVR, you use 400 MB of the available drive space.

• The file sizes suggested are merely a reference point. Large and busy contact centers can potentially need to increase EMSAllLogfilesMax in order to ensure logs are not overwritten.

Display Message Traces

Once the messages are captured, display them with the dumplog EMS utility. Dumplog reads an EMS log file, formats the event data, and writes the formatted data to an output file. If the log file includes message trace events, each traced message appears in decoded format in the dumplog output.

When the data is captured, reset the values you changed.

Regacc Utility

The regacc utility is command-driven and can be used in a Telnet session. Type regacc at the command prompt. This table lists the most common regacc commands:

Command	What It Does
regcd	Changes the current registry directory.
regdir	Lists the current registry directory.
regpwd	Prints the current working directory.
regset	Sets a new registry value in the current working registry directory.
q	Exits the regacc utility.
?	Displays Help for regacc.
command /?	Displays the syntax for an individual command.

This example displays how to access the directory that contains the processes to turn up tracing. Issue the regcd command in order to change directory, and then the regdir command in order to display the contents of the current working directory.

regcd
Cisco ICM version 4.6 and earlier:
regacc:regcd software\geotel\icr\cal\pg1a\ems\currentversion\library\processes

Cisco ICM version 5.0 and later:
regacc:regcd software\Cisco Systems, Inc.\icm\cal\pg1a\ems\currentversion\library\processes
regacc:regdir
		<KEY>       : DCServer
               <KEY>       : et
               <KEY>       : hsl
               <KEY>       : mds
               <KEY>       : mis
               <KEY>       : nm
               <KEY>       : nmm
               <KEY>       : opc
               <KEY>       : pgag
               <KEY>       : pim1
               <KEY>       : tsyp

Note: This value is displayed over multiple lines due to space limitations.

In this case, the PIM process needs tracing. The regcd command is used in order to move into the pim1 directory, and the regdir command in order to view the contents of that directory.

regacc:  regcd pim1 
regacc:regdir

EMSAllLogFilesMax             : REG_DWORD: 1e8480
EMSBreakOnExit                : REG_DWORD: 0x0
EMSBreakOnInit                : REG_DWORD: 0x0
EMSDebugBreak                 : REG_DWORD: 0x1
EMSDisplayToScreen            : REG_DWORD: 0x1
EMSForwardLevel               : REG_DWORD: 0x1
EMSLogFileCountMax            : REG_DWORD: 0x3e8
EMSLogFileLocation            : REG_SZ: logfiles
EMSLogFileMax                 : REG_DWORD: 0x186a0 
EMSNTEventLogLevel            : REG_DWORD: 0x2
EMSTraceMask                  : REG_DWORD: 0x0
EMSUserData                   : REG_BINARY: FFFF

The regset command is used in order to change the value. In this example, the EMSLogFileMax size is changed from 5 MB to 1 MB.

Note: You must use hexadecimal formats when you change values.

regacc:regset emsalllogfilesmax 1e8480 
emsalllogfilesmax 1e8480                    :REG_DWORD:  1e8480

OPCTest, Rttest, and Procmon

Here is an explanation of the processes used in tracing.

OPCTest

You can use OPCTest in order to turn up tracing for the OPC process only. Turn up individual trace meters with the debug command. In OPCTest, type debug /? for more information about the command.

If the process asserts or if services are stopped, the options you specified turn off. It is still necessary to use the regacc or regedt32 command in order to increase the EMSAllLogFilesMax and EMSLogFilesMax so that the data does not wrap in the output.

In order to turn off tracing from OPCTest, issue the debug /noall command. Do not forget to minimize all process windows when you finish testing.

Refer to Using the OPC Test Command Line Utility for more information about OPCTest.

Rttest

You can issue the rttest command in order to turn up tracing only for the RTR process. Use the debug command in order to turn up individual trace meters. In rttest, type debug /? for more information about the command.

If the process asserts or if services are stopped, the options you specified turn off. It is still necessary to use the regacc or regedt32 command in order to increase the EMSAllLogFilesMax and EMSLogFilesMax so that the data does not wrap in the output.

Refer to The Cisco ICM rttest Utility for more information about rttest.

Procmon

You can use procmon to turn up tracing on the pims, mis, and ctiserver processes. Unfortunately, there is no standard option to turn up tracing for these processes. For example, the option for the Definity switch is debug, whereas to start a VRU PIM trace, you must set the trace meter and use the ltrace command in order to view the trace meters. In order to view more information about the use of procmon, type this at a DOS prompt:

procmon custname device process

Issue the mhelp command in order to list the options for the individual process.

Here is an example of the options for the Definity switch:

C:\>procmon cust pg2a pim1
>>>>debug /?
Usage: acd_debug [/noagent] [/agent] [/agent+] [/agent++] [/nobri] [/bri]
                 [/bri+] [/nocall] [/call] [/call+] [/nocms] [/cms] [/cms+]
                 [/noconfig] [/config] [/nocv] [/cv] [/noerror] [/error]
                 [/nohb] [/hb] [/ken] [/ken+] [/noken] [/noopc] [/opc]
                 [/nopost] [/post] [/nosim] [/sim] [/notg] [/tg] [/notimer]
                 [/timer] [/notp] [/tp] [/tp+] [/trace] [/novq] [/vq] [/vq+]
                 [/warning] [/nowarning] [/all] [/noall] [/set UserSetBit]
                 [/help] [/?]

The regacc utility is built into procmon. Within procmon, you can issue the mhelp command in order to view the regacc commands.

If the process asserts or if services are stopped, the options you specified turn off. It is still necessary to use the regacc or regedt32 commands to increase the EMSAllLogFilesMax and EMSLogFilesMax so that the data does not wrap in the output.

To turn off tracing from procmon, enter debug /noall. Do not forget to minimize all process windows when you finish testing.

Refer to Using Remote Process Monitor Console (Procmon) for more information about procmon.

Related Information

• Using the OPC Test Command Line Utility
• The Cisco ICM rttest Utility
• Using Remote Process Monitor Console (Procmon)
• How to Use the Dumplog Utility
• Technical Support - Cisco Systems