Enterprise Content Management System Monitor 5.1 Agent Debugging Guide Revision 1.3 2014-11-05 CENIT AG Author: Stefan Bettighofer

2

1 Table of Contents

1 Table of Contents ................................................................................................................. 2

2 Overview .............................................................................................................................. 3

3 Definitions ............................................................................................................................ 3

3.1 IBM ECM CALA_REX Agent ......................................................................................... 3

3.2 IBM ECM CALA Monitoring Agent ................................................................................. 3

3.2.1 logctlsrc .................................................................................................................. 3

3.2.2 calamon ................................................................................................................. 3

3.2.3 ascfileread .............................................................................................................. 3

3.2.4 Ntevtlogread ........................................................................................................... 3

3.2.5 tecfmtfilt .................................................................................................................. 3

3.2.6 v2fmtfilt................................................................................................................... 3

4 View CALA Status task......................................................................................................... 4

5 Activating the task debugging ............................................................................................... 5

6 Activating the monitor debugging ......................................................................................... 7

7 Advanced Debugging Options for tasks and monitors .......................................................... 9

7.1 Store a debug file for each monitor run.......................................................................... 9

7.2 Keep temporary files after each monitor run ................................................................ 11

8 Activate the CALA_REX Client Debugging ......................................................................... 12

3

2 Overview This guide will give an overview on how to debug failures on the ECM SM Agents monitors and

tasks.

3 Definitions

3.1 IBM ECM CALA_REX Agent The CALA_REX Agent receives all remote execution functions from the ECM SM Server. This

includes tasks, file transport and configuration.

3.2 IBM ECM CALA Monitoring Agent The CALA Monitoring Agent is responsible for the monitoring itself. It contains five components

with different functions.

3.2.1 logctlsrv The main component of the ECM SM CALA Monitoring Agent. This component will start up all

other components and checks the health of the agent.

3.2.2 calamon The calamon executes the monitors, creates event and sends them to the ECM SM Server.

3.2.3 ascfileread The general logfile reader of the ECM SM CALA Monitoring Agent.

3.2.4 ntevtlogread The logfile reader especially for the Windows Event Log entries.

3.2.5 tecfmtfilt The logfile parser for the logfiles that use a Tivoli format file.

3.2.6 v2fmtfilt The logfile parser for the ECM SM own format file. (v2s)

4

4 View CALA Status task The View CALA Status task will provide a detailed status of the selected agent including all five

components.

Beside the general information like the version/revision, startup and uptime or the port where the

component is bound to, there are special attributes for each component. In this example, the

ascfileread shows which logfiles are configured to be monitored. The output of the View Cala

Status task is also a valuable source for information if there are problems like instability or the

performance of the client. If for example the startup time of one component is significant different

to the other this is a signal that this component crashed and was restarted by the logctlsrv.

5

5 Activating the task debugging In case a task is not working as expected and the default task output is insufficient to identify the problem the task debugging has to be enabled.

To activate the task debugging a folder call .plusdebug has to be created in the temporary directory of the CALA_REX on the agent. The temporary directory for windows is configured in the file <install directory>\cala_rex\cala_rex_cli.cfg

The default temp directory is <install directory>\temp Windows: e.g C:\Program Files(x86)\IBM\ECMSM_AGENT\temp UNIX: /tmp

Navigate to the temporary directory

6

And create the new folder .plusdebug.

Notes:

Make sure the CALA_REX runtime user has write permissions for the directory.

On Windows, please use the cmd to create the folder. The context menu “new folder” does not allow a dot as first character in a folder name.

On Unix systems the temporary directory of the cala_rex is always /tmp. The .plusdebug directory has to be created within this directory.

On old Windows CALA_REX installations, it is possible, that the tempdir property is not set in the cala_rex_cli.cfg. In this case please add the missing property or create the .plusdebug directory in the fallback temp directory located in the Windows temp. Windows e.g: C:\Windows\Temp\.plusdebug

With activated task debugging the task output will now display the path and the name to the correct logfile.

7

6 Activating the monitor debugging All monitors will return a negative return code if they run into a problem during the execution.

The return code depends on the monitor. All possible return codes of a monitor are documented

in the online help of the monitor or in the monitoring guides. The two screenshots are showing

the possible return codes of the monitor ObjectStorePerformance

Online Help Monitoring Guide

These return codes helps to identify the problem of the monitor but in some cases, more detailed

debugging information or a logfile is necessary.

To activate the monitor debugging a folder call .plusdebug has to be created in the temporary

directory of the CALA on the agent. The temporary directory on Windows is located in

<install directory>/cala/temp, on Unix the /tmp directory is used instead.

Windows e.g: C:\Program Files (x86)\IBM\ECMSM_AGENT\cala\temp\.plusdebug

Unix e.g: /tmp/.plusdebug

Navigate to the temporary directory

8

Create the new folder .plusdebug

Note:

Make sure the CALA runtime user has write permissions on the directory.

On Windows, please use the cmd to create the folder. The context menu “new folder” does not allow dot for the first character in a folder name.

With activated monitor debugging the message text in the events will be extended with the directory and file name of the corresponding debug file.

9

7 Advanced debugging options for tasks and monitors In additional to the normal debugging mode where every debug file will be overwritten by the

next monitor/task run and the temporary files are removed after the completion of the monitor or

task ECM SM offers two additional debugging options.

7.1 Store a debug file for each monitor run If a file named “details” exists in the .plusdebug directory, the monitor engine creates a new

debug file for each monitor run. Please note, that the debug files are not deleted at any time.

This has to be done manually.

Note:

The details file is deleted on UNIX systems during CALA shutdown.

Debug directory without “details” file.

10

Debug directory with details file.

11

7.2 Keep temporary files after each monitor run Some monitors store temporary information like outputs of external tools or return codes into

temporary files. Normally these files are deleted after the monitor has finished. If the temporary

information has to be observed in a debug scenario there is a possibility to keep these files.

To enable this feature a file named “tempfiles” has to be created in the .plusdebug directory.

The number at the end of the filename identifies the process ID of the monitor that created the

temporary files. Even if several instances of the same monitor are running it is still possible to

differentiate between the temporary files.

Note:

Like the file “details”, the file “tempfiles” will be deleted during CALA shutdown on UNIX

systems.

It is possible that passwords are shown in clear text within the temporary files.

12

8 Activate the CALA_REX Client Debugging In some scenarios it is necessary to debug the CALA_REX Client. This would be the case if

there is a problem with the file transport during a client installation or update, a reconfiguring of

the client or if tasks are not executed. The created logfile needs a solid knowledge of the

CALA_REX architecture but it is important to know how this logfile is created in case the IBM or

CENIT support requests a CALA_REX client log.

To activate the CALA_REX Client debugging open the <install

directory>/cala_rex/cala_rex_cli.cfg file and add the two marked lines.

Notes:

The logfile keeps growing until the two parameters added to the cala_rex_cli.cfg are

removed again. Please make sure that enough space is available

It is also possible to specify an absolute path for the logfile. If no absolute path is defined,

the logfile will be created in the cala_rex directory.