Overview

Overview
Prev	Appendix E. GTMPCAT - GT.M Process/Core Analysis Tool	Next

gtmpcat is a diagnostic tool for FIS to provide GT.M support. It gathers extensive diagnostic context from process dump (core) files and from running processes. This diagnostic information permits FIS to respond more quickly and successfully with root cause analysis of issues for which you engage with GT.M support.

Starting with GT.M V6.3-002, each GT.M release includes a gtmpcat_for_{release} kit which contains the files required to run gtmpcat for the released GT.M version. install_gtmpcat.sh script installs the gtmpcat files in $gtm_dist/tools/gtmpcat. After installation, use $gtm_dist/gtmpcat to run gtmpcat. Note that the gtmpcat_for_{release} kit does not contain the files necessary for analyzing other GT.M releases. Full gtmpcat releases contain these files for all supported production GT.M releases as of the gtmpcat release date.

	Important
	The local variables of a GT.M process may contain restricted information, such as protected health care or financial data. Under your direction, gtmpcat either ignores (the default) or accesses the contents of local variables.

The gtmpcat program is itself written using GT.M and requires:

GT.M V5.3-004 or later when run in M mode (may misrepresent UTF-8 information if present), or
GT.M V5.4-002 or later when run in UTF-8 mode

However, gtmpcat can analyze core files and processes from GT.M V5.1-000 or later - there need not be a relationship between the GT.M release used to run gtmpcat, and the GT.M release of a core file or process analyzed by gtmpcat.

gtmpcat requires the presence of an appropriate system debugger (for example, gdb on Linux (x86 and x86_64) or dbx on AIX). In operation, gtmpcat attaches to a system debugger, and directs it to extract information from a core file or live process.

This appendix discusses gtmpcat and how to use it.

	Caution
Albeit small, there is a non-zero risk of premature process termination when attaching to a live process with a debugger which is what gtmpcat does when it is not directed to a core file. This risk cannot be eliminated. If problem diagnosis requires attaching to a live process, FIS recommends attaching to an expendable process, or to one in a testing environment. Use gtmpcat on a production process when you have considered all your options and carefully determined that is the best alternative.

Caution

Albeit small, there is a non-zero risk of premature process termination when attaching to a live process with a debugger which is what gtmpcat does when it is not directed to a core file. This risk cannot be eliminated. If problem diagnosis requires attaching to a live process, FIS recommends attaching to an expendable process, or to one in a testing environment. Use gtmpcat on a production process when you have considered all your options and carefully determined that is the best alternative.