3.4 Working with Log Files

Log files provide useful information about the functioning of the various Synchronizer components.

3.4.1 Log File Overview

The Synchronizer services generate a set of log files that are created in subdirectories under the following directory:

/var/log/datasync

The log file subdirectories and file names are:

Synchronizer Component

Log File Subdirectory

Log File Name

Sync Engine

syncengine

engine.log

Config Engine

configengine

configengine.log

Web Admin

webadmin

server.log

Connector Manager

syncengine

connectorManager.log

Connectors

connectors

default.pipeline1.connector_name-AppInterface.log

default.pipeline1.connector_name.log

Use the following command to check the most recent additions to a log file:

tail -f log_file_name.log

3.4.2 Log File Rotation

The Synchronizer log files are automatically compressed and rotated by a logrotate cron job. The schedule is set by the DAILY_TIME="00:30" line in the /etc/sysconfig/cron file, which means that the log files are checked at 12:30 a.m. each night. Any Synchronizer log files that have exceeded 4 MB in size are compressed and rotated at that time. After 99 instances of each log file have accumulated, the oldest log file is deleted when a new log file is created.

Log rotation is controlled by the following files:

/etc/logrotate.d/datasync-syncengine
/etc/logrotate.d/datasync-configengine
/etc/logrotate.d/datasync-webadmin

By default, gzip is used to compress old log files. You can change the compression method by changing the following line in the files listed above:

compresscmd /usr/bin/gzip

For example, to change from gzip compression to bz2 compression, use the following line:

compresscmd /usr/bin/bzip2 

Using bz2 compression produces smaller log files but uses more system resources during compression.

For more information, see the Linux logrotate command.

3.4.3 Logging Levels

All Synchronizer components have log files:

All Synchronizer log files use the same logging levels:

  • Debug: Logs large quantities of developer-level data. This logging level is appropriate for troubleshooting purposes. It puts a heavy load on the Synchronizer system and should be used only until the troubleshooting activities are completed.

  • Info: Logs informational messages about normal synchronization processing. This logging level is suitable for a Synchronizer administrator who wants to observe the functioning of the Synchronizer system.

    Info is the default logging level and is strongly recommended because it balances the amount of data logged, the amount of disk space required for log files, and the load on the Synchronizer system.

  • Warning: Logs problems that should not adversely affect synchronization processing but should be investigated and resolved for optimum performance. This logging level can be appropriate for a smoothly running Synchronizer system where you only want to be notified of warnings and errors.

  • Error: Logs error messages that indicate critical problems in synchronization processing. This logging level puts the least load on the Synchronizer system because it logs only critical errors, but it does not log sufficient data to help resolve any errors that occur.

3.4.4 Sync Engine Log File

The Sync Engine log file (engine.log) reports on events that pass through the Sync Engine as they transfer from connector to connector. It logs problems with the physical connection to each connector and with communication between connectors. It also logs problems with the event XML files.

You can control the amount of information that is written to Synchronizer log files. The default logging level is Info.

  1. In Synchronizer Web Admin, click default in the Manage Engine section to display the Engine Configuration page.

  2. In the Logging section, select a logging level.

  3. Click Save Log Settings.

  4. Restart the Synchronizer services to put the new setting into effect:

    rcdatasync restart
    

3.4.5 Config Engine Log File

The Config Engine log file (configengine.log) reports on configuration setting changes made in Synchronizer Web Admin and on any effects of those changes on the connections between the Sync Engine and connectors. It also logs issues with starting and stopping connectors and tracks the poll cycle for changes in LDAP groups.

You can control the amount of information that is written to Synchronizer log files. The default logging level is Info.

  1. In a terminal window on the Synchronizer server, become root by entering su - and the root password.

  2. Change to the following directory:

    /etc/datasync/configengine
    
  3. Open the configengine.xml file in a text editor.

  4. Locate the following tag:

    <log>
         <output>/var/log/datasync/configengine/configengine.log</output> 
         <level>info</level>
    </log> 
    

    This section identifies the Config Engine log file and sets the logging level.

  5. Replace the logging level between the <log> tags with the desired logging level.

  6. Save the configengine.xml file, then exit the text editor.

  7. Restart the Synchronizer services to put the new setting into effect:

    rcdatasync restart
    

3.4.6 Web Admin Log File

The Web Admin log file (server.log) reports problems with the Synchronizer Web Admin interface. Typically, you would not see problems here unless you edited the XML source for one of the Configuration pages and introduced invalid XML. If a Configuration page does not display correctly after you edit the XML source, you can check this log file for help resolving the problem with the XML.

You can control the amount of information that is written to Web Admin log file. The default logging level is Info.

  1. In a terminal window on the Synchronizer server, become root by entering su - and the root password.

  2. Change to the following directory:

    /etc/datasync/webadmin
    
  3. Open the server.xml file in a text editor.

  4. Locate the following tag:

    <log>
         <output>/var/log/datasync/webadmin/server.log</output> 
         <level>info</level>
    </log> 
    

    This section identifies the Web Admin service log file and sets the logging level.

  5. Replace the logging level between the <log> tags with the desired logging level.

  6. Save the server.xml file, then exit the text editor.

  7. In a terminal window on the Synchronizer server, become root by entering su - and the root password.

3.4.7 Connector Manager Log File

The Connector Manager log file (connectorManager.log) reports problems with loading a connector that has the configuration provided on the connector’s Configuration page.

The Connector Manager starts one Python thread for itself and an additional Python thread for each connector that it manages. When you list Connector Manager threads or Python threads in a terminal window, you cannot tell which Python thread is associated with the Connector Manager and which Python thread is associated with each connector. The Connector Manager log file lists each component and the PID number associated with each one. This can be very useful for troubleshooting.

3.4.8 Connector Log Files

Each connector has two log files associated with it:

  • The connector application interface log file for each connector (default.pipeline1.connector_name-AppInterface.log) reports on problems that occur during event processing by the connector.

  • The connector pipeline log file for each connector (default.pipeline1.connector_name.log) reports on problems with the event XML files that transfer back and forth between the Sync Engine and the connector. It logs the results as events pass through the connector.

You can control the amount of information that is written to the connector log file.

  1. In Synchronizer Web Admin, click the connector that you want to change the setting for.

  2. In the Logging section, select a logging level.

  3. Click Save Log Settings.

  4. Click Home on the menu bar to return to the main Synchronizer Web Admin page.

  5. In the Actions column for the connector, click Stop Stop icon to stop the connector, then click Start Start icon to start the connector with the new setting.

3.4.9 Synchronizer Log File Management Tools

Log files can be an effective window into the functioning of your Synchronizer system. The log file management tools help you to consolidate log files from multiple locations and to gather specific types of information from multiple log files in a single operation.

Collect Logs Tool

As shown in the Section 3.4.1, Log File Overview, Synchronizer log files are created in a variety of directories. The Collect Logs tool collects the most recent log files into a .tar.gz file for convenience when submitting log files to Support. You can collect all of the log files in the following list, or you can collect just the first five, which are the most useful log files:

  • default.pipeline1.groupwise-AppInterface.log

  • default.pipeline1.groupwise.log

  • default.pipeline1.mobility-AppInterface.log

  • default.pipeline1.mobility.log

  • engine.log

  • configengine.log

  • connectorManager.log

  • server.log

The files are collected into a file named datasync_logs_yyyy-mm-ddThh.mm.ss.tar.gz.

To run the Collect Logs tool:

  1. In a terminal window on the Synchronizer server, become root by entering su - and the root password.

  2. Change to the following directory:

    /opt/novell/datasync/tools
    
  3. Run the following command:

    python CollectLogs.pyc
    
  4. Enter yes if you want to collect all log files.

    or

    Enter no if you want only the five most useful log files.

  5. Enter 1 for the GroupWise Connector.

  6. Enter 1 for the Mobility Connector.

    The collected logs are listed in the terminal window and compressed into the .tar.gz file.

    A manifest.txt file that lists the log files in the .tar.gz file is also included in the .tar.gz file. The manifest.txt file can be used as input to the other log file management tools, as described in Manifest File.

Trace Log Tool

The Trace Log tool enables you to trace a specific item or contact through multiple log files.

  1. In Synchronizer Web Admin, set the logging level to Debug for the Sync Engine log file, the GroupWise Connector log file, and the Mobility Connector log file, as described in:

  2. (Conditional) If you want to trace an item (message, appointment, or note), complete this step, then skip to Step 4:

    1. In the GroupWise Windows client, send a new item, so that item activity is recorded in the log files.

    2. In the Sent Items folder, right-click the item to trace, then click Properties.

    3. Copy the content of the Record ID field to the clipboard of the Windows workstation.

      A record ID looks similar to the following example:

      4C7D1A3C.domain.post_office.100.1686237.1.486FE.1
      
    4. Make the content of the Record ID field available on the Synchronizer server so that you can paste it into the Trace Log tool in Step 9 below.

  3. (Conditional) If you want to trace a contact, complete this step, then continue with Step 4:

    1. In the GroupWise Windows client, open a personal address book.

    2. Right-click the contact to trace, then click Details.

    3. Click Advanced, then scroll down to the Entry ID field.

    4. Copy the content of the Entry ID field to the clipboard of the Windows workstation.

    5. Make the content of the Entry ID field available on the Synchronizer server so that you can paste it into the Trace Log tool in Step 9 below.

  4. In a terminal window on the Synchronizer server, become root by entering su - and the root password.

  5. Change to the following directory:

    /opt/novell/datasync/tools
    
  6. Run the following command:

    python traceLog.pyc
    

    By default, the Trace Log tool accesses log files in the default locations, as listed in Section 3.4.1, Log File Overview. If you want the Trace Log tool to access log files other than those in the default locations and with the default names, see Manifest File for additional instructions.

  7. Enter 1 for the GroupWise Connector.

  8. Enter 1 for the Mobility Connector.

  9. Provide the record ID or entry ID that you gathered in Step 2 or Step 3, then press Enter.

    The Trace Log tool now creates a file named trace.out in the tools directory that includes the following sections to help you diagnose the problem:

    Starting from GroupWise...
    ===================================
    
    From GroupWise Connector into Engine...
    =======================================
    
    Inside Engine...
    ================
    
    From Engine to Mobility Connector...
    ====================================
    
    From Mobility Connector to Device...
    ====================================
    

    Each section lists the log messages that pertain to the problem item or problem contact for each segment of the synchronization process, enabling you pinpoint the source of the synchronization problem.

  10. When you are finished tracing items, set the logging level back to its typical setting.

Track Time Tool

The Track Time tool tracks the average time from when an item is created or modified in the GroupWise client to when the item or modification is available in the Mobility Connector and ready for download to your mobile device.

  1. In Synchronizer Web Admin, set the logging level to Debug for the Sync Engine log file, the GroupWise Connector log file, and the Mobility Connector log file, as described in:

  2. In a terminal window on the Synchronizer server, become root by entering su - and the root password.

  3. Change to the following directory:

    /opt/novell/datasync/tools
    
  4. Run the following command:

    python trackTime.pyc
    

    By default, the Track Time tool accesses log files in the default locations, as listed in Section 3.4.1, Log File Overview. If you want the Track Time tool to access log files other than those in the default locations and with the default names, see Manifest File for additional instructions.

  5. Enter 1 for the GroupWise Connector.

  6. Enter 1 for the Mobility Connector.

    The Track Time tool displays the elapsed time statistics in the terminal window.

  7. When you are finished gathering elapsed time statistics, set the logging level back to its typical setting.

Manifest File

When you run the Collect Logs tool, it creates a .tar.gz file of the collected logs in the tools directory. It also includes a manifest.txt file that lists the collected log files, for example:

{
"GroupWise": "default.pipeline1.groupwise-AppInterface.log", 
"Engine": "engine.log", 
"Mobility Pipeline": "default.pipeline1.mobility.log", 
"Mobility": "default.pipeline1.mobility-AppInterface.log", 
"GroupWise Pipeline": "default.pipeline1.groupwise.log"
}

The Trace Log tool and the Track Time tool can access the manifest.txt file for the list of log files to process. If you want these tools to access archived log files in different locations or with different names from the live log files, you can modify the manifest.txt file and make it available to the tools.

  1. Extract the manifest.txt file from the .tar.gz file into the same directory with the tools (/opt/novell/datasync/tools).

  2. Edit the manifest.txt file with the archived log file locations and file names.

  3. Use the following commands to run the tools:

    python traceLog.pyc -i manifest.txt
    python trackTime.pyc -i manifest.txt
    
  4. After you have used the tools to access the log files listed in the manifest.txt file, delete or rename the manifest.txt file, so that the tools access the live log files, not the archived log files, the next time you run them.

3.4.10 NTS supportconfig Tool

The supportconfig tool provided by Novell Technical Services gathers information about your system to help NTS resolve issues with which you require assistance. It is provided as part of the SUSE Linux Enterprise Server 11 operating system. You can also use it for your own troubleshooting activities.

Each component of your Synchronizer system (Sync Engine, connectors, and so on) has a supportconfig plug-in that gathers information specific to its functioning. The following information is gathered:

  • The component’s configuration file with security information such as passwords stripped out

  • The component’s current log file

  • The component-specific script that supportconfig ran to collect the information

To run supportconfig for your own troubleshooting activities:

  1. In a terminal window on the Synchronizer server, become root by entering su - and the root password.

  2. Enter the following command:

    supportconfig
    

    The supportconfig tool examines the server very thoroughly. At the end of its list of findings, it lists the Synchronizer components:

    Data Synchronizer plug-ins for the supportconfig utility

    The tool zips all the data it collected into the following file:

    /var/log/nts_servername_yymmdd_hhss.tbz
    

    This file name identifies the server and the time stamp for the files that supportconfig has collected.

  3. Examine the files that supportconfig collected:

    1. Copy the .tbz file to a convenient temporary directory.

    2. Use the following command to unzip the compressed file:

      tar xjf file_name.tzb
      

      The following files contain the information about each Synchronizer component:

      List of Data Synchronizer files generated by the supportconfig utility
  4. View each .txt file to see the configuration file, current log file, and script file for each Synchronizer component.

For more information, see supportconfig for Linux.