Creating a kernel trace

Last update: 8 March 2018
This article describes the steps neccessary to create a kernel trace of activities of Fabasoft Folio components.

Microsoft Windows

In order to be able to trace the activities of the Fabasoft Folio Kernel with the Fabasoft Tracer, the Kernel DLL coomk.dll* has to be replaced with a special trace version.

Fabasoft Folio Kernel Trace Version

The trace version of coomk.dll can be found at the following locations:

  • In the directory "Setup/ComponentsBase/Trace/<plattform>/" on the Fabasoft Folio installation disc or image.
*In versions prior to Fabasoft Folio 2010 Winter Release the file was named coomkXX.dll where XX is the version number of the release.

Fabasoft Tracer

In order to capture the trace messages from the Kernel the Fabasoft Tracer "tracer.exe" has to be started, for more information about the usage please see Fabasoft Tracer.

Creating the Trace

To create the trace the following steps have to be performed:
  1. Stop the Fabasoft Folio web-, AT- and/or conversion service.
  2. Rename the file "coomk.dll" in the Kernel installation directory to "coomk.dll.noTrace".
  3. Copy the trace version of "coomk.dll" into the Kernel installation directory.
  4. Set the environment variable "CHECKINSTALLATION" to "CHECKINSTALLATION=COMPONENTS" . This can be done either by editing the Registry value at 
    HKEY_CURRENT_USER\Software\Fabasoft\Environment

    with the service user that runs the Kernel or via editing the .upd files (coomk.upd and cooprep.upd) located at C:\ProgramData\Fabasoft.

  5. Start the Fabasoft Folio web-, AT- and/or conversion services necessary to reproduce the problem.
  6. Prepare the steps necessary to reproduce the problem.
  7. Start the Fabasoft Tracer.
  8. Try to reproduce the problem.
  9. When the problem occurs, save the tracer output to a file using the menu "File->Save".
  10. Upload the trace file to the Fabasoft Support Service Desk.
Please ensure that only trace message information from process, thread and module are recorded, this can be achived by using the Fabasoft Tracer menu "Settings->Output->Default".
Please only start the Fabasoft Tracer when you are ready to reproduce the problem. This ensures that only trace messages that are related to the problem are recorded and helps in the analysis of the trace.

Removing the Trace Version

If you want to stop using the trace version of the Kernel perform the following steps:
  1. Stop the Fabasoft Folio web-, AT- and/or conversion service.
  2. Delete the trace version of the file "coomk.dll".
  3. Rename the file "coomk.dll.noTrace" back to "coomk.dll".
  4. Restore the environment variable "CHECKINSTALLATION" to its initial state by setting it to "CHECKINSTALLATION=yes".
  5. Start the Fabasoft Folio web-, AT- or conversionservice.

Linux

In order to be able to trace the activities of the Fabasoft Folio Kernel with the Fabasoft Tracer, the Kernel library libcoomk.so* has to be replaced with a special trace version.

Fabasoft Folio Kernel Trace Version

The trace version of libcoomk.so can be found at the following locations:
  • In the directory "Setup/ComponentsBase/Trace/<platform>/" on the Fabasoft Folio installation disc or image.
*In versions prior to Fabasoft Folio 2010 Winter Release the file was named libcoomk.so.XX where XX is the version number of the release.

Trace Message Logging

Prior to Fabasoft Folio 2015 trace messages in Linux were written in the log file of the appropriate instance:
  • Webservices:
    Webservices write trace messages into "/var/opt/fabasoft/log/web/WebService_<id>.error.log".
  • AT-Services:
    AT-Services write into "/var/opt/fabasoft/instances/COOATService_<id>/log/main/current".
  • FSCEval:
    FSCEval outputs the trace messages to the current console, in order to record this trace messages the console output has to be redirected. 
    fsceval -file <path_to_script> > /tmp/tracefile.trc

    Newer versions use the tool "tracer" to log these messages, for more information about the usage please see Fabasoft Tracer.

Creating the Trace

To create the trace the following steps have to be performed:
  1. Start a terminal.
  2. Login to the Fabasoft Folio service user.
    su - fscsrv
  3. Locate any opened "libcoomk.so", which represent a single kernel instance each.
    lsof |grep libcoomk.so

  4. Stop the Fabasoft Folio web-, AT- and/or conversion service.

  5. The following 2 steps must be executed for every "libcoomk.co" in every directory previously found.

  6. Copy the file "libcoomk.so" in the directories, for instance "/opt/fabasoft/share/eval/" to "libcoomk.so.noTrace".

    cp /opt/fabasoft/share/eval/libcoomk.so /opt/fabasoft/share/eval/libcoomk.so.noTrace

  7. Copy the trace version of "libcoomk.so" into the directories, for instance "/opt/fabasoft/share/eval/" and replace the file that is there.

    cp /<installdisc>/Setup/ComponentsBase/Trace//libcoomk.so /opt/fabasoft/share/eval/

  8. Start the Fabasoft Folio web-, AT- and/or conversion services necessary to reproduce the problem.

  9. Prepare the steps necessary to reproduce the problem.

  10. Start the Fabasoft Tracer or flush the log file if you are using a version prior to Fabasoft Folio 2014 Spring Release

    cp /dev/null /var/opt/fabasoft/<path_to_logfile>

  11. Try to reproduce the problem.

  12. When the problem occurs, save the log file in Fabasoft Tracer or if you are using a version prior to Fabasoft Folio 2014 Spring Release copy the log file using the following command:

    cp /var/opt/fabasoft/<path_to_logfile> /tmp/tracefile.trc

  13. Upload the trace file to the Fabasoft Support Service Desk.

Removing the Trace Version

If you want to stop using the trace version of the Kernel perform the following steps:

  1. Start a terminal.
  2. Login to the Fabasoft Folio service user.
    su - fscsrv
  3. Stop the Fabasoft Folio web-, AT- and/or conversion service.
  4. Copy the file "libcoomk.so.noTrace" back to "libcoomk.so" and replace the trace version.
    cp /opt/fabasoft/share/eval/libcoomk.so.noTrace /opt/fabasoft/share/eval/libcoomk.so
  5. Start the Fabasoft Folio web-, AT- or conversionservice.