Trace Support

From RTSC-Pedia

Jump to: navigation, search
revision tip
—— LANDSCAPE orientation
[printable version]  [offline version]offline version generated on 18-Nov-2017 00:11 UTC

Trace Support

Tracing the execution of XDCscript



Trace support in XDCtools consists of two APIs, one for package producers and one for system integrators. Package producers insert trace statements in their code, and define conditions under which trace statements should print messages. System integrators enable a subset of all trace statements by selecting trace statements based on their properties.

Each trace statement has the following properties:

Package producer specifies the string printed when a trace statement is enabled. The timestamp and the capsule name are automatically added to the beginning of the trace output, and the groups to which the statement belongs are added to the end of the trace output. The message "function init() called", from a trace statement that belongs to the group "local" and "all", in the trace output is displayed as:
TIME=06:45:50.416 PM -- C:/reps/tisb/example/package.xs: function init() called (local, all)
A capsule is a file where the trace statement is located. A capsule is often a configuration time implementation of a module and has the same name as the module, with the extension .xs. However, a capsule can also be an XDCscript file that is not related to any RTSC module, or it can be a Java source file.
If the capsule with the trace statement belongs to a RTSC package, the name of the package is attached to the trace statement as a property. For Java files, this property is set to the name of the Java package.
This property is explicitly assigned to a trace statement, and it determines at which verbosity level the trace statement will be displayed.
A trace statement can belong to any number of groups. A group is simply a string defined by package producers that allows producers to group related trace statements, distributed across different modules and packages, into trace units that can be disabled or enabled as a whole.

Trace Activation

For users who do not need a fine-grained control of the trace output, XDCtools supports an environment variable XDC_TRACE_ENABLE, which can be used to easily enable trace output for all commands, as well as a corresponding command line option that does the same thing but on a per command basis.

Environment variables

Environment variables.  The environment variable XDC_TRACE_ENABLE allows two special trace settings, which are a subset of trace options available through the extended trace support API described in following sections. These settings are:

Enables all trace statements, including internal XDCtools trace, at the highest level
Enables all trace statements related to loading packages

% export XDC_TRACE_ENABLE=all
c:\>set XDC_TRACE_ENABLE=all

For finer control of the trace output you can use the environment variables described below.

XDC_TRACE_ENABLE was used in previous releases as an equivalent to the environment variable XDC_TRACE_CAPSULES, which is described later in this document. Use of XDC_TRACE_CAPSULES is preferred for enabling trace in selected capsules, but the usage of XDC_TRACE_ENABLE for enabling capsules is still supported and it is described in xdc.traceEnable. The previous usage of XDC_TRACE_ENABLE and the trace support described on this page should not be used at the same time, because it can result in more or less trace being emitted than expected.

Command line options

Command line options.  Using an environment variable has the advantage that no command lines need to change in order to trace the operation of the tools. There are times, however, when it is useful to only trace the operation of an individual command. Both xs and xdc support command line options that allow you to enable trace on a per command basis.

The following xdc command line enables all trace statements:

% xdc XDC_TRACE_ENABLE="all"

The Java property xdc.traceEnable can be used to activate the trace support from xs command line:

% xs -Dxdc.traceEnable="load" ...

Package Producer API

A package producer generates trace statements from XDCscript by calling

$trace(String msg, Int level, String groups[]);

The only required argument is msg. Default value for level is 0, and if groups is left unspecified, the trace statement will belong only to the group all, which contains all trace statements. The verbosity levels are currently limited to 0, 1, and 2. The level 0 is the least verbose, while the level 2 is the most verbose.

The trace statement does not need to specify its capsule and its package because these properties are determined automatically by XDCtools.

From Java code, package producers can generate trace statements through the class Trace in the package, by calling any of the functions

Trace.print(Object thisObj, String msg, int level, String groups[]);
Trace.print(Object thisObj, String msg, int level);
Trace.print(Object thisObj, String msg);

In addition to the arguments defined for the XDCscript API, Java callers must pass the value of this as the first arguments to allow Trace to determine the caller's package and the class name, which are then used as package and capsule property of the trace statement.

In case of static Java functions, where the pointer this is not available, a new instance has to be created. For example, to add a trace statement to a static function in the class Foo(), one would call Trace.print(new Foo(), "message"). There is an additional expense of creating a new instance in such cases that should be taken into account.

System Integrator API

By default, all trace is disabled. A system integrator can enable trace statements by selecting values for the properties of trace statements. For example, trace can be enabled for a specific set of capsules, packages, and groups. Then, the verbosity level can be used to filter trace statement to only those at the selected level and below.

The trace support for system integrators is accessible through the XDCscript module, or through the environment and command line variables.

XDCscript Trace API

XDCscript Trace API.  The trace support available through the Trace module allows listing capsules, packages, and groups for which the trace should be enabled, as well as setting the verbosity level.

var Trace = xdc.module("");
Trace.setLevel(Int n);
Trace.packageEnable(String pkgs[]);
Trace.groupEnable(String groups[]);
Trace.capsuleEnable(String caps[]);

Trace.setLevel() limits trace output to trace statement tagged with level equal or lower than n.

Trace.packageEnable() enables trace output from all packages whose names match an element in pkgs. The strings from pkgs are treated as JavaScript regular expressions, and partial matches against package names are accepted. For example, to enable trace from all packages from the namespace ti.sdo, it is enough to add the string ti.sdo to the string array pkgs. The returned value contains a list of previously supplied strings, if any. The newly supplied list replaces the existing list.

Trace.groupEnable enables trace output from all groups that match an element in groups. The strings from groups are treated as JavaScript regular expressions, and partial matches against group names are accepted. There is a default group all, which allows the system integrator to enable all trace statements by calling Trace.groupEnable(["all"]);. The returned value contains a list of previously supplied strings, if any. The newly supplied list of groups replaces the existing list.

Trace.capsuleEnable enables output from all capsules that match an element in caps. The parameter caps is treated as a list of JavaScript regular expressions, therefore it does not have to contain the whole name of a capsule to match it. The returned value contains a list of previously supplied strings, if any. The newly supplied list of capsules replaces the existing list.

Each function that enables trace can query the existing list of supplied strings without changing the list. That can be achieved by invoking the functions with an empty array as an argument. To clear a list, functions must be invoked with an argument that contains only one element, an empty string.

var currentList = Trace.capsuleEnable([]); // returns the current list
Trace.capsuleEnable([""]);                 // clears the list
Advanced environment variables

Advanced environment variables.  The following environment variables correspond to the functions in Trace:

It can also be set through Java property xdc.traceLevel.
It can also be set through Java property xdc.traceCapsules.
It can also be set through Java property xdc.tracePackages.
It can also be set through Java property xdc.traceGroups.

XDC_TRACE_LEVEL accepts an integer, while the other three variables accept a list of strings separated by ';'.

Java properties can also be used to activate the trace support from xs command line. For example, to activate trace for all packages at all levels, a user could type:

% xs -Dxdc.traceLevel=2 -Dxdc.traceGroups="all" ...

XDCtools Trace Groups

XDCtools core packages contain trace statements that can help debugging of XDCscript files. These statements belong to the following predefined trace groups:

This group contains all XDCtools trace statements. When xdccore is enabled at the highest verbosity level, all trace messages from XDCtools core packages are printed.
This group enables trace messages that display libraries returned from invocations of getLibs() functions.
This group displays the name of a package loading another package, the name of the loaded package, and the repository from which the package is being loaded.
This group enables messages that are printed when the function xdc.useModule() is invoked on a module, and when a module's module$use function is invoked.
By default, the stack trace in error messages displayed by XDCtools exclude the files from XDCtools core packages. However, if the trace group xdcerror is enabled, the stack trace includes all files.

For example, the following command line enables trace from both xdcerror and packageLoad groups:

% xdc XDC_TRACE_GROUPS="xdcerror;packageLoad"
% xs -Dxdc.traceGroups="xdcerror;packageLoad"


Tracing everything

Tracing everything.  The easiest way to enable all trace statements is to use the environment variable XDC_TRACE_ENABLE. The following command line enables all trace statements:

% xdc XDC_TRACE_ENABLE="all"

The Java property xdc.traceEnable can also be used to activate all trace statements from xs command line:

% xs -Dxdc.traceEnable="all" ...

Alternatively, various combinations of the other trace environment variables can achieve the same effect. Environment variables have the advantage that you do not need to change any files or command lines. On the other hand, they apply to all subsequent commands and may result in producing more trace information than desired.

It's also possible to enable trace from within XDCscript itself. This can be handy when you want to enable trace only for specific portions of a script's execution. The special group "all" can be used to enable trace for all groups but, to get all trace output, you must also set the trace level to 2:

var Trace = xdc.module("");
Tracing a specific package

Tracing a specific package.  If the package pkgA contains the file package.xs with the following content:

function init()
    $trace("init ...", 0, ["pkgInit"]);
function close()
    $trace("closing ...", 0, ["pkgClose"]);
function validate()
    $trace("validating ...", 1, ["pkgValidate"]);

The configuration script

var Trace = xdc.module("");

or the command line:

% xs -Dxdc.tracePackages="pkgA"

generates the following trace output:

TIME=10:36:46.730 AM -- C:/rep/pkgA/package.xs: init ... (pkgInit, all)
TIME=10:36:46.860 AM -- C:/rep/pkgA/package.xs: closing ... (pkgClose, all)

Notice that the output does not show output from the validate() function. This is because the trace level passed to $trace() is 1 and the default trace level is 0. In this example, to see output from all $trace statements you must also set the trace level to 1 (or more). For example, the command line:

% xs -Dxdc.tracePackages="pkgA" -Dxdc.traceLevel=1

generates the following trace output:

TIME=10:43:36.804 AM -- C:/rep/pkgA/package.xs: init ... (pkgInit, all)
TIME=10:43:36.934 AM -- C:/rep/pkgA/package.xs: closing ... (pkgClose, all)
TIME=10:43:37.555 AM -- C:/rep/pkgA/package.xs: validating ... (pkgValidate, all)
Tracing a specific group

Tracing a specific group.  With the same package.xs as in Example 1, the configuration script

var Trace = xdc.module("");

or the command line:

% xs -Dxdc.traceGroups="pkgValidate" -Dxdc.traceLevel=1

generates the following trace output:

TIME=10:54:02.255 AM -- C:/rep/pkgA/package.xs: validating ... (pkgValidate, all)
Enabling full stack traceback

Enabling full stack traceback.  By default, all stack traceback output is filtered to eliminate internal XDCtools stack frames. You can disable this filtering by enabling the trace group "xdcerror".

% export XDC_TRACE_GROUPS=xdcerror

Alternatively, this can be enabled from within a script.

var Trace = xdc.module("");

See also

XDCscript - xdc.traceEnable Enable debug trace output Client documentation for
XDCscript - Capsule-Object.$trace Print a trace message
XDCscript - Capsule-Object.$traceQuery Query whether capsule trace is enabled

Personal tools
package reference