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

Summary: The following knowledge base article explains the process to modify the diagnostics logging for Strategy components from the command line in Windows and Unix environments. Both enabling and disabling logs 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 Strategy Knowledge Base technical note: 
 
KB10941: What is the MSTRCtl utility and how is it used in MicroStrategy Intelligence Server 9.x?
 
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 Strategy 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 gsic
   

   
   
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 "mstrctl -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
An example scenario to turn on the SMTP Sender > Trace under CastorServer Instance is shown below:
 

1. Navigate to <install_path>/opt/Strategy/bin
2. Use the './mstrctl -s IntelligenceServer gsc' command to determine the current log destinations:
    
   

   
   ./mstrctl -s IntelligenceServer gsc
   <?xml version="1.0"?>
   <configuration>
   <base_tcp_port_number>34952</base_tcp_port_number>
   <log_path>/var/log/Strategy</log_path>
   <install_path>/opt/Strategy/IntelligenceServer</install_path>
   <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>
   ...
   

   
     
3. Use the './mstrctl -s IntelligenceServer gsic' command to determine if SMTP Sender > Trace is currently enabled:
   

   
   ./mstrctl -s IntelligenceServer gsic
   <?xml version="1.0"?>
   <configuration n="CastorServer">
   ...
   <logger n="SMTPSender">
   <dispatcher n="Error">
   <log_destination n="DSSErrors"/>
   </dispatcher>
   <dispatcher n="Packet Trace"/>
   <dispatcher n="Trace"/>
   <dispatcher n="Verbose Packet Trace"/>
   </logger>
   

   
   
4. After determining that there is no output log set for the SMTP Sender > Trace, use the './mstrctl -s IntelligenceServer ssc' command to create a new log destination:
    
   

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

   
   
5. Press the "Control + D" keys on Linux/Unix to terminate the input.
    
6. 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="SMTPSenderTrace" tp="3" max_size="2048" callstack_message_ids=""/>
   </log_destinations>
   

   
   
7. Now use the './mstrctl -s IntelligenceServer ssic' command to set the log destination as the output destination for SMTP Sender > Trace.
    
   

   
   ./mstrctl -s IntelligenceServer ssic
   <configuration>
   <diagnostics>
   <logger n="SMTPSender">
   <dispatcher n="Trace">
   <log_destination n="SMTPSenderTrace"/>
   </dispatcher>
   </logger>
   </diagnostics>
   </configuration>
   

   
   
8. Press the "Control + D" keys on Linux/Unix to terminate the input.
    
9. Check that the entries are created correctly.
   

   
   ./mstrctl -s IntelligenceServer gsic
   <?xml version="1.0"?>
   <configuration n="CastorServer">
   ...
   <logger n="SMTPSender">
   <dispatcher n="Error">
   <log_destination n="DSSErrors"/>
   </dispatcher>
   <dispatcher n="Packet Trace"/>
   <dispatcher n="Trace">
   <log_destination n="SMTPSenderTrace"/>
   </dispatcher>
   <dispatcher n="Verbose Packet Trace"/>
   </logger>
   

   
   

For any traces setup to log under machine default, "mstrctl -s IntelligenceServer ssc" and "mstrctl -s IntelligenceServer gsc" should be used for all steps listed above. 
Users should note, that when enabling diagnostics from the command line through the 'mstrctl' utility, the Intelligence Server log configuration is not automatically updated. As a result, any logging enabled while the Intelligence Server is running will need an Intelligence Server restart to take effect. Users can force the Intelligence Server to update its diagnostic configuration manually by running the command 'echo "d" > <MSTR_HOME_PATH>/IntelligenceServer/command-iserver.txt' on Unix/Linux systems, where <MSTR_HOME_PATH> is the home path chosen during installation.
 
To enable a new performance logging configuration, users should run the command 'echo "p" > <MSTR_HOME_PATH>/IntelligenceServer/command-iserver.txt' at the command line.
KB15868