Enterprise Content Management System Monitor 5.1 Agent Debugging Guide Revision CENIT AG Author: Stefan Bettighofer

Transcription

1 Enterprise Content Management System Monitor 5.1 Agent Debugging Guide Revision CENIT AG Author: Stefan Bettighofer

2 1 Table of Contents 1 Table of Contents Overview Definitions IBM ECM CALA_REX Agent IBM ECM CALA Monitoring Agent logctlsrc calamon ascfileread Ntevtlogread tecfmtfilt v2fmtfilt View CALA Status task Activating the task debugging Activating the monitor debugging Advanced Debugging Options for tasks and monitors Store a debug file for each monitor run Keep temporary files after each monitor run Activate the CALA_REX Client Debugging

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 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 calamon The calamon executes the monitors, creates event and sends them to the ECM SM Server ascfileread The general logfile reader of the ECM SM CALA Monitoring Agent ntevtlogread The logfile reader especially for the Windows Event Log entries tecfmtfilt The logfile parser for the logfiles that use a Tivoli format file v2fmtfilt The logfile parser for the ECM SM own format file. (v2s) 3

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. 4

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 5

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. 6

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 7

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. 8

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. 9

10 Debug directory with details file. 10

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. 11

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. 12