Textual Message Logging

Sparta includes a mechanism for generating textual messages that can be configurably directed to various output files to generate a textual trace of the state or events inside a simulation.

This page details the modeling view of the logging system - that is, how log messages are emitted

Logging System Goals

The Sparta logging feature exists to allow model and simulator owners to generate free-form messages of a certain 'category' from a specific point within a device tree. Each log message should be filterable by its category and origin by end-users of the simulator. Users should also have the ability to redirect log messages to any number of output files including stdout/stderr based on log message origin and category. This allows users to selectively log messages from specific subsections of the simulated system at various levels. Thus, a single simulation run can produce many log files containing any combination of messages depending on user configuration.

Logging System Design Requirements

1. Associate Log messages with a single node in a device tree
2. Associate Log messages with one or more category strings (e.g. "info", "debug", "warning")
3. Itentify, before simulator finalization, what log categories a simulation is capable of generating
4. Allow the user-configurable routing of log messages generated by a simulation to a specific set of files and/or standard streams based on the origin and category of each message.

• This should never cause duplicate messages in the same file/stream
• A client of the simulator should not be able to interfere with another's log observeration

1. Minimize performance cost of logging infrastructure when logging is disabled

Conceptual Usage

Scoped Logging

Scoped logging refers to logging message originating at a specific node in the simulation's device tree. This is the preferred means of logging as it allows log messages to be filtered by their origin. Additionaly, models generating log messages can determine if anything is observing its messages and avoid wasting time performing expensive string formatting if not

Scoped Logging Usage

1. A sparta::TreeNode must exist in a sparta device tree which will represent the context (origin) of the log message. See trees. This will typically be either a plain sparta::TreeNode or sparta::ResourceTreeNode
2. A sparta::log::MessageSource must be constructed as a child node of the context above. This must be done before the sparta finalization phase.
3. At any time, a message may be posted to this message source and if the logging infrastructure is observing this notification sourece or its parent of any number of generations, then that message will end up in a log file or standard stream.

Control of log message routing is described in the Capturing Log Messages section

Global Logging

Occasionally, a log message will be generated by some component that is not part of the simulator proper. Though this is very rare, singletons and other globally scoped infrastructure may not allow themselves to be integrated into a sparta device tree. Therefore it is possible to log through a global node instead of a location within the device tree.

Control of log message routing is described in the Capturing Log Messages section

#include "sparta/log/MessageSource.hpp"
...
sparta::log::MessageSource::getGlobalWarn() << "global warning message";
sparta::log::MessageSource::getGlobalDebug() << "global debug message";

Capturing Log Messages

Control of how log messages are filtered and routed to destination log files/streams is covered (at a low level) in the taps section. However, the sparta::app::CommandLineSimulator and sparta::app::Simulation classes assist in setting up log message observation, routing, and formatting based on command line options or manually. The Command Command Line Interface section covers this.

Usage Notes

1. Errors should generally not be captured in the log system

Implementation Notes

1. The logging system is built on the sparta notification_generation system.