So what is TM1 TOP?
Definition and Access
The TM1 Top utility empowers you to dynamically monitor “threads” running in an instance of a Cognos TM1 server. TM1 Threads are of three possible “types”:
- User Threads – Name of an actual user that is logged into TM1
- Chore Threads – A chore running on the TM1 server
- System Threads – A TM1 system process running on the TM1 server. System threads can be:
- Pseudo (used to clean up user-defined consolidation (UDC) objects)
- Stats (represents the thread for the performance monitor feature that is started when a user selects the Start Performance Monitor option in TM1 Architect and Server Explorer) or
- DynamicConf (dynamically reads and updates parameters in the TM1 server configuration file, tm1s.cfg.
TM1 Top is a stand-alone utility (similar to the UNIX “top” utility which allows dynamic monitoring of the processes running on a given system) that runs within a console (command) window on a Microsoft Windows system. It is designed to make minimal demands on the TM1 server and the supporting network and system.
With the exception of a user-initiated login process, TM1 Top does not use any cube or dimension resources in the TM1 server, and does not use or interact with the data or locks on the TM1 server. The server-side processing that supports TM1 Top runs in a separate light thread to allow TM1 Top to report server state even if the server is unresponsive to users.
Generally, TM1 Top provides real-time monitoring of your TM1 servers, similar to the GNU operating system top command.
The Formal Installation
TM1 Top is installed by default when you install TM1 Server (when you perform a custom TM1 installation with the TM1 Installation Wizard, TM1 Top is listed under Servers on the Component Selection screen).
After installation, you need to locate the following files:
- Tm1top.exe
- TM1top.ini
These files will be located in your TM1 “bin” folder”.
If TM1 Top is not currently installed on your system, you can run theTM1 Installation Wizard to install the utility as follows.
- Run the TM1 Installation Wizard.
- If your system has a previous installation of TM1, click Next to advance to the Program Maintenance screen. On the Program Maintenance screen, select the Modify option. Click Next to advance to the Installation Options screen.
- If your system does not have a previous installation of TM1, follow the Installation Wizard steps until the Installation Options screen opens.
- On the Installation Options screen, select the Custom option for the Installation Type.
- Click Next.
The Component Selection screen opens.
- On the Component Selection screen, expand the Servers component category and select the TM1 Top sub-category.
- Select the This feature will be installed on local hard drive option for TM1 Top.
- Follow the steps in the TM1 Installation Wizard to complete the installation.
Configuring the TM1top.ini File
Before you can run TM1 Top, you need to edit the initialization file Tm1top.ini. Like TM1 Server, TM1 top utilizes a simple text file to initialize at startup. This file is named TM1top.ini and is an ASCII file that specifies environment information for the TM1 Top utility.
By default, a sample Tm1top.ini file is installed to the TM1_install_dir\bin directory. When you run TM1 Top, the Tm1top.ini file needs to be located in the same directory as the TM1 Top executable file.
A sample of a configured Tm1top.ini file is shown below.
adminhost=
servername=planning sample
logfile=c:\temp\tm1top.log
logperiod=50
logappend=T
refresh=10
adminsvrsslcertid=
adminsvrsslcertauthority=
adminsvrsslcertrevlist=
exportadminsvrsslcert=
adminsvrsslexportkeyid=
Remember; do not include any spaces between the parameter name and the parameter value when editing the Tm1top.ini file. The parameters in the Tm1top.ini file are described in the following table.
Running TM1 Top with Command-line Options
You can also enter the configuration parameter values at the command prompt when starting TM1 Top (which will over-ride the values in the Tm1top.ini file).
Use must use the following syntax to run TM1 Top with command-line options:
tm1top.exe -OptionName1 OptionValue1 -OptionName2 OptionValue2 ..
OptionName and OptionValue can be any of the following parameter and value combinations:
- -adminhost admin-host-name
- -servername server-host-name
- -refresh refresh-period
- -logfile file-path
- -logperiod nnn
- -logappend T or F
For example, to run TM1 Top with the ServerName parameter set to sdata, the refresh parameter set to 5 seconds and output sent to a logfile, enter the following:
tm1top.exe -servername sdata -refresh 5 –logfile c:\tm1logs\topout.txt
Note: Use quotes for parameter values that include spaces, as follows:
tm1top.exe -servername "planning sample"
Also from the command line you can see a list of available parameters, use the /? option as follows:
tm1top.exe /?
Understanding the Top Display
When TM1 Top is running, it displays a set of fields and status information in the following format:
Each row in the display represents one unique thread running in the TM1 server that you are monitoring. The title bar of the console window displays the current values for the AdminHost, ServerName, and Refresh parameters.
TM1 Top is a DOS based application executable, so to see more lines or a wider display, you need to re-size the console window or use a smaller font size. If the display fills the entire height of the console window, you can use the up and down arrow keys on your keyboard to go to the next or previous page within the console window.
The following table is based upon information provided in the product documentation and describes the status fields displayed by TM1 Top.
Locking
TM1 Server uses a set of three lock modes to control access to TM1 data. When a TM1 server is running, it applies these locks to individual TM1 objects, such as cubes, views, and dimensions, as these objects are accessed by TM1 threads. All locks will impact TM1 performance at some level.
The level of impact to application performance will be based upon:
- Lock Mode applied
- User activities
- Model architectural design
The lock modes for TM1 objects are described in the following table.
TM1 Top displays the status of locks used by all threads running in a TM1 server. Lock status is displayed by TM1 Top under the State, Obj Lock Status, and Total Lock Status fields. It is important that lock status be reviewed regularly by the application administrator to determine the application’s locking pattern(s). Based upon observed locking patterns, the application administrator may:
- Reschedule application processes to off peak intervals
- Cancel locked threads
- Ask for a review of a particular area of the application architecture that appears to be a thread bottleneck
Thread Processing States
As previously mentioned, TM1 application activity is represented in “threads”. TM1 Top displays the current processing state of each thread in the State field. A TM1 thread can be in one of the following processing states.
Important for the application administrator to note are:
- Thread states Idle, Run and Login are “normal” and mostly non-impacting to application performance.
- Threads in a Wait state should be monitored. It is normal for all threads to experience some Wait time, but if a thread remains in this state for an extended period of time, the application administrator will need to determine the cause of the wait. Waits are caused by one of the following events:
- The thread is waiting for R-locks to be released so it can obtain a W-lock on the object.
- The thread is waiting for a W-lock to finish so it can get either an R-lock or an IX-lock on an object.
- The thread is requesting an IX-lock, but is waiting for another thread with an IX-lock on the same object to finish and release the lock.
- The thread is requesting an IX-lock for an object, but is waiting for a thread with a R-lock on the same object to release its lock.
- The thread is waiting for another thread to complete and release its locks.
- A thread in a Commit state will cause TM1 Server to apply object locks and have the potential to impact application performance.
- A thread in a Rollback state literally means that that TM1 Server has not allowed it to continue to completion and has restarted the thread from its most recent “checkpoint”. There is no “maximum times” that a thread will be restarted; therefore a thread will be rolled backed as many times as it takes to complete or it is canceled by the administrator. This is one of the most common causes of application performance degradation
Basic Top Commands
It is important that the application administrator have TM1 administrator access. Using TM1 Top, an administrator can see exactly what is happening in/on a TM1 Server. In addition, particular threads can be reviewed and, if required, canceled.
Canceling a Thread
Using the TM1 Top cancel command, the application administrator can attempt to cancel and remove a thread (by the unique thread ID). The TOP cancel command inserts a “ProcessQuit” into the chosen thread. If the thread is calculating a large view or is a TurboIntegrator process “stuck in a loop”, the cancel command may not be effective. In this case, the only option may be to terminate the user’s connection using the TM1 Server manager.
The following are the most commonly used TM1 Top commands:
X -exit
W -write display to a file
H -help
V -verify/login to allow cancelling jobs
C -cancel threads, you must first login to use that command
Potential Errors and Exceptions
During the user of TM1 Top, the following exceptions may be encountered:
“Could not connect to server “servername” on admin host “adminname””
Press “R” to retry; or any other key to exit
This error occurs when TM! Top cannot connect to the TM1 server. The most common causes are:
- Incorrect TM1 Top configuration
- TM1 Server not running
TM1Top will not run. Can’t find the tm1api.dll
This error occurs when the TM1Top executable cannot locate the file TM1API.dll was not found. Re-installing the application may fix this problem. TM1Top needs the following files to work:
- TM1Top.exe
- TM1Top.ini
- tm1api.dll
- tm1sip.dll
- tm1lib.dll
TM1Top flashes and the command console does not appear
This error occurs when the path to the log file in the tm1top.ini file does not exist. Verify that the path to the log file in the tm1top.ini file exists. If not, choose a path that does exist and the window should come up as expected.
Conclusion
There are many methods for monitoring and managing TM1 applications. One of the most useful and easy to implement is TM1 Top. No application administrator should be without it!
