From RTSC-Pedia

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC

Using xdc.runtime Logging/Example 5

Controlling Logging

Controlling Logging

It is possible, both at runtime and through static configuration, to control which log statements are actually logged by your application. This is important in managing the space within the log buffers on the target as well as in minimizing the bandwidth required to move the records off of the target to any realtime analysis tools.

There are three main ways in which events can be filtered on the target.

1. Filtering based on the category of an event
2. Filtering based on the level (detail level, priority, etc.) of an event
3. Filtering based on the module which the event is logged from

Event Categories

Every Log Event is defined with a particular category, defined by the xdc.runtime.Diags module. For example, the STATUS category is used for error and warning type events, the ANALYSIS category is used for events related to benchmarks and performance analysis, and the INFO category is used for generic informational events.

Every module has a diagnostics mask which contains a bit representing each of the event categories, and these bits can be enabled or disabled both at configuration time and at runtime. This allows event categories to be enabled or disabled on a per-module basis.

Event Levels

Events may also represent different "levels" of information. Depending on the category of the event, there may be different priority levels of events, or there may be events which provide different levels of detail.

For every event category, there are four event levels. These levels form a hierarchy, so that LEVEL1 is the highest and LEVEL4 is the lowest. If the filtering level is set to LEVEL2 for a given category, then only the events in that category which are LEVEL1 or LEVEL2 will be logged.

See Diags.EventLevel for the definition of the event levels.

Unlike the event categories, which are enabled and disabled on a per-module basis through the module diagnostics mask, the event filter levels are handled by the ILogger implementation. Event level filtering is considered an advanced feature, and not all ILogger implementations provide support for it, only those which also implement the xdc.runtime.IFilterLogger interface. The xdc.runtime.LoggerBuf module supports event level filtering.

Event Filtering Example

var Log = xdc.useModule("xdc.runtime.Log");
var Diags = xdc.useModule("xdc.runtime.Diags");
 
/* Configure logging for xdc.runtime.Main */
var Main = xdc.useModule("xdc.runtime.Main");
 
/* Use the LoggerBuf ILogger service provider */
var LoggerBuf = xdc.useModule("xdc.runtime.LoggerBuf");
 
/* Create and bind a logger for Main */ 
Program.global.logger = LoggerBuf.create();
 
Main.common$.logger = Program.global.logger;
 
/* Enable the USER1 event category for Main. */
Main.common$.diags_USER1 = Diags.RUNTIME_ON;
 
/* Disable USER2 events of all levels for Main. */
Main.common$.diags_USER2 = Diags.RUNTIME_OFF;
 
/* We must enable filtering by level. */
LoggerBuf.filterByLevel = true;
 
/* Filter out all USER1 events below LEVEL2. */
LoggerBuf.level1Mask = 0;
LoggerBuf.level2Mask = Diags.USER1;
LoggerBuf.level3Mask = 0;
LoggerBuf.level4Mask = Diags.ALL_LOGGING & (~Diags.USER1);

The configuration contains the following important settings:

1. We choose which event categories to enable or disable. We enable USER1 in 1, and disable USER2 in 2. All categories except STATUS are disabled by default, but we explicitly disable USER2 here for clarity.
2. We enable filtering by event in 3. Since this is considered an advanced feature, it is disabled by default in order to save on the overhead of filtering.
3. We configure the LoggerBuf module's event level filtering in 4. For all categories except USER1, we set the filter level to LEVEL4 so that events of all four levels are logged. To demonstrate the level-based filtering, we set USER1 to LEVEL2, so that only LEVEL2 and above events will be logged in this category. Note that these filtering settings are global and affect all modules.

#include <xdc/std.h>
 
#include <xdc/runtime/Log.h>
#include <xdc/runtime/LoggerBuf.h>
#include <xdc/runtime/Diags.h>
 
#include <xdc/cfg/global.h>
 
extern const LoggerBuf_Handle logger;
 
int main(int argc, String argv[])
{ 
    /* Print USER1 category events with each of the four levels. */
    Log_print0(Diags_USER1 | Diags_LEVEL1, "A USER1 category, LEVEL1 event.");
    Log_print0(Diags_USER1 | Diags_LEVEL2, "A USER1 category, LEVEL2 event.");
    Log_print0(Diags_USER1 | Diags_LEVEL3, "A USER1 category, LEVEL3 event.");
    Log_print0(Diags_USER1 | Diags_LEVEL4, "A USER1 category, LEVEL4 event.");
 
    /* Print a USER2 category event. */
    Log_print0(Diags_USER2 | Diags_LEVEL1, "A USER2 category, LEVEL1 event.");
 
    /* Flush the logger to see the records printed out. */
    LoggerBuf_flush(logger);
 
    return (0);
}

The application C code contains some arbitrary Log_print statements which demonstrate the effects of filtering. Based on the configuration, USER2 events will not be logged, and only USER1 events of LEVEL2 or higher will be logged. When we flush the LoggerBuf to see the records printed out, we see that the filtering has taken affect and there are only two records in the output.

#0000000001 xdc.runtime.Main: A USER1 category, LEVEL1 event.
#0000000002 xdc.runtime.Main: A USER1 category, LEVEL2 event.

See also

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC