How to Enable Tracing

Enabling a trace means that the trace adds trace packets to the output. A disabled trace adds no trace packets to the output. There are two options to enable tracing in the source code or component, depending on the tracing requirement.

To enable tracing at build-time, the Instrumentor has to include the #define SYMBIAN_TRACE_ENABLE flag in the relevant source code (file) of the project. If it is not included, all traces will be excluded at the build time and it will not be possible for a Trace Collector to gather any trace information regardless of the filter settings in ULogger.

If the requirement is to enable tracing in all the files in an executable, the Instrumentor can achieve this by adding MACRO SYMBIAN_TRACE_ENABLE to the MMP file of the project. Further, at compile time, a Trace Collector can enable the pre-instrumented fast kernel traces by following the procedure given in Base How to BTrace.

To enable tracing at run-time, the Instrumentor has to have enabled traces at the build-time. That is, if the traces are enabled at build-time, the Trace Collector can enable or disable any traces at run-time. But if the traces for a particular component are disabled at build-time, the Trace Collector cannot enable them at run-time.

Considerations

Before enabling trace points, the Trace Collector has to consider the following two options of outputting traces :

• Outputting all traces from a component or a set of components: After the traces have been enabled at build time by the Instrumentor, the Trace Collector will be able to generate the trace packets when the instrumented component is executed, provided the ULogger engine is configured to filter in all of these traces. For more information on ULogger configuration file, see How to use the ULogger configuration file.

• Outputting some of the traces (subset) from one or more components: The Trace Collector can achieve this by enabling or disabling the predefined primary and secondary filter combination used within the instrumented component. The primary and secondary filter combination can be set by using the Configuration file or the ULogger client API.

  The Trace Collector is able to turn on any combination of filters for a component, according to the scenarios presented in the Relationship between primary and secondary filters section in Key concepts and terms.

With the Unified Trace solution, the Trace Collector can obtain trace data during early boot by using the uloggersysstarter.exe executable file and the default configuration file (Z:\private\10273881).

To enable early tracing, the Trace Collector has to add uloggersysstarter.exe to the start-up module, which is relevant to their specific start-up mode, platform, and device.

Note:This module is responsible for coordinating the launch of all ROM-based components that must be available at device startup. For Symbian reference hardware it is provided by the optional replaceable system starter module.

Tracing during boot will then use the uloggerconfig.ini ULogger configuration file to determine what traces to output and how to do so. So it is important that the Trace Collector or ROM creator builds the correct one into the ROM. For more information on syntax and the behaviour of the, see ULogger command syntax.

Limitation

If there is a failure, the ULoggerSysStrater module does not report any errors to the Trace Collector, as there is no user interface at early device startup. The only indication of failure is that there is no log file. The failure can arise due to the following reasons:

• Non-availability of the trace server as the ULoggerServer or the ULoggerClient module do not exist on the ROM build.

• A corrupt or missing pre-defined configuration file.

• An invalid configuration setting.

See also

• How to insert trace points in a component

• How to output trace data