Enabling Tracing
This topic describes how to enable tracing, view trace messages, and log trace messages.
About Tracing
Tracing is a tool for use primarily during development. Trace elements enable you to see the behavior of various elements in a production, for the purpose of debugging or diagnosis. You typically disable tracing before a production goes live.
The production trace mechanism works as follows:
-
As part of the development process, InterSystems IRIS® developers add trace elements to the appropriate areas of your code. These trace elements (potentially) write trace messages at runtime. See Adding Trace Elements.
Note that these are messages only in a general sense; trace messages are simply strings and are unrelated to Ens.Message and its subclasses.
-
As part of the configuration process, do the following:
-
Configure the production to enable tracing. This step means that, at runtime, the trace elements are executed (rather than being ignored).
-
Optionally enable logging for the trace messages. This step writes trace messages to the Event Log.
-
Optionally configure the applicable business hosts to run in the foreground so that you can see trace messages in the Terminal while the production is running. See the last section.
-
You typically disable tracing before a production goes live.
Enabling Tracing
By default, all user trace elements are enabled. You can also enable tracing of various system events.
To do so, set values for some or all of the following nodes of the ^Ens.Debug global:
Node | Purpose |
---|---|
^Ens.Debug("TraceCat") | Controls tracing overall as follows:
|
^Ens.Debug("TraceCat","bproc") | Enables or disables system traces from business processes.
For this node and all the rest of the nodes in this table, if the node value is 1, the specified traces are enabled. If the node value is 0, these traces are disabled. This node is ignored if the parent node value is 0. |
^Ens.Debug("TraceCat","connwait") | Enables or disables system traces from adapters waiting to connect. |
^Ens.Debug("TraceCat","exterr") | Enables or disables system traces showing errors from external systems. |
^Ens.Debug("TraceCat","file") | Enables or disables system traces from file read or write operations. |
^Ens.Debug("TraceCat","ontask") | Enables or disables system traces from business host framework events. |
^Ens.Debug("TraceCat","parse") | Enables or disables system traces from virtual document parsers. |
^Ens.Debug("TraceCat","protocol") | Enables or disables system traces of sequence numbers from the MSH segment in HL7 messages. |
^Ens.Debug("TraceCat","queue") | Enables or disables system traces related to message queue management. |
^Ens.Debug("TraceCat", "sql") | Enables or disables system traces from processing events of the SQL adapter. |
^Ens.Debug("TraceCat","system") | Enables or disables general system trace elements. |
^Ens.Debug("TraceCat","timing") | Enables or disables system traces providing information about duration of calls. |
^Ens.Debug("TraceCat","transform") | Enables or disables system traces about DTL data transformations, apart from errors. |
^Ens.Debug("TraceCat","user") | Enables or disables user traces. |
^Ens.Debug("TraceCat","xform") | Enables or disables system traces about errors in DTL data transformations. |
For example, to enable tracing related to message queue management, enter the following command in the Terminal, in the appropriate namespace:
set ^Ens.Debug("TraceCat","queue")=1
Also see Enabling %ETN Logging.
Enabling Logging for Trace Messages
InterSystems IRIS can also log trace messages (that is, write them to the Event Log). To enable or disable logging of trace messages, use the following settings:
-
For any business host, use the Log Trace Events setting. When this setting is selected, InterSystems IRIS logs all the enabled trace messages for this business host log.
-
For the production, use the Log General Trace Events setting. When this setting is selected, InterSystems IRIS logs all enabled trace messages from production elements that are not business hosts.
There is no overlap or interaction between these settings; Log General Trace Events does not override or provide a default value for Log Trace Events.
Seeing Trace Messages in the Terminal
To see the trace messages in the Terminal, do the following:
-
If you are using Windows Vista or Windows 7, enable the Interactive Services Detection Service, as follows:
-
On the Windows Start menu, go to Administrative Tools > Services.
-
Scroll to Interactive ServicesDetection.
-
Right click and select Start.
-
-
Enable the Foreground setting for the business host or business hosts in which you are interested.
When you run the production, InterSystems IRIS opens a Terminal window for each foreground business host. This Terminal window shows all enabled trace messages for that business host. It also shows all log items and alerts.
-
On Windows Vista or Windows 7, the Interactive Services Detection Service displays a dialog box to indicate that a program is attempting to display a message. Click View the Message. The Interactive Services Detection Service then displays a window that contains one or more Terminal windows.