How to modify diagnostics logging for MicroStrategy components from the command line in Windows and Unix/Linux environments.

Summary: The following document explains the process to modify the diagnostics logging for MicroStrategy components from the command line in Windows and Unix environments. Both activation and disable are covered.

Introduction:

Diagnostics logging can be turned on from the command line in both Windows and Unix/Linux environments by using the mstrctl utility. This utility is described in detail in the following MicroStrategy Knowledge Base technical note:

What is the MSTRCtl utility and how is it used in MicroStrategy Intelligence Server 9.x?

Summary: This Document explains what is the MicroStrategy MSTRCTL utility, including some of its functionalities and an example usage. 

What is MSTRCTL?

MSTRCTL is a MicroStrategy Intelligence Server control utility that can be used to retrieve Intelligence Server related information and manipulate Intelligence Server instances from command line. The Microsoft Windows installation of the Intelligence Server will locate the file MSTRCTL.exe under Program Files/Common Files/MicroStrategy. For MicroStrategy Intelligence Server Universal installations on Unix/Linux the mstrctl script may be found in the "MicroStrategy Home/bin" folder.

MSTRCTL functionalities:

For a complete list of possible functionalities of the utility, navigate to the of the utility and execute it with the '-h' option: 

mstrctl -h

The output from the command is shown below: 

Usage:
mstrctl [-h -V]
-h, --help       print this screen and exit.
-V, --version       print version information and exit.

Usage (NETWORK):
mstrctl <request>
<request>:
(list-machines lm) [server_name]       discover machines that this utility may control.

Usage (MACHINE): 
mstrctl [-m <machine_name> [-l <login>]] <request>
-m <machine_name>, --machine=<machine_name>       execute the request on the specified machine.
-l <login>, --login=<login>       remote machine account (password will be prompted).
<request>: (list-servers ls)       list servers installed on a machine.
(list-odbc-dsns lod)       list ODBC DSNs.

Usage (SERVER): 
mstrctl [-m <machine_name> [-l <login>]] -s <server_name> <request> [parameters]
-m <machine_name>, --machine=<machine_name>      execute the request on the specified machine.
-l <login>, --login=<login>       remote machine account (password will be prompted).
-s <server_name>, --server=<server_name>       server that request refers to.
<request> [parameters]:
(list-instances li)       list existing server instances.
(get-default-instance gdi)       get default instance name.
(set-default-instance sdi) <instance_name>       change default instance name.
(get-server-configuration gsc)       get server configuration.
(set-server-configuration ssc)       change server configuration.
(create-instance ci) [instance_name]       create a new server instance.
(copy-instance cpi) [instance_name] <new_instance_name>       duplicate an instance with a new name.
(delete-instance di) [instance_name]       delete a server instance.
(register-service rs) [instance_name]       register a server instance as service.
(unregister-service us) [instance_name]       unregister a server instance as service.
(get-license gl)       get server license information.

Usage (SERVER INSTANCE): 
mstrctl [-m <machine_name> [-l <login>]] -s <server_name> <request> [instance_name]
-m <machine_name>, --machine=<machine_name>       execute the request on the specified machine.
-l <login>, --login=<login>       remote machine account (password will be prompted).
-s <server_name>, --server=<server_name>       server that request refers to.
<request>:
(get-service-configuration gsvc)       get service configuration.
(set-service-configuration ssvc)       change service configuration.
(get-server-instance-configuration gsic)       get server instance configuration.
(set-server-instance-configuration ssic)      change server instance configuration.
(get-status gs)       get server instance status.
start [--interactive --service]       start a server instance.
stop       stop a server instance.
pause       pause a server instance.
resume       resume a server instance.
(terminate term)       terminate a server instance (use with caution).

As shown above, MSTRCTL command can be used to retrieve server related information for a network, machine, server, or server instance. The command can also be used to manipulate specific server instances.

Example for MSTRCTL command usage: 

The following is an example demonstrating how to use the MSTRCTL command to retrieve MicroStrategy Intelligence Server related information. The following steps show how to retrieve the complete configuration information for an Intelligence Server instance:

1) Execute the command below to obtain a list of servers running on a machine:

mstrctl -m test-computer ls

Here, test-computer is the machine name in which a user is interested. The sample output shows there are three servers running on the machine:

EMDataLoader
IntelligenceServer
Listener

2) To obtain all instances of MicroStrategy Intelligence Server on a machine, execute the following command:

mstrctl -m test-computer -s IntelligenceServer li

The sample output shows there is only one instance of Intelligence Server running on the test-computer machine and is called CastorServer shown below (which is the name for the default Intelligence Server instance). The "-m " option can be dropped in which case the utility reports the instances on the local machine.

CastorServer

3) To retrieve the complete configuration information for the CastorServer instance, execute the following command:

mstrctl -m test-computer -s IntelligenceServer gsic CastorServer

Part of a sample output for the command is shown below:

<?xml version="1.0"?>
<configuration n="CastorServer">
   <metadata>
     <login>AccessUser</login>
     <odbc dsn="MicroStrategy_Tutorial_Metadata"/>
   </metadata>
   <svrd n="MicroStrategy Tutorial Server"/>
   <tcp_port_number>65534</tcp_port_number> 
   <processor_affinity_mask is_supported="1" >0</processor_affinity_mask>
   <performance_monitor_enabled>1</performance_monitor_enabled>
   <performance_counters log_destination="DSSPerformanceMonitor" pru="1" frequency="1" persist_perf_counter="1">
     <cat n="MicroStrategy Intelligence Server Profiler">
          <performance_counter n="DSSAnalyticalEngineServerTask CPU Time(sec)" persist="0"/>
          <performance_counter n="DSSAnalyticalEngineServerTask Elapse Time(sec)" persist="0"/>
          <performance_counter n="DSSAnalyticalEngineServerTask Total Counts" persist="0"/>
          <performance_counter n="DSSApplyViewContextTask CPU Time(sec)" persist="0"/>
          <performance_counter n="DSSApplyViewContextTask Elapse Time(sec)" persist="0"/>
          <performance_counter n="DSSApplyViewContextTask Total Counts" persist="0"/>
          <performance_counter n="DSSCloseJob CPU Time(sec)" persist="0"/>
          <performance_counter n="DSSCloseJob Elapse Time(sec)" persist="0"/>
          <performance_counter n="DSSCloseJob Total Counts" persist="0"/>
          <performance_counter n="DSSDatamartExecuteTask CPU Time(sec)" persist="0"/>
          <performance_counter n="DSSDatamartExecuteTask Elapse Time(sec)" persist="0"/>
          <performance_counter n="DSSDatamartExecuteTask Total Counts" persist="0"/>
          <performance_counter n="DSSDocumentDataPreparationTask CPU Time(sec)" persist="0"/>
          <performance_counter n="DSSDocumentDataPreparationTask E lapse Time(sec)" persist="0"/>
          <performance_counter n="DSSDocumentDataPreparationTask Total Counts" persist="0"/>
          <performance_counter n="DSSDocumentExecuteTask CPU Time(sec)" persist="0"/>
          <performance_counter n="DSSDocumentExecuteTask Elapse Time(sec)" persist="0"/

Steps to enable logging:

1. Create a logging destination if one does not already exist.
2. To check the existing logging destinations, run the command:
   
   

   mstrctl -s IntelligenceServer gsc

   
   
3. To create the new logging destination use the command:
   
   

   mstrctl -s IntelligenceServer ssc

   
   
   After entering this command, users can enter the required configuration xml. An example transaction is shown below:
   
   

   ./mstrctl -s IntelligenceServer ssc
   <configuration>
   <log_destinations>
   <log_destination n="NewTraceFile" tp="3" max_size="2048" callstack_message_ids=""/>
   </log_destinations>
   </configuration>

   
   
   To terminate the input to mstrctl on Windows use the key combination "Control + Z". On Unix/Linux the combination "Control + D" is needed.
4. To check the current logging configuration for all the MicroStrategy components, it may be possible to use the output from step two. To check the logging configuration for the CastorServer Instance, use the command:

   mstrctl -s IntelligenceServer gsc

   
   
5. Now depending on whether the logging should be turned on for all instances or for the specific CastorServer Instance, the command "mstrctl -s IntelligenceServer ssc" or "mstrtctl -s IntelligenceServer ssic" may be used. The transaction to turn on the logging is as follows:
   
   

   ./mstrctl -s IntelligenceServer ssic
   <configuration n="CastorServer">
   <diagnostics pru="0">
   <logger n="Component_name">
   <dispatcher n="dispatcher_name">
   <log_destination n="NewTraceFile"/>
   </dispatcher>
   </logger>
   </diagnostics>
   </configuration>

   
   
6. To turn off the logging for a specific dispatcher, use the 'delete="1"' attribute in the log destination tag as shown below:
   
   

   ./mstrctl -s IntelligenceServer ssic
   <configuration n="CastorServer">
   <diagnostics pru="0">
   <logger n="Component_name">
   <dispatcher n="dispatcher_name">
   <log_destination n="TraceFile" delete="1"/>
   </dispatcher>
   </logger>
   </diagnostics>
   </configuration>

   
   

Example to activate the database connection instance trace:

An example scenario to turn on the database connection instance trace under the Database Classes component is shown below:

1. Use the './mstrctl -s IntelligenceServer gsc' command to obtain the current default diagnostics configuration:
   
   

   ./mstrctl -s IntelligenceServer gsc
   
   <?xml version="1.0"?>
   <configuration>
   <base_tcp_port_number>34952</base_tcp_port_number>
   <log_destinations>
   <log_destination n="SystemLog" tp="2" callstack_message_ids="0x800438C7"/>
   <log_destination n="LicenseSummary" tp="3" max_size="4000" callstack_message_ids=""/>
   <log_destination n="DebugOutput" tp="1" callstack_message_ids=""/>
   <log_destination n="DSSPerformanceMonitor" tp="4" max_size="2000" callstack_message_ids=""/>
   <log_destination n="DSSErrors" tp="3" max_size="2048" callstack_message_ids="0x800438C7"/>
   </log_destinations>
   
   <performance_counters log_destination="DSSPerformanceMonitor" frequency="1" persist_perf_counter="1">
   <cat n="Memory">
   <performance_counter n="Free paging space(MB)" persist="0"/>
   ...
   <diagnostics>
   <logger n="(Default)">
   <dispatcher n="Error">
   <log_destination n="DSSErrors"/>
   </dispatcher>
   <dispatcher n="Fatal">
   <log_destination n="DSSErrors"/>
   </dispatcher>
   <dispatcher n="Info">
   <log_destination n="DSSErrors"/>
   </dispatcher>
   <dispatcher n="Warning">
   <log_destination n="DSSErrors"/>
   </dispatcher>
   </logger>
   ...
   
   <logger n="Database Classes">
   <dispatcher n="Connection Instances"/>
   <dispatcher n="Connection Management"/>
   <dispatcher n="Error">
   <log_destination n="DSSErrors"/>
   </dispatcher>

   
   
2. Use the './mstrctl -s IntelligenceServer ssc' command to create a new log destination:
   
   

   ./mstrctl -s IntelligenceServer ssc
   <configuration>
   <log_destinations>
   <log_destination n="DBClassesConnInstTrace" tp="3" max_size="2048" callstack_message_ids=""/>
   </log_destinations>
   </configuration>

   
   
3. Press the "Control + D" keys on Unix to terminate the input.
4. Use the './mstrctl -s IntelligenceServer gsc' command to check that the log destination entry is entered correctly:

   ./mstrctl -s IntelligenceServer gsc
   
   <?xml version="1.0"?>
   <configuration>
   <base_tcp_port_number>34952</base_tcp_port_number>
   <log_destinations>
   <log_destination n="SystemLog" tp="2" callstack_message_ids="0x800438C7"/>
   <log_destination n="LicenseSummary" tp="3" max_size="4000" callstack_message_ids=""/>
   <log_destination n="DebugOutput" tp="1" callstack_message_ids=""/>
   <log_destination n="DSSPerformanceMonitor" tp="4" max_size="2000" callstack_message_ids=""/>
   <log_destination n="DSSErrors" tp="3" max_size="2048" callstack_message_ids="0x800438C7"/>
   <log_destination n="DBClassesConnInstTrace" tp="3" max_size="2048" callstack_message_ids=""/>
   </log_destinations>
   

   
   
5. Now use the './mstrctl -s IntelligenceServer ssc' command to set the log destination as the output destination for the connection instance trace.

   ./mstrctl -s IntelligenceServer ssc
   <configuration>
   <diagnostics>
   <logger n="Database Classes">
   <dispatcher n="Connection Instances">
   <log_destination n="DBClassesConnInstTrace"/>
   </dispatcher>
   </logger>
   </diagnostics>
   </configuration>

   
   
6. Press the "Control + D" keys on Unix to terminate the input.
7. Check that the entries are created correctly.

   ./mstrctl -s IntelligenceServer gsc
   <?xml version="1.0"?>
   <configuration>
   <base_tcp_port_number>34952</base_tcp_port_number>
   <log_destinations>
   <log_destination n="SystemLog" tp="2" callstack_message_ids="0x800438C7"/>
   <log_destination n="LicenseSummary" tp="3" max_size="4000" callstack_message_ids=""/>
   <log_destination n="DebugOutput" tp="1" callstack_message_ids=""/>
   <log_destination n="DSSPerformanceMonitor" tp="4" max_size="2000" callstack_message_ids=""/>
   <log_destination n="DSSErrors" tp="3" max_size="2048" callstack_message_ids="0x800438C7"/>
   <log_destination n="DBClassesConnInstTrace" tp="3" max_size="2048" callstack_message_ids=""/>
   </log_destinations>
   <performance_counters log_destination="DSSPerformanceMonitor" frequency="1" persist_perf_counter="1">
   <cat n="Memory">
   <performance_counter n="Free paging space(MB)" persist="0"/>
   <performance_counter n="Free real memory(MB)" persist="0"/>
   ...
   <logger n="Database Classes">
   <dispatcher n="Connection Instances">
   <log_destination n="DBClassesConnInstTrace"/>
   </dispatcher>
   <dispatcher n="Connection Management"/>
   <dispatcher n="Error">