How to use HDBGCTRL for SCM HServer Logging

Document ID : KB000049628
Last Modified Date : 14/02/2018
Show Technical Document Details

Description:

Beginning with SCM r12.1.00 (12.1 GA), you can use the command line utility hdbgctrl for on demand debug logging of hservers, brokers, and agents without restarting the broker or agents. This article discusses how to use it, what it does, and how it interacts with the regular logging mechanism in hserver.arg.

Solution:

SCM Server Logging

You can specify a logging level for SCM hserver processes in %CA_SCM_HOME%/hserver.arg.
The broker service must be restarted for changes to the logging level to take effect.

What does each logging level capture?

-logging=int level

Writes detailed server information to the server log. Each log level displays the information of all levels below it. The levels are cumulative not mutually exclusive.
Level=1 displays ODBC errors and any error messages written by the relational database.
Level=2 displays the product Transaction name; the date and time it started; the date and time it ended; the name of the server and process ID that processed the transaction; and the duration of the transaction in milliseconds.
Level=3 displays the executed SQL statement, when it started, when it ended, the execution time in milliseconds, and the time in milliseconds since the last completed SQL.
Level=4 displays commit and rollback statements.
Level=5 displays the results of the SQL statements being executed.

Where are the log files?

When logging is initialized at startup, it attempts to write to $CA_SCM_HOME/log. If this directory does not exist or cannot be written to by the user starting the process it will attempt to log to "./log" (a log directory at the current location). If there is no log directory at the current location, no logging will occur and no error will be displayed. This will not prevent the process from starting as this is considered a non-fatal problem.

For Windows, hserver logs are written to %USERPROFILE%\.cascm\log except if started as a service by the System account. In that case, logs are created in %CA_SCM_HOME%\log

How does hdbgctrl work?

Hdbgctrl commands are not cumulative. When a user executes a 2nd hdbgctrl command it overrides the 1st. This means you cannot execute consecutive hdbgctrl commands to monitor multiple clients. Only the most recent hdbgctrl command will be active.

There is no command to check the status of hdbgctrl, but you can grep (search) the broker log to locate the most recent call to it.

For example:

If a user executes the following debug command:

hdbgctrl -b halma12 -usr harvest -pw harvest hserver:on:2:"CREATE_PACKAGE" then the following entry will be added in the broker log

Debug Command: hserver:on:2:CREATE_PACKAGE

Search the current SCM broker log for the last occurrence of the string "Debug Command". This will be the active hdbgctrl command.

How does hdbgctrl interact with hserver "-logging=x" logging levels?

The hdbgctrl logging level overrides the -logging=X setting in hserver.arg - for the hservers it is applied to .

Hdbgctrl does not create a new hserver instance. Issuing an hdbgctrl command causes the debug control string specified to be sent to the broker. The broker holds the hdbgctrl settings in memory and passes the debug command and settings to any active hserver instance servicing requests matching the debug command string provided.

Once an hserver has processed any transaction matching the debug control string, it will continue to log based on those settings until any of the following things occur:

  • an hdbgctrl OFF command is issued

  • another hdbgctrl command is issued to replace the first

  • the broker and hserver processes are recycled.

If a server process has not served any transactions that match the debug command string, then the current "-logging=X" setting will remain in effect for that hserver, but as soon as any hserver is asked to execute a command that matches the hdbgctrl debug control string, it will begin to log with the new parameters and "-logging=X" settings will cease.

Hdbgctrl settings are stored in memory in the broker process and not in the server processes or in the database. This means that when the broker is shutdown all settings are lost.

Every transaction request sent to the broker will be checked based on the hdbgctrl setting. If the logging condition matches, the broker will add additional flags in the transaction request when it forwards it to an hserver. There is no guarantee that every matching transaction will be forwarded to the same hserver.

The debug level retained by the broker has precedence over settings in hserver.arg once activated for a given hserver process and remain in effect until a new hdbgctrl command is issued or the broker and hservers are recycled. Once an hdbgctrl command has updated the logging settings for a given hserver, all other logging specified with "-logging=X" in an hserver.arg is overridden.

Transaction logging

All SQL statements contained within one Transaction will be executed by one HServer. An SCM transaction is never split up between multiple hservers. However, one transaction is not equal to one key press or one activity within the GUI. A checkout, for example consists of many transactions and these may or may not execute on the same hserver. It is the job of the broker to distribute load and coordinate serial transactions before returning to the client.

Reference material for The On-Demand Debugger - hdbgctrl

Beginning with SCM r12.1.00 (12.1 GA), you can use the command line utility hdbgctrl for on demand debugging of hservers, brokers, and agents without restarting the broker or agents.

12.1.00 (GA) Release Notes:

Error Management - On Demand Debug Utility

The On Demand Debug Utility turns on the debug trace for the broker, the hserver, and the agent at run time without restarting the processes. This utility can control the broker qtrace and the agent trlvl. For the hserver, the debug trace is transaction-based. To turn on the trace for the hserver, you specify a specific server transaction and the logging level for the debug utility. When the server receives the specified transaction, the trace is enabled and it is disabled automatically at the end of the transaction. The debug traces are written to the default process log file.

12.1.00 - 12.1.03 Command Line Reference Guide:

hdbgctrl Command-Debug Control

The broker -qtrace option, the hserver -logging option, and the remote agent -trlvl option can be turned on or off at runtime by using the hdbgctrl debug control utility. This utility is an administration tool, so the user must have the CA SCM administrator privileges to run this command. The trace messages are written to the default process log file.

This command has the following format:

hdbgctrl [-b name] [-rm name -rport portnumber] [-usr username] [-pw password] [-prompt] [-eh filename] [-o filename | -oa filename] [-h] debug_control_string

-b name
(Required, must specify -b or -rm) Specifies the CA SCM broker name. This option is required if the target process is the broker or the hserver.

-rm name
(Required, must specify -b or -rm) Specifies the remote agent computer name. This option is required if the target process is the agent.

-rport portnumber
(Required, must specify -b or -rm) Specifies the port number of the remote agent computer. This option is required if the agent computer name is specified.

-usr username
(Required, unless -prompt is specified) Specifies the user name for login to the broker or agent. If -usr is defined without -pw, the user is prompted for the password at runtime.

-pw password
(Required, unless -prompt is specified) Specifies the password for login to the broker or agent. To hide the password from being exposed in plain text on the command line, use the prompt option.

-eh filename
(Optional) Specifies the encrypted CA SCM or agent username-password file name. The file name used with this option contains encrypted username-password credentials and must be generated with the svrenc utility.

Note: -eh overrides -usr and -pw options. -prompt overrides -eh, -usr and -pw options.

Debug_control_string

Controls the trace options for the broker, the hserver, and the remote agent. The string has the following format:

process_name:switch:logging_level:transaction_name:client_host

process_name:broker, hserver, or agent

Specifies which process is controlled. This field is required for all target processes.

switch: on or off

Specifies enable (on) or disable (off) the trace for the target process. This field is required for all target processes.

logging_level: 1-5 for hserver, 1-3 for agent

Specifies the level of the trace (-logging for hserver and -trlvl for the agent) for the target process. This field is required if the target process is the hserver or the agent and the switch is on. This field is ignored if the target process is the broker or the switch is off.

transaction_name: hserver transaction name or "all" for all transaction types

Specifies which transaction the hserver trace is activated. The trace is turned off automatically at the end of the transaction. This field is required for the hserver. The field is ignored for the broker and the agent. Only one transaction type can be activated for debug trace at any time unless "all" is specified for the transaction_name.

client_host: client_machine_name

Activates the hserver trace only if the transaction request is from the specified client and the transaction matches the specified transaction name. This field is optional for the hserver and is ignored if the target process is the broker or the agent.

Examples: hdbgctrl Command

hdbgctrl -b scmbroker -usr scmuser -pw passwd broker:on
hdbgctrl -b scmbroker -usr scmuser -pw passwd broker:off
hdbgctrl -b scmbroker -usr scmuser -pw passwd hserver:on:4: LIST_VERSION_IN_VIEW
hdbgctrl -b scmbroker -usr scmuser -pw passwd hserver:on:4: LIST_VERSION_IN_VIEW:machine_A
hdbgctrl -b scmbroker -usr scmuser -pw passwd hserver:off:4: LIST_VERSION_IN_VIEW
hdbgctrl -rport portnumber -rm scmagent -usr scm agent username -pw scm agent password agent:on:1
hdbgctrl -rport portnumber -rm scmagent -usr scm agent username -pw scm agent password agent:off:1