Using Traces

Introduction

Arcane provides a utility class (Arcane::TraceAccessor) for displaying traces in modules. This class allows managing several types of traces: information, errors, ...

If, in the module descriptor, the parent-name attribute of the module element equals Arcane::BasicModule (the default), traces are automatically available.

Traces are used like classic streams in C++, thanks to the << operator.

For example, to display an information trace:

Arcane::TraceAccessor::info() << "Ceci est un message d'information";

All C++ types that have the operator<<() operator can be traced. For example:

int z = 3;
Arcane::TraceAccessor::info() << "z vaut " << z;

Note that a carriage return is automatically performed between each message. Consequently, adding a carriage return at the end of a trace causes a line break.

Trace Categories

The trace methods are:

• Arcane::TraceAccessor::info() for information traces,
• Arcane::TraceAccessor::debug() for debug traces,
• Arcane::TraceAccessor::log() for log traces,
• Arcane::TraceAccessor::warning() for warning traces,
• Arcane::TraceAccessor::error() for error traces,
• Arcane::TraceAccessor::fatal() for fatal error traces, which stops execution. It is also possible to use the ARCANE_FATAL() macro to achieve the same behavior. The advantage of the macro is that it explicitly tells the compiler that an exception of type Arcane::FatalErrorException() is being thrown, which can help avoid compilation warnings.

Warning or error traces (Arcane::TraceAccessor::warning(), Arcane::TraceAccessor::error(), and Arcane::TraceAccessor::fatal()) are always displayed. For information (Arcane::TraceAccessor::info()) and debug (Arcane::TraceAccessor::debug()) traces, the behavior depends on whether the execution is sequential or parallel and whether ARCANE is compiled in debug or optimized mode:

• in optimized mode, debug traces are never active. Furthermore, the debug() method is replaced by an empty method, meaning it does not consume any CPU resources.
• in optimized mode, by default, information traces are only displayed by subdomain 0. This behavior is configurable (see section Trace Configuration).
• in debug mode, traces from subdomain 0 are displayed on standard output. Traces from other subdomains are written to a file named 'outputn', where 'n' is the subdomain number.

Log traces are written to a file in the 'listing' directory, named 'log.n', where 'n' is the subdomain number.

There are 4 methods for parallel trace management:

• Arcane::TraceAccessor::pinfo() for information traces,
• Arcane::TraceAccessor::pwarning() for warning traces,
• Arcane::TraceAccessor::perror() for error traces,
• Arcane::TraceAccessor::pfatal() for fatal error traces, which stops execution.

For pinfo(), each subdomain displays the message. For the others (Arcane::TraceAccessor::pwarning(), Arcane::TraceAccessor::perror(), and Arcane::TraceAccessor::pfatal()), this means that each subdomain calls this method (collective operation), and therefore only one trace will be displayed. These parallel traces can be useful, for example, when you are certain that the error will occur on all processors, such as an error in the dataset. You must ensure that all subdomains call the collective methods, as otherwise it can lead to code blocking.

It should be noted that if the Arcane::TraceAccessor::fatal() method is called in parallel, the processes are generally terminated without warning. With Arcane::TraceAccessor::pfatal(), it is possible to stop the code cleanly since each subdomain generates the error.

There are three trace levels for the debug category: Arccore::Trace::Low, Arccore::Trace::Medium, and Arccore::Trace::High. The default level is Arccore::Trace::Medium.

Arcane::TraceAccessor::debug(Arccore::Trace::Medium) << "Trace debug moyen"
Arcane::TraceAccessor::debug() << "Trace debug moyen"
Arcane::TraceAccessor::debug(Arccore::Trace::Low)    << "Trace debug affiché dès que le mode debug est utilisé"

Trace Configuration

It is possible to configure the desired debug level and the use of information traces for each module in the ARCANE configuration file. This user configuration file allows modifying the default behavior of certain architectural elements, such as trace display. It is named config.xml and is located in the .arcane directory of the user account running the execution.

Configuration is done using the name, info, and debug attributes of the trace-module element. This element must be a child of the traces element.

• name specifies the name of the module concerned
• info equals true if information traces should be displayed, false otherwise.
• debug equals none, low, medium, or high according to the desired debug level. Debug traces at a level higher than requested are not displayed. The high level corresponds to all traces.

Here is an example file:

<?xml version="1.0" ?>
<arcane-config>
  <traces>
    <trace-class name="*" info="true" debug="none"/>
    <trace-class name="Hydro" info="true" debug="medium"/>
    <trace-class name="ParallelMng" info="true" print-class-name="false"
                 print-elapsed-time="true"/>
  </traces>
</arcane-config>

In the example, the user requests that information traces for all modules be enabled by default, but not debug traces. For the Hydro module, information traces and debug traces up to the medium level are displayed. For the ParallelMng message class, the info and elapsed time are displayed, but not the message class name (i.e., the beginning of the line '*I-ParallelMng'.

Note

Regardless of the configuration, debug traces are not available in the fully optimized version.

It is possible to dynamically change the information of a message class. For example, the following code allows changing the verbosity level and displaying the elapsed time from a module or service, but not the message class name:

Arcane::ITraceMng* tm = traceMng();
Arcane::TraceClassConfig tcc = tm->classConfig("MyTest");
tcc.setFlags(Trace::PF_ElapsedTime|Trace::PF_NoClassName);
tcc.setVerboseLevel(4);
tm->setClassConfig("MyTest",tcc);

---

Environment Variables Command Line and Dataset