|
ALib C++ Library
|
by |  |
|
Loading...
Searching...
No Matches
|
ALib C++ Library
|
by | |
|
ALox is a module of the general purpose C++ library ALib C++ Library. Nowadays it is fully integrated in ALib, and has the status of what we call an ALib Camp. Historically, since 2013, ALox was developed in parallel for programming languages C# and Java likewise. While the JAVA and C# versions are not maintained anymore since 2018, they are still available and found with this link: ALox for C# and Java. The C++ version is and will be continuously maintained.
Within ALib, module (or "Camp") ALox provides an ecosystem to support structured and well organized log output. The library attempts to make debug logging as easy and lightweight as possible. One of the goals we want to achieve is that developers, once using the library, just stop to put any temporary debug output statements into their code, but do it all with nice, readable, configurable, reusable logging statements that can be temporarily or long-term switched off and that are furthermore automatically pruned out of release versions of the application.
On the other end of the list, we want to enable release logging for applications in production systems (release versions) to collect mission critical metrics and data from the field. Basic support for release logging is here today already. The introduction of new features and concepts in the area of release logging will also support debug logging aspects of ALox. Therefore the natural path of evolution of ALox is "debug features first, release features next".
The rather simple class structure and architecture of the library allows users to easily extend ALox. If you extended ALox by new Loggers or features, you are welcome to contribute your innovations to this open source project.
ALox is designed to support different log streams. A log stream is a destination of log messages and can be the IDE console, the terminal console, a file, a web service or anything that accepts data streams. Abstract class detail::Logger represents such a log stream. While some implementations of class Logger are provided with the ALox package, the system allows custom implementations of Loggers that log information to any 'data drain' in any format you like.
When using ALox, there is not much interaction with classes of type Logger, though. The reason for this is, that the data that is logged, can be directed into multiple Loggers at once. Therefore, the API interface for executing the logging itself, is residing somewhere else and internally, ALox dispatches the log data to the list of Loggers in question.
The interaction with class Logger (and its derived types) is therefore limited to the following:
What can be described as "the data that is logged", is called a 'Logable' or, as it may be more than one, the Logables in ALox. While most logging APIs are restricted to logging text messages, ALox is not. Still, the usual case is logging text messages, but the architecture of ALox allows logging an arbitrary amount of objects of arbitrary type.
Because C++ is a very strictly typed language, a lot of prerequisites need to be in place before it is possible to (safely) drop any sort of object into a logging interface. These prerequisites are created in other ALib Modules, that ALox builds upon. The most important of them are:
In short, ALib Boxing is "std::any on steroids", allowing to pass any sort of object and "box" it together with runtime type information. Interested users might consult the Programmer's Manuals, tutorials and reference documentation of the ALib Modules linked above. For now it is enough to know: ALox accepts any sort of object to be dropped as Logables into the logging system and internally can access the data in a type safe way, just as it is true with higher-level programming languages like Java or Python. And, besides the ability of getting type information from the "boxes" and to "unbox" their values, ALib Boxing allows defining and invoke some sort of "virtual methods" on boxed values (this is why this concept is much more than what std::any provides.
In the case of textual logging (the standard case, including 'simple' debug logging), all Logables are processed by instances of derived types of class Formatter. This is why ALox logging optionally allows passing format strings which include placeholders and formatting options, like field width, alignment, tabulators, quotes, and much more. If no format string is detected, string representations of the Logables will be just concatenated and logged. This way, formatting the output is just an option.
And the flexibility goes even beyond that: By default, two built-in incarnations of this class are used FormatterPythonStyle and FormatterJavaStyle. The two types are used in parallel. This means, that the already optional and auto-detected format strings may follow either the Python String Fromat Syntax, which is also similar to what C# offers, or the formatting standards of the Java language, which in turn are a little like good old printf, but of course much more powerful and also type-safe.
It can be concluded that ALox logs just anything a user passes to it as Logables: Textual or binary data and if textual, optionally accepting auto-detected formatting strings of different syntactical type!
When this manual and the reference documentation of ALox are referring to a 'Log Statement', this means a piece of (user) code that invokes an ALox interface method that potentially performs log output.
Of course, each Log Statement incorporates the provision of one or more Logables to ALox. Hence, those interface methods of the ALox API that carry a parameter named logable (or a list of those, named logables can easily be identified as methods that comprise Log Statement.
The term 'Log Domain' in ALox denotes a sort of 'key' that is used to group Log Statements into different sets. Each Log Statement belongs to exactly one specific set of Log Statements by having the same Log Domain associated.
Such association can be made by using an optional parameter named domain which is available in each interface method of the ALox API which comprises a Log Statement.
A typical sample for a Log Domain might using name "UI" with all Log Statements that concern the user interface of an application. A developer may switch Log Statements of Log Domain "UI" completely off at the moment he is not interested in UI development. Alternatively, warning and error messages might get allowed. Later, when working on UI related code again, that Log Domain may be re-enabled. If a team of developers is working on a project, each team member may configure ALox to enable those Log Domains that he is currently working on.
Although parameter domain is optional, still each Log Statement is associated with a Log Domain. The way how ALox 'magically' associates Log Statements with 'the right' Log Domain, without the need for the user to be explicit about it, is one of the features that makes ALox quite unique. More about this will be explained in later chapters of this manual.
It is very common for logging eco-systems, to implement the concept of 'verbosity levels', and ALox is no exception to this. First of all, the term Verbosity denotes an attribute of Log Statements. The values of this attribute are defined in enum class Verbosity.
Some of the interface methods that comprise Log Statements carry the Verbosity in their method name, e.g., warning() or verbose(). Other, specialized methods offer a parameter named verbosity of type Verbosity.
Besides Log Statements, Verbosity is also an attribute of Log Domains. As every Log Statement has a Log Domain and a Verbosity associated with it, ALox is able to match both values against each other to decide whether a Log Statement is executed or not.
When you think about this for a second, what is gained by this concept becomes obvious: The overall verbosity of the log output is not controlled globally but on a 'per Log Domain basis'. This allows switching the topic that an application is logging about. When interested in user interface things, a Log Domain called "UI" might be set to a 'more verbose' level, while other Log Domains are switched off or are reduced to real error messages.
As described later in this manual, the possibilities of ALox to filter the log output are even more granular and flexible.
The 'Scope' is a next attribute any Log Statement possesses. The different types of scopes are nested into each other and are a little similar to what C++ names a "scope". For example Scope::Method is similar to a local variable's scope from a C++ perspective: it is visible only in method it is declared. But still, in ALox, Scopes are different and the main reason is that ALox is not able to detect scopes in the same way as a compiler of a programming language is. Therefore, we are talking about the following language related scopes:
Besides these language-related Scopes, ALox in addition defines thread-related Scopes. Those are relating to the thread that is executing a Log Statement. There are two of them, one defined as an 'outer' Scope of the language-related set of Scopes, the other is an 'inner' Scope of those.
All information about this topic is found in chapter 5 Scopes in ALox. The corresponding enum type in the reference documentation is Scope.
Attention: now it becomes tricky! Each Log Statement belongs to a Scope, precisely, even to a set of nested Scopes. The grouping of the statements into Scopes is done automatically by ALox. The Scope is detected from the position of the Log Statement within the source code and from the thread that is executing it. Now, a Scope Domain is a default domain set by the user of ALox for a specific Scope. Once such default value is set, ALox uses this domain for each Log Statement located within that Scope. This way, Log Statements get their Log Domain associated 'automatically'.
As a sample, a Scope Domain "DB" could be set as the default Log Domain for Scope::Filename that contains code that stores and retrieves data from a database management system. Now, all Log Statements within this source file get this Log Domain automatically associated, without explicitly specifying "DB" with every Log Statement. Therefore - although each Log Statement needs to refer to a Log Domain - such domain is not needed to be added to each statement into the source code. This has several advantages: less typing, less code clutter by Log Statements, copied Log Statements magically switch their domain when 'pasted' into a different scope, and so forth.
As you see, there are two ways to assign a Domain to a Log Statement: Either by providing optional parameter domain with a Log Statement, or by setting a Scope Domain and omitting the parameter.
By having Scope Domains which associate a "default domain" with a Log Statement that resides in a certain Scope and knowing that the Scopes are nested into each other, the question is what happens if multiple Scope Domains apply to the same Log Statement? Or, a similar question: what happens if a Scope Domain is set for a Scope that a Log Statement resides in and in addition, the Log Statement uses optional parameter domain to explicitly specify a Log Domain?
The answer is: ALox concatenates all Scope Domain to a Domain Path, separated by character '/'. This means that ALox organizes Log Domains hierarchically, hence this can be seen as a tree of Log Domains. The concatenation starts from the most 'outer' Scope and ends at the most 'inner'. The value of optional parameter domain is appended close to the end - but not completely at the end.
Besides 'mixing' Scope Domains and parameter domain, ALox also allows 'overriding' Scope Domains with parameter domain.
Using the techniques in the right manner, is one of the keys to efficiently use ALox. The details of how this is done is explained in a dedicated chapter: 4 Log Domains.
The definitions and terminology that were introduced in this chapter so far should be quickly summarized. We have:
Now, the most prominent class of ALox which acts almost like a "single point of contact" comes into the game: Class Lox.
This class keeps it all together! This is what class Lox does:
It becomes clear that this class is an ALox users' main interface into logging. After ALox was set-up once (probably in the bootstrap section of a software), and Loggers are created, configured and attached to a Lox, this class is almost all that is needed across all other parts of a software. All main ALox functionality, especially the interface for the logging statements themselves is comprised in this class.
One important detail of the internal management of class Lox is the fact that it associates a separated Verbosity value for each combination of Log Domain and Logger.
The rationale behind that is easy to understand: An application that supports different Loggers at once (which happens quite quickly when using ALox), might want to log different subsets of the log messages with a different Verbosity to each of theses Loggers. For example, a Logger dedicated for debug-logging that streams into an output window of an IDE, would be desired to be generally more verbose and also switch Verbosity more frequently, than a Logger that in parallel logs into a file which is storing also logs of earlier debug sessions.
While those interface methods in class Lox which comprise a Log Statement already accept an arbitrary amount of Logables as parameters, this list can even be extended by further objects which are then all together passed to method Logger::Log of each Logger attached.
Such additional objects are called Prefix Logables. In short, ALox allows associating Logables to Scopes. This way, all Log Statements 'collect' such Prefix Logables which were defined to any of the nested Scopes in a list and passes them to the Logger. We could have named them Scope Logables or Context Logables, however, the word 'prefix' makes perfect sense with the most important type of Logables, namely strings! With logging text messages, Prefix Logables act like a prefix to a log message. All about this topic is found in chapter 7 Prefix Logables.
Another feature of ALox which leverages the concept of Scopes, is found with overloaded methods Lox::Once.
They are really 'heavily' overloaded, therefore the most simple version just accepts a Logable. With this version ALox hides the use of Scopes and offers what you would expect from the methods' name: logging a statement only the first time it is executed. The different parameters allow to cover more complex uses cases than this. All about this Log Statement is found in chapter 6 Lox::Once().
As being able to 'prune' ALox debug-Log Statements from release code, a low hanging fruit for the ALox feature list is to offer a concept for storing and using data, that otherwise would be temporary debug variables during the development process. Again, ALox Scopes are leveraged which makes the otherwise simple methods Lox::Store and Lox::Retrieve quite powerful.
All about Log Data is found in chapter 8 Log Data (Debug Variables).
While ALox claims to be lean and easy, besides these concepts explained in this chapter, it was decided that a next level of complexity is supported. The good news is: for simple use case scenarios, you do not need to know about that.
So, this new 'level of complexity' is simply introduced by the fact that it is possible, and sometimes very attractive, to create and use more than one instance of class Lox in a software. Each class is populated with Loggers and of course uses an own dedicated tree of domains.
The following paragraphs gives use cases and further background on using multiple Loxes.
There are two fundamental logging scenarios that we call debug logging and release logging.
For various reasons (performance, code size, security, etc), debug Log Statements should be disabled and removed (pruned) from the release version of a software.
To achieve all goals and provide a very simple interface into debug logging, the ALox ecosystem provides a specific purely static class Log which provides access to one instance of class Lox and to a few other static objects.
The assumption (restriction) that is taken here, is that debug logging is implemented by using one dedicated Lox. This should be sufficient for most scenarios, because, as described above, within that Lox instance various Loggers with own Log Domain settings will provide a lot of flexibility to log different types of messages into different streams and manipulate the verbosity for each stream accordingly.
To achieve efficient and complete pruning, ALox relies on a set of preprocessor macros. These macros are doubly defined:
The first set performs debug logging, hence addresses the objects of static class Log (through preprocessor symbol LOG_LOX), while the second set performs release logging, operating on the Lox (through preprocessor symbol LOX_LOX).
Another motivation for using separated instances of class Lox may be understood when thinking about use cases where things start getting critical from different point of views. For example:
It is explicitly allowed to attach a Logger to more than one Lox object. class Logger implements a mechanism to protect against race conditions in multithreaded environments as soon as such double-registration occurs. The obvious use case is again the mission-critical, separated Lox described in the previous paragraphs. A Logger that is responsible for 'standard' release logging, e.g., logging into a rolling release log file, can be attached to the 'mission-critical' Lox which holds the corresponding 'mission-critical' Logger. Now, the standard release log automatically receives a copy of the 'mission-critical' Log Statements.
The ALib Camp singleton class ALoxCamp, instantiated in global variable alib::ALOX, keeps a list of all instances of class Lox that were registered with it. Registration is done by default when constructing a Lox. The advantage of that registration is that a Lox can be retrieved by its name using ALoxCamp::Get. This is convenient because this way, references of a Lox do not have to be passed around or otherwise made public, which would clutter your own software's codebase, especially your header files.
But there might also be situations, when this 'public availability' of a Lox instance is not wanted. For this case, optional parameter doRegister may be set to false when invoking constructor Lox::Lox.
This chapter provides all details on Log Domains. Before reading it, be sure that you have read and understood the chapter 3 Terminology and Key Concepts.
Let us quickly recapture what was explained already on Log Domains in the previous chapter and the tutorials. It is very common to logging libraries to provide a system that allows controlling the "verboseness" of the log output, by matching what ALox calls a Verbosity associated to Log Statements. ALox allows dividing the overall set of Log Statements into subsets that belong to different topics or 'areas of interest'. These topics are called Log Domains and each Log Statement has one associated. Furthermore, ALox allows having multiple different Loggers performing each Log Statement in parallel. Now, ALox stores the Verbosity per combination of Log Domain and Logger.
The result is, that the Verbosity can be different not only in respect to each Log Domain but also, the same Log Domain may have a different Verbosity set for different Loggers.
The method to set such Verbosity which is found (in different, overloaded versions) in class Lox is simply called SetVerbosity(). As you see in the reference documentation of Lox::SetVerbosity, this method as a minimum requires a value for the Logger that is affected and the Verbosity that is to be set. The third parameter, the Log Domain defaults to "/" if not given. Omitting parameter domain with this method tells ALox to set all Log Domains to the same Verbosity.
This probably sounds more complex than it is. If you think about it for a second, it should become obvious. As a sample, this mechanism allows logging warning and error messages of an application of just any Log Domain to a file to have that log available across different debug-sessions, while the IDEs' console output is much more verbose in respect to those Log Domains a programmer currently is interested in.
Or, as another example, we could consider a Logger that sends alert Emails to system administrators. Of course, Emails should be sent only for very special events, e.g., when something really severe happens. You may collect these severe errors in a special domain "/ADMIN" (real-time administration errors) and exclusively activate this domain for this Email-sending Logger.
Domain names may only consist of the following characters:
'A' to 'Z','0' to '9' and'-') and underscore ('_').If one of this characters is used, ALox replaces this character with # (which, as stated above is otherwise equally not allowed) without further notice. (Also, no internal log statement is given in this case). As a result, the explicit provision of illegal domain names "ABCa$)" or "ABC<=>" will each result in the same domain name "ABC###".
One of the major design goals of ALox is simplicity. By nature simplicity is sometimes in in competition with flexibility or feature richness of an API. One way to resolve such conflicting goals is to provide features that - if not wanted or needed or not even known - are invisible to the user. The concept of hierarchical Log Domains is a good sample of how this was achieved in the ALox API design.
Consider an application with a user interface. Within the code that implements the UI, a lot of Log Statements using different Verbosities may be embedded using Log Domain 'UI'. Depending on the complexity of an application, switching domain 'UI' to a more verbose level (by setting the Verbosity of Log Domain 'UI'), might already lead to a huge amount of Log Statements. Of course, the solution is to split that domain into several ones, e.g., one for UI dialogs, one for manipulations of the main window, one for menu events and one for mouse interactions, etc. Therefore, splitting domains in subtopics is a common use case as soon as code becomes more complex. To support this use case, ALox organizes Log Domains hierarchically. The sample would lead to:
With every method in ALox that accepts a Log Domain as a parameter, instead of just one single domain name, a domain path can be used. Domains in a path are separated by a slash '/'. As soon as domain parameters contain path separators, the hierarchical domain system of ALox takes action.
The Log Domains' paths in our sample would be named:
Setting the Verbosity of a Log Domain is always done recursively for all its Subdomains (and sub-Subdomains). Let us look at a sample, how an ALox user would setup the domain tree, when debugging.
First, the setting should allow only error messages "in general", which means over all domains. Hence we provide the root domain '/', which is anyhow the default value for parameter domain:
As the interest is currently in domain '/UI/DIALOGS', we first switch '/UI' to a Verbosity that logs error, warning and info statements and then switch subdomain '/UI/DIALOGS/' to the most verbose level:
As such setting is always recursive, the order of setting domains is important. If the statements above were performed in reverse order:
the setting for domain '/UI/DIALOGS' to All would be overwritten by the setting of parent domain '/UI'.
The advantages of hierarchical domains so far are:
But the real reason, why hierarchical domains drive the flexibility of ALox really to a next level, becomes only obvious in the next chapter!
People might argue that providing a Log Domain to each Log Statement is an overhead of typing. That is true. For this reason - and many more - ALox provides the concept of Scope Domains.
Scope Domains are set using method Lox::SetDomain(const NString&, Scope). This method, along with parameter scopeDomain, requires a parameter of enumeration type Scope that determines the 'Scope' that the given domain path should default to.
Such Scope is assembled of two parts: one part that is taken from the source code information that ALox collects at compile-time with each Log Statement. The other part is related to the thread that is executing the Log Statement, hence is evaluated at runtime.
We start really simple and look at Scope::Method which denotes that the Scope Domain given with method Lox::SetDomain(const NString&, Scope) should apply to all Log Statements of the current method. Here is a sample:
This sets the domain "/MYDOM" as the Scope Domain for this method. As a result, a Log Statement that does not provide a domain uses the Scope Domain. The output could be:
ut_alox_dox.cpp:142:MyMethod [0.000 +077 µs][PROCESS][/MYDOM]#001 : This log statment uses domain /MYDOM
We have already gained some advantages from this most simple use of a Scope Domain
As we have learned above, the following two Log Statements are the same when a Scope Domain was set for Scope::Method:
But we have to be careful! The following two Log Statements are not using the same Log Domain:
As can bee seen in the output:
ut_alox_dox.cpp:170: MyMethod [0.000 +006 µs][PROCESS][/MYDOM ] #003 : This log statment uses domain 'MYDOM' ut_alox_dox.cpp:171: MyMethod [0.000 +--- ][PROCESS][/MYDOM/MYDOM] #004 : Oooops, this goes to '/MYDOM/MYDOM'!
The difference of the sample is that while we previously always used a '/' at the beginning of domains, now for parameter domain of the last Log Statement this was omitted. This caused ALox to concatenate the domain provided in the Log Statement with the Scope Domain set, to a new domain path.
This mechanism does not need too much further explanation, as this is similar to file system path usage: A Log Domain path starting with '/' is called an absolute path and one that omits the '/' character is called a relative path.
Same as with file system paths, a relative path can also be expressed with a single dot. As a Sample, domain paths "DOM" and "./DOM" are the same. The use of a leading extra 'dot'-domain in the path to signal relative domains is optional and probably a matter of taste.
More important is that ALox Log Domains also support two dots '..' in relative path names for addressing a parent domain. Later in this chapter, a sample for addressing a parent domain is shown.
While the previous sample code looked more like an erroneous use of a domain (resulting in domain '/MYDOM/MYDOM'), the following sample shows a use case of a relative domain path which absolutely makes sense:
The output would be:
ut_alox_dox.cpp:247: ReadChangeAndWriteBack [0.000 +006 µs][PROCESS][/IO/READ ] #006 : Reading file ut_alox_dox.cpp:253: ReadChangeAndWriteBack [0.000 +--- ][PROCESS][/IO/PROCESS ] #007 : Processing data ut_alox_dox.cpp:259: ReadChangeAndWriteBack [0.000 +--- ][PROCESS][/IO/WRITE ] #008 : Writing file ut_alox_dox.cpp:264: ReadChangeAndWriteBack [0.000 +--- ][PROCESS][/IO ] #009 : Success!
The previous samples used Scope::Method. Another important Scope 'level' is Scope::Filename.
As mentioned before, we are not going into the details of the extended Scope definition of ALox (those are given in 5 Scopes in ALox), but what is very important to understand is that scopes are nested into each other. We talk about outer scopes and inner scopes. As you might guess, Scope::Filename is an outer Scope of Scope::Method.
Now, Scope Domains which can be set per Scope level, are concatenated to a complete domain path. ALox starts from the 'most inner' Scope and then prepends (!) the paths of outer Scopes as long as relative domain paths are given. In other words, as soon as an absolute path is found as a Scope Domain for a scope, the further concatenation of outer Scopes' Scope Domains is stopped.
We are using the same sample as above, but this time, the public interface method internally is split into different parts:
In the constructor fo the class, Scope Domain "IO" is set for the entire class by using Scope::Filename.
When sample method ReadChangeAndWriteBack() is executed, this output is generated:
ut_alox_dox.cpp:301: checkSetup [0.000 +008 µs][PROCESS][/CHECKS ] #011 : Setup OK! ut_alox_dox.cpp:309: read [0.000 +003 µs][PROCESS][/IO/READ ] #012 : Reading file ut_alox_dox.cpp:316: process [0.000 +003 µs][PROCESS][/IO/PROCESS] #013 : Processing data ut_alox_dox.cpp:323: write [0.000 +003 µs][PROCESS][/IO/WRITE ] #014 : Writing file ut_alox_dox.cpp:330: writeStats [0.000 +003 µs][PROCESS][/STATS ] #015 : Statistics
With the takeaways from the features explained already in this chapter, the code is quite self-explanatory. Some remarks:
The usual way to use ALox is to separate the code that sets the Verbosity of Log Domains into a single location, normally somewhere in the 'boot-strapping part of a process. This is probably the same location where the Loggers used and also Lox objects are created and configured.
It is of course tempting to quickly (temporily) increase the Verbosity of the Log Domain(s) that a code unit uses while working on that code unit. Method Lox::SetVerbosity properly uses the current Scope, so that a statement like this:
properly sets the evaluated Scope Domain. However, if such code lines are inserted, they should be duly marked as 'temporary' and 'to-be-removed'.
Especially when working in a team, it is even more convenient to not even set the Verbosity of any domain from within the code, but by using external configuration data.
The separation has good reasons: A portion of the code that logs using a certain set of domains should not modify these Log Domain's Verbosity. One day such code could be moved into a library and then such changes are merely irreversible (well, in-fact this misbehavior can be 'healed', but this is also only explained in chapter 13 External Verbosity Configuration).
It was explained in section Hierarchical Log Domains, that setting the Verbosity is always done recursively for all Subdomains of the given Log Domain. The reason for this is to avoid 'random' settings as much as possible.
For convenience, Log Domains do not need to be 'registered' with ALox. As soon as an unknown Log Domain is used in a Log Statement, ALox creates a reference to this Log Domain and for each Logger in the corresponding Lox the Verbosity of the parent Log Domain is inherited.
Now, if a Log Domain setting was allowed to be non-recursive, the setting of a subdomain could have different values:
Therefore, the order of the use of a Log Domain would decide about its Verbosity.
One of ALoxs' design goals is to hide features that are not used and which are unnecessarily increasing complexity of using ALox if they are not needed (Further explained in Appendix B: Auto-Configuration and Orthogonality). For this reason, within this chapter of the manual (which is all about understand what domains Log Domain just are), a parameter of method Lox::SetVerbosity that can be omitted because it has a default value, was not even named. Using this parameter allows restricting the setting of the Verbosity of to a domain and and allows including arbitrary sets of Subdomains or not, by assigning a priority to each Verbosity setting.
Apart from lifting the always recursive Verbosity setting, the main motivation for introducing this concept resulted from the general need to prioritize conflicting settings which may come from different sources of configuration data. Therefore, if non-recursive settings are needed for any reason, refer to chapter 13 External Verbosity Configuration for explanations about how to achieve this.
As we learned, ALox allows using absolute or relative Log Domain paths. This is true for Scope Domains as well as for parameter domain in a Log Statement.
The general recommendation is to use relative paths. There are several advantages which all arise from the fact that ALox assembles the Scope Domain path by looping through all Scopes from the most inner to the most outer. As soon as an absolute path is found, the loop is aborted and concatenation stops. The benefits of keeping all Log Domain paths relative are highlighted in the next chapter (5 Scopes in ALox) when all about Scopes is explained - including an important use case that justifies absolute Log Domain paths!
ALox uses 'itself' to log information about its use. This is helpful e.g., to observe where and when a Log Domain is used for the first time or where and when a Verbosity setting is performed.
To keep the 'tree of Log Domains' clean and reserved exclusively for application specific Log Domains and to avoid accidental activation of internal log messages, ALox manages the internal Log Domains in a separated tree.
Information about how to 'address' this tree and when to use it, is explained in chapter 11 Internal Logging.
ALox uses the concept of Scopes in different ways. The most important and prominent use is to set so called Scope Domains. Those can be registered and then are used as a 'default' domain path with each Log Statement placed within the according Scope. The concept of Scope Domains has been explained already in the previous chapter (see 4 Log Domains). But to keep it simple, the full variety of ALox Scopes was not yet, explained there. This is what this chapter aims to do.
So, be sure, that you have read and understood chapter 4 Log Domains, before working yourself through this chapter. Using the more complex possibilities of scopes is optional when using ALox, so you can consider this chapter as an advanced topic.
Furthermore, there are other features in ALox that use Scopes. Those are elaborated in chapters
ALox Scopes are enumerated in enum-class Scope. The Scopes found here are separated in two sets:
Scopes are nested into each other. We talk about 'outer' and 'inner' scopes. For example the Scope of a method is nested into the Scope of the file name that the method is implemented in.
The language-related Scopes that ALox supports are (from outer to inner):
Apart from Scope::Global, to evaluate the actual Scope of an invocation of a member of class Lox, ALox needs to 'automatically' collect information of the calling entity. In ALox for C++ is this is achieved using preprocessor macros for all Log Statements.
As explained in detail in chapter 10 Differences of Debug- and Release-Logging, for release-logging, such automatic collection is not wanted. Without repeating the reasons for this here, let us emphasize the consequence:
The good news is: This is absolutely OK! The rationale for claiming this is:
The following sections describe each of the language-related Scopes in detail.
As the name of this Scope indicates, this is the 'most outer' Scope of ALox. It is always there and only one single 'instance' of it exists per Lox. In other words, all Log Statements or other invocations of ALox are executed 'within' this singleton scope.
When setting Scope Domains for the Global Scope, all Log Statements have such domain as their root-domain. (Of course, unless one inner Scope Domain or the statement itself is using an absolute domain path!).
One use case of setting a Scope Domain for Scope::Global could be described as follows: An instance of class Lox is used for release-logging of special and sparse Log Statements (e.g., logging into the operating systems' journal, aka event log). Now, in debug versions of the executable a debug-Logger is attached to the release lox (in addition to attaching it to the debug-lox), within this debug log output, all of these special Log Statements would be nicely sorted into the Scope Domain of Scope::Global, while non of the Log Statements to this release lox need to specify that domain path.
Another use case are special debug situations. Imagine a dubious behavior of a software is observed rather seldom. A programmer could register a debug Logger with Verbosity All for domain '/DEBUG'. Now, when a certain first indication for the start of the dubious behavior occurs, a setting of the Scope Domain '/DEBUG' for Scope::Global can be activated. From this point in time, all Log Statements would be activated, because all Log Statements of all code would be gathered beyond that temporary Log Domains '/DEBUG' and all Subdomains inherit its Verbosity.
This scope adresses the directory structure that a C++ source code file is located in. Unfortunately, ALox is not able to automatically gather information about the namespace that a Log Statement resides in, but if the source codes are stored in accordance to the namespaces they implement, a quite congruent behavior to the namespace scopes of C++ can be achieved with ALox Scopes.
For example, a directory tree could look like this:
/home/user/myproject/src/main.cpp
/home/user/myproject/src/ui/menu/menu.hpp
/home/user/myproject/src/ui/menu/menu.cpp
/home/user/myproject/src/ui/dialogs/about.hpp
/home/user/myproject/src/ui/dialogs/about.cpp
/home/user/myproject/src/io/sockets/http.hpp
/home/user/myproject/src/io/sockets/http.cpp
/home/user/myproject/src/io/database/mysql.hpp
/home/user/myproject/src/io/database/mysql.cpp
Using method Lox::SetDomain(const NString&, Scope) with Scope::Path instructs ALox to use the direct parent directory of a source file as the scope for the given Scope Domain. Thus, this domain is activated for all Log Statements residing in any source file of this directory.
Now, method Lox::SetDomain allows adding an integral value to the enumeration value Scope::Path and call the method with argument Scope::Path + N. This tells ALox to cut N directories from the path and hence to refer to an 'outer directory'. This way, Scope::Path can be used to denote a whole set of nested scopes! When executing a Log Statement within a source file, all Scope Domains which are set to any parent directory of the source file are applied!
Scope::Path that are higher than the number of parent-directories available to be cut, does not result in an error. Instead, an empty path name is registered and consequently, a registration with, lets say Scope::Path + 42 would simply be overwritten by a subsequent registration with level Scope::Path + 43 and the effect would be nearly similar to using Scope::Global.Scope::Filename does not really need to be explained. All Log Statement within the same source file share the same Scope::File. It is an inner scope of Scope::Path. Files with the same name, but residing in different directories have different scopes.
C++ source file names typically have an extension like .cpp, .hpp, .h, .hxx, etc. Such extension is ignored by design. This way, by setting a Scope Domain of Scope::Filename e.g., from within file 'mydialog.cpp', such setting also applies to Log Statements occurring in the corresponding header 'mydialog.hpp'. Of course, this is only true if both files reside in the same directory.
Scope::Method comprises all Log Statements which are residing in a certain method or function. This is the 'most inner' of the language-related set of Scopes supported by ALox. But it is not the most inner of all ALox Scopes, as we will learn later in this chapter.
As Scope::Method is 'language-related', its behavior is like in the programming language in respect to nested method calls: Same as a method variable is not 'visible' within other methods that are invoked from this method, a Scope Domain set in a method is not 'active' within nested, invoked methods. This of course makes a lot of sense, otherwise Scope Domains of methods would be overwritten or at least redirected by Scope Domains of a calling method.
C++ allows opening and closing 'anonymous scopes' using curly braces '{' and '}'. For example, a variable declared in such anonymous scope is not visible to the rest of the method after the anonymous scope is closed. Unfortunately, these anonymous scopes cannot be 'detected' by ALox automatically. In C++, with the help of its concept of strict 'stack-unwinding', it would be possible to extend ALox to support inner Scopes for nested blocks that automatically get unset as soon as program execution leaves an anonymous scope. In favor of keeping the different language versions compatible (and also in favor to not overcomplicate things!), this is not offered by ALox.
But there is an obvious way to reach the goal of setting Subdomains for Log Statements within a block of code: Simply equip each Log Statement of an anonymous source scope with a relative path using parameter domain. Such relative domain paths provided with a Log Statement are placed by ALox within the evaluated, resulting domain path, as if they resulted from a Scope Domain setting of an inner Scope of Scope::Method.
When reading earlier chapter 4 Log Domains and the later chapters (6 Lox::Once(), 7 Prefix Logables and 8 Log Data (Debug Variables)), you might be surprised, that the only way to manipulate a specific Scope is to do this with an invocation from within that Scope itself.
Why does ALox not provide alternative interfaces that makes it possible to explicitly address a Scope with an invocation from 'outside' of this scope? E.g., why is it not possible to set the scope for a method by naming the path, file and method?
The reason is to avoid ambiguities and misconfigurations. The source files' paths may be quite volatile things. When working in a team, or already when one person is working in parallel on two different machines (at work and at home) the paths may vary. Furthermore any sort of code refactoring in any respect would enforce a 'manual' change of scope specifications.
The errors and hassle that would quickly occur when the explicit naming of Scopes was supported by ALox would not justify the benefits.
But we do not consider this as a huge restriction. The responsibility for Log Domains names is deemed to rely in 'the hands' of the code that is defining the Log Statements using these Log Domains. The handler of a certain subset of a code within a project should know best which domains and Subdomains are to be used. As an exception, the use of rather 'global' domains that collect certain information, e.g., "/CONFIG_ERRORS", should be aligned across the team. Usually those domains are addressed using an absolute path within a Log Statement - and hence are not impacted by the Scope and potentially associated Scope Domains anyhow.
Having said this, it is agreed and and understood that the definition of Scope Domains of language-related Scopes has to appear in source code within the Scope itself - optionally within an 'inner' Scope of the Scope. For example, within a method of a class, both Scope::Method and Scope::Filename can be set.
What should be avoided are Contrary settings. If the same Scope is set with different values, the second invocation just replaces the first one. Therefore, some random behavior might appear when the settings of Scope Domains are contrary. For example, a Scope Domain for a source folder could be set from within different classes residing in or below this source folder. As a rule of thumb (to avoid double definitions), it is advised to put the registration code to the most central (important) class of such directory.
A snapshot of all current settings can be logged using Lox::State to investigate which settings have been performed. Alternatively, if the snapshot is not enough to understand what is set, overwritten and used where, a live log of ALox' internal messages can be activated to identify exactly which code lines are doing what in respect to Scope Domains. See 11 Internal Logging for more information about how to enable internal log messages.
This section adds two new Scope 'levels', named:
to the ALox Scope feature. As the name indicates, these Scopes create a reference to the thread that is executing a statement that is using values associated with such Scope.
Looking at Scope Domains, of course, they are used to add an additional component to the overall evaluated Log Domains path of a Log Statement. For Scope::ThreadOuter, such addition is performed at the beginning of the evaluated Log Domains path, directly after Scope::Global. For Scope::ThreadInner, the Scope Domain set is appended at the very end of the evaluated Log Domains path. The term 'very end' is important: This is not only the most 'inner' of all Scopes, it is appended to the assembled Log Domains path even after the optional parameter domain of a Log Statement. In other words, it could be said, that Scope::ThreadInner is even more 'inner' than the local, optional parameter domain of a Log Statement.
The whole list of Scope Domains, together with the parameter domain, which are all concatenated (as long as none of them is an absolute path) results to:
Remark: [L] and [T] here indicate language-related and thread-related Scopes.
An important use case for Scope Domains of Scope::ThreadOuter is useful in single-threaded applications, the same as in multithreaded. If a Scope Domain is set for Scope::ThreadOuter before invoking a method (and removed right after the invocation), all subsequent Log Statements are 'redirected' to the domain path specified, covering the whole call stack of nested method calls. This way, a portion of the program execution can be controlled in respect to the Verbosity of Log Statements easily. You can consider this use as being similar to Scope::Method but lasting not only for the method itself but for all statements of recursively invoked methods as well.
In multithreaded applications, Scope::ThreadOuter is typically used in situations where the log output of different threads should be separately controlled in respect to the Verbosity of their log output. Imagine a background thread that causes trouble but uses the same code and libraries that the rest of the application does. If you now would increase the Verbosity of such Log Domains where the problems occurred, the log output would be 'cluttered' with a lot of Log Statements caused by any thread of the process. Setting Scope::ThreadOuter allows 'redirecting' all such log-output of the thread in question to a dedicated root domain. Now, controlling the Verbosity of the Subdomains of this thread-specific root domain allows investigating directly what is happening there. This sample addresses debugging and probably a temporary 'redirect' of domains that is removed when a problem is fixed.
But there are also samples where a permanent setting of a Scope::ThreadOuter makes sense. Most operating systems/programming environments are using a dedicated thread implementing the user interface. Handlers of UI-events like mouse clicks are installed and executed on a per event basis. If now, with the very first UI event firing into the user code, (e.g., signaling that the application is now running, or the main window was created), a Scope Domain like 'UI' is registered with Scope::ThreadOuter, all UI related code magically logs into this domain path. As a consequence, no UI-related code like classes for dialog boxes, menu handlers, etc, need to set such domain themselves (e.g., using Scope::Path in a constructor).
Furthermore, it becomes very obvious from just looking at the Subdomains that get created, when the UI thread is tasked with things that rather should be moved to a different thread to avoid blocking the application for too long.
While technically Scope::ThreadInner is very similar to Scope::ThreadOuter, the effect and use cases still differs slightly. Instead of 'redirecting' just all log output of a thread into a new subtree of Log Domains, Scope::ThreadInner splits all 'leafs' of the overall Log Domain tree by adding a thread-dependent Log Domain to those leafs.
When we think about this for a minute, the obvious use case is to filter the log output of specific Sub-Log Domains by thread. First, when a Scope Domain of Scope::ThreadInner is set, the Verbosity of the new Subdomains will not change. This is true, because all new domains that are created by this thread are Subdomains of those Log Domains used before. And such Subdomains just inherit the setting as long as they are not controlled explicitly (as explained in 4.6.2 Why Does Verbosity Setting Always Work Recursively?). From here, specifically for this thread, the Verbosity of certain domains can now be tweaked until the right set of Log Statements appear.
Imagine a very general class providing a very general feature, hence frequently used by different parts of a software. Increasing the Verbosity of a Log Domains of such class might increase the overall log output too much. Now, by splitting such Log Domains using a Scope Domain for Scope::ThreadInner it becomes possible to either decrease the Verbosity for threads that are not of current interest or by only increasing the Verbosity of the thread of interest.
Finally it is noteworthy to mention the impact of Scope::ThreadInner being the most inner Scope Domain that is evaluated:
We learned in section 5.2.2 Scope::Path, that this Scope through the use of different parent directories may be seen as whole set of nested Scopes itself.
The same is true for Scope::ThreadOuter and Scope::ThreadInner! If multiple Scope Domains are set for one of both Scopes, instead of overwriting the previous setting (as done with language-related scopes), such Scope Domains are added to the ones that were previously set.
This is important for almost all use cases described in the previous sections.
Hereby, subsequent settings are 'inner' Scopes of the previous ones. This means, that during program execution the first Scope Domain that is set, results in a higher level within the domain tree. Subsequent Scope Domains set result in direct Subdomains of the former ones.
ALox, when passing a nulled string with parameter scopeDomain of method Lox::SetDomain removes the most recently set Scope Domain first. But also an out-of-order removal of thread-related Scopes is possible. More details on setting and removing Scope Domains for thread-related Scopes is given in the next section.
The same method, Lox::SetDomain(const NString&, Scope) which is used for language-related Scopes is used to set and remove thread-related Scopes.
If a domain path is given with parameter scopeDomain and either Scope::ThreadOuter or Scope::ThreadInner for parameter scope, then this domain path is added to the list of corresponding domains set. The list reflects a set of nested Scopes for itself.
To remove the most recently added Scope Domain, it is sufficient to do the same call, with an empty or nulled parameter scopeDomain. Again, this is the same as with removing or 'un-setting' Scope Domains of other Scope types.
For the case that the reverse order of adding and removing thread-related Scope Domains cannot be guaranteed, class Lox offers method Lox::RemoveThreadDomain which accepts the domain path to be removed explicitly as a parameter.
It was discussed in 5.2.6 How To Set Scope Domains for Language-Related Scopes, that those types of Scopes can only be set from 'within' the Scope to be set (the same or an inner Scope). This is different with thread-related Scopes. Method Lox::SetDomain(const NString&, Scope) as well as Lox::RemoveThreadDomain accept an optional parameter thread which allows explicitly providing the thread object to associate a thread-related Scope Domain to. Of course, if this parameter is omitted, the 'actual Scope', hence the current thread, is used.
When things get more complicated, same as with language related scopes, a snapshot of all current settings can be logged using Lox::State to investigate which settings have been performed.
Alternatively, if the snapshot is not enough to understand what is set, removed and used where, a live log of ALox' internal messages can be activated to identify exactly what the code is doing in respect to Scope Domains. See 11 Internal Logging for more information about how to enable internal log messages.
We want to summarize the takeaways of this chapter:
Finally we want to express an important thought: The three concepts of ALox, namely
align very nicely. Clever use of them may lead to true "emergence": Suddenly, log output provides more information than the single Log Statements' messages itself. (Similar to water, which has different "emerged" properties than the sum of properties of its molecules.)
But it should not be forgotten what the main purpose of Log Domains is: It is controlling the Verbosity of Log Statements. In other words, the main purpose of Log Domains is not to understand and analyze the calling hierarchy (call stack) a piece of code produces. While ALox may be used to help here quite nicely, there are other software tools and techniques available for accomplishing this.
Therefore our recommendation is: Do not overuse the concept of Scope Domains. With too many Scope Domains set, the original purpose of Log Domains may become harder to achieve. Already the maintenance of Verbosities may start causing some unwanted effort.
For a better understanding of what is explained in this chapter, it might be advisable to have read chapter 5 Scopes in ALox before continuing with this one. In short, at that place it is explained how ALox defines language-related Scopes (including the 'global' Scope) and thread-related Scopes. Both types are 'interwoven' and form the complete set, as denoted in enum-class Scope.
The most important use of Scopes in ALox is for setting and using Scope Domains which helps sorting and controlling the log output tremendously. Further information on this topic is found in chapter 4 Log Domains. This chapter provides details about a feature that we simple call Lox::Once.
Using ALox, you have probably come across method Lox::Once, with its various parameters and overloaded versions which omit and default the parameters.
As the name indicates, this method is used to execute a Log Statement only once. A first use case of such a Log Statement is obvious: Whenever it is interesting to know whether a piece of code was executed at least once, this Log Statement:
is the one to go. No further (debug) code needs to be added and pruned using #if / #endif clutter. Its nice and readable, just as Log Statements should be.
The concept of method Lox::Once goes quite beyond this simple sample. Before we go to the real interesting things, lets first quickly introduce other parameters that are optional to all other variations of this method:
As with all Log Statements, a domain path can be given:
Note that there is no overload available that accepts a Domain Path and defaults the verbosity to Verbosity::Info. This has technical reasons: The overload resolution would become ambiguous.
This sample above indicates a next use case besides the one asking for "was a piece of code reached once". This use case is: "Log problems or facts, which will not change in the future only once". Here, the configuration file "config.ini" contains wrong information. It is what it is. Do not tell me this twice and do not clutter the log output in subsequent execution of a software.
At this point in time, it might be worth to mention, that the counter is increased with each Lox::Once statement independently from the Verbosity setting of the effective Log Domain such statement is associated with. In other words, even if the domain was switched off (using Verbosity.Off), the counter is still increased. By the same token, if more than one Logger (or none) is attached to the Lox, still the counter is increased by exactly 1.
Then, although the method is named 'Once', parameter quantity allows specifying a different number of occurrences:
Yes, yes, not really true: when the integral value of the internal counter overflows, you'll see an next 10 log statements. The counter is implemented as int.
Finally setting the parameter to a negative value, lets ALox perform the log the first time it is invoked and after that, every n-th time (to be precise, every (-quantity)-th time).
In the introduction we have seen use cases like:
These and similar use cases are now extended from concerning one log message to a set of log messages. Let us Stick to the sample with the mis-configured config.ini:
This might be observed in two methods: when data is written or when it is read:
While this works well and we could be happy as it is, the little drawback here, is that, if both methods get executed, each Log Statement is executed once and hence, this sums up to two. For a debug-log output on a IDE console, this is not really dramatic. But there are other usage scenarios of logging (logging to a system journal, logging over the air, etc.) where ALox should be asked to avoid this.
And it can be very easily avoided:
We provide optional parameter group, both valued "INI_DIR_ERROR". Because both log statements share the same Group 'key', ALox shares its internal counter for the number of already performed logs between them.
In summary, parameter group is used to group a number of Lox::Once statements which are located in arbitrary places of a software together and count the number of overall executed logs.
For a short time, this is all to know about using Groups. But we will come back to Groups after the next section.
Instead of 'grouping' a set of Lox::Once statements by manually assigning them a group name, ALox Scopes can 'automatically' group statements which in a 'natural' way belong together. If the methods ReadData and WriteData from the previous sample reside in the same source file, the very same that was achieved using Groups, can be achieved using Scopes:
Comparing the samples, it can be observed, that parameter group of type String was replaced by parameter scope of type Scope, with value Scope::Filename. For other possible values, see chapter 5 Scopes in ALox.
From a birds' perspective, the advantages of Scopes are:
Their biggest disadvantage: There is only one Lox::Once counter per Scope. The sample above does not support two different sets of methods that independently from each other get counted.
On the other hand, the advantage of Groups is: Statements from completely different Scopes can be grouped and there is an unlimited number of Groups possible.
There is one thing, that can only be achieved with Scopes, namely with Scope::ThreadOuter or Scope::ThreadInner. This attaches the Lox::Once counter to a thread that is executing one of the statements. This opens the new use case for ALox:
As we see, using groups or using scopes have their proper use case and both have advantages and disadvantages, so why not combining them?
The parameter list of Lox::Once and some of its overloaded variants, allow to provide both, a Group name and a Scope. To understand the consequence, its best to explain how ALox internally handles Groups.
Groups of course are implemented with hash-tables. Their key is a String, the Group name, and their value contains the counter. Now, ALox (to be precise, class Lox), creates a hash-table for Group keys for each 'instance of a scope' where Lox::Once is used.
When parameter scope is omitted with Lox::Once, it simply defaults to Scope::Global, which is, as explained in 5 Scopes in ALox, a singleton for each Lox. Consequently, each and every statement belongs to Scope::Global and this is why Groups of default Scope::Global seem to work independently from any scope.
The other way round, if parameter group is omitted, then there are two options for ALox: If parameter scope is given and is not equal to Scope::Global, then ALox uses a default Group key. Because this is the same for all such invocations, the statement is bound to the given Scope and to nothing else. In the second case, when Scope::Global is given (still with no Group), ALox switches to Scope::Filename and creates the Group key from the line number of the invocation. This way, the 'parameterless' invocation of LogOnce, results in binding the counter exclusively to this single Lox::Once statement.
The truth therefore is, that ALox always combines Groups and Scopes, we just have not noticed that, yet. After having understood this, the only question is: What new use cases do we get when using Groups with Scopes other than Scope::Global? So far, we had:
With using Groups in Scopes other than Scope::Global all of the above get combined and a little more. Just for example:
It is up to the reader of this manual and user of ALox to adopt his own use cases to this list.
Unlike other methods of class Lox that comprise Log Statements which accept an arbitrary amount of logables, method Once and its overloaded variants accept only one logable. This restriction is caused by the otherwise complicated set of parameters and overloads of this method. There is an easy way out!
To supply more than one Logable, in C++ a container of type TBoxes may be passed with parameter logables:
Some combinations of Scope 'levels' and using Groups probably do not make too much sense. For example: Grouping different LogOnce statements together within Scope::Method? Well, you rather think about splitting a huge method into a bunch of smaller ones, as your method seems to have become a little complex.
If this gets all to complicated for you being new to ALox, here are some hints:
The feature of ALox called Prefix Logables covered in this chapter, builds upon the ALox concept of Scopes in a similar way as feature Scope Domains does. Therefore it is advisable to have read and understood chapters
This chapter will not repeat every detail covered already in the aforementioned chapters.
Logables in ALox are of type Box. Class Lox forwards them to its attached loggers with each Log Statement. In addition to those provided with the statement, one or more boxes might be added to the beginning of the list. We call these addable objects Prefix Logables.
Before we explain the use cases for Prefix Logables, let us begin to elaborate how those are set by the user of ALox and how ALox processes them.
With the first way of setting and removing Prefix Logables method SetPrefix(const Box&, Scope) is used. The method and its overloaded versions is very similar to method Lox::SetDomain(const NString&, Scope) used for setting Scope Domains. Besides the difference in the name, the only difference is the first parameter, which is a Logable instead of a domain path string.
All that was said about setting Scope Domains in Chapter 4 Log Domains is true for setting Prefix Logables and this should not be repeated here. The same rules for Scopes apply, including the fact that with Scope::ThreadInner and Scope::ThreadOuter, a subsequent setting of a Prefix Logable is added to a list of Prefix Logables for these Scopes, while for other Scopes, the current Prefix Logable is replaced.
Passing nullptr as parameter logable, removes the Prefix Logable from the given Scope, respectively, in the case of thread-related Scopes, removes the Prefix Logable most recently set.
The only small difference to the interface for setting Log Domains is that there is no method available corresponding to Lox::RemoveThreadDomain, which provides a little extra flexibility of maintaining Scope Domains in contrast to maintaining Prefix Logables.
Besides binding Prefix Logables to a Scope, ALox provides an alternative and this is binding Prefix Logables to a Log Domain. The method for doing this is FunctionEntry::Signature.
The method accepts a Log Domain path which may be absolute or relative. If relative the normal evaluation of a resulting domain path taking Scope Domains into account applies.
A third optional parameter allows making the setting exclusive in respect to Prefix Logables which are set according to a Scope. By default, the exclusivity is not set.
While the Log Statements accept an arbitrary amount of objects, the methods to set Prefix Logables have only one parameter. If more than one Prefix Logable is to be set, the first alternative is to set them one by one:
The second alternative is to wrap them in an object of class TBoxes. This is derived from std::vector<aworx::Box>. If this is done, ALox will "flatten" the given arrays when the Prefix Logables are passed to the Loggers. This means, instead of adding the array to the overall list of Logables, the single objects contained in the array are added:
'}'). With any sort of Log Statement in ALox, the Prefix Logables are collected according to the Scope and the Log Domain of that Log Statement. In the same fashion as Scope Domains are concatenated, ALox adds Prefix Logables to the list of Logables that are passed to each Logger instance. Consequently, the list that a Logger receives is filled as follows:
If in 6. or 7. a Prefix Logable was passed with optional parameter otherPLs valued Inclusion::Exclude, then after adding this Logable, the collection of further Prefix Logables is stopped. Because all objects are collected in reverse order, starting with objects of Scope::ThreadInner, this means that objects otherwise collected in 1. to 5. (respectively 6.) are not added. This allows having a setting of a Prefix Logable, which is bound to a domain, to 'override' those bound to a Scope.
As with any 'normal' Logable that is passed to the Logger, it is completely up to the Logger what to do with this data.
Those Logables passed with Scope::ThreadInner are appended to the list after the Log Statements' Logable and therefore should be considered a 'suffix', not a prefix. You might wonder why this whole feature is named 'prefix', especially as this term is not applicable to objects in an ordered array. The answer to this is given in the next section.
Talking about the use cases of feature Prefix Logables, we have to distinguish between logging arbitrary objects, what ALox supports and logging textual (string) messages, what is by far the most widely application for ALox.
When logging textual messages (more precisely: when using Loggers derived from abstract class TextLogger, just as all textual Loggers delivered with ALox are), the impact of Prefix Logable is simple. Class TextLogger just passes all objects found in the list of Logables to its ObjectConverter which in turn (in its default implementation) passes them to the formatters found in field StandardConverter::Formatters. This list by default, has two objects, namely of types FormatterPythonStyle and FormatterJavaStyle attached. This way, TextLogger is well prepared to assemble a nicely formatted log output, by default accepting Python formatter strings as well as the corresponding Java syntax.
This explains the term 'prefix': Apart from Prefix Logables of Scope::ThreadInner, all Prefix Logables are prefixes to the 'log message'. Those of Scope::ThreadInner are suffixes. For the architects of the ALox API it was just too teasing to name the whole concept Prefix Logables and this way being able to have - for the most obvious use case - the user code look like this:
The output will look similar to this:
ut_alox_dox.cpp:461:LogSetPrefix [0.000 +049 µs][PROCESS][/IO]#020 : Data File: Opened. ut_alox_dox.cpp:464:LogSetPrefix [0.000 +--- ][PROCESS][/IO]#021 : Data File: Read. ut_alox_dox.cpp:467:LogSetPrefix [0.000 +--- ][PROCESS][/IO]#022 : Data File: Closed.
A next use case is recursively increasing 'indentation' of the log messages, as demonstrated here:
Note that this sample is using Scope::ThreadOuter. If it was using Scope::Method it would fail, because only the thread-related Scopes allow to add multiple objects. With thread-related Scopes, this works like a 'push and pull' mechanism. Luckily, with using the thread-related Scopes, the whole indentation is automatically thread-safe!
Indentation can also be useful when adding prefixes for different language-related Scopes. For example classes whose source files are residing in nested directories (alike namespaces), might be considered core, helper tools that usually have a low Verbosity setting. It might be a good option to indent all their logging by setting a prefix for their namespace. If they need to be debugged, and their Verbosity is increased, Log Statement of those are due to the indentation still very easily distinguishable from the rest of the log output. Such structured log output can help to increase the readability of a debug-log tremendously.
As an alternative to 'indentation', think about using the escape codes found in class alib::lox::ESC. Prefixing those instead of normal strings or spaces, leads to nicely colorized or bold or italic log output, at least with text-loggers supporting such styles. (ALox provides such Loggers e.g., for ANSI consoles or Windows OS command windows.)
Use cases are depending on the application and situation. Let us touch a last one here: Consider an application that causes errors in certain situations. Let's say, a phone app seems to start logging errors 'randomly' which means, you do not know when. You suspect it happens when the network connection drops. A first quick investigation could be to add a Prefix Logable "Online: ", respectively "Offline: " as soon as the devices' OS signals a change. You simply set this using Scope::Global, or alternatively for the Log Domain where the error occurs. In the next debug-runs, you have all messages prefixed with the current state. You do not need to follow your log output 'backward' to find the most recent log message giving you information about that status. Generally spoken: Prefix Logables allow to add status information to log lines providing information collected elsewhere.
The situation with Loggers designed to log arbitrary objects is different. (How to create such custom, application specific Loggers is described in 17 Loggers and Implementing Custom Types).
If only arbitrary objects were supported in ALox and the standard textual logging would not exist as the predominant use-case, then the whole feature probably would have been named Context Logables. Instead of providing the 'context' with each Log Statement to a custom Logger, or setting it explicitly using a custom interface method of such custom Logger, arbitrary context data can be used leveraging the various Scope options.
Imagine for example a custom Logger that logs into a database. A 'context' in this case could be the database table to use. Log Statements of different Scopes would then 'automatically' direct their Logables to different tables in the database, if different Prefix Logables had been set for the Scopes.
Another sample could be logging application metrics to an online metrics-server. The parameters and information passed to the server are probably encoded in a URL. Now, the bigger parts of such parameters do not change within a context (aka Scope). Those would be passed only once per Scope to ALox using the feature of Prefix Logables. The metrics-Log Statements themselves would only carry the rest of the detailed information specific to the metrics information that are supposed to be sent.
Use cases are endless and cannot be named here, they depend the field of application that ALox is used to support.
One of the design goals of the ALox Logging Library is to avoid code clutter when using it. In a perfect world, Log Statements would be as clear and easy to read as comment lines. C++ does not provide life-cycle management for allocated data and this causes a potential problem when using Prefix Logables.
When logging arbitrary objects, the use cases touched in the previous section make it obvious that ALox cannot be responsible for life-cycle management of Prefix Logables. Therefore, if data is used as Prefix Logable which is exclusively created for that purpose (and are no general long-living objects), there is no way to avoid some extra code that creates and deletes such objects, probably enclosed by
#if defined(ALOX_DBG_LOG) // alternatively ALOX_REL_LOG, or both
...
#endif
or embedded in macro
Log_Prune( ... ) // alternatively Lox_Prune()
We think with release logging and binary object logging, both considered a 'heavy' use of ALox anyhow, extra code should not be anything to be concerned about.
With textual logging, especially in the case of debug logging, this is different. Here, the designers of ALox are concerned about extra code which increases the 'intrusiveness' of ALox! Therefore, the following rule applies. For string-type Logables, precisely such of box types nchar[], wchar[] and xchar[], ALox internally creates copy of the string provided. Of course, when such Prefix Logable is removed, ALox deletes this internal buffer. The benefit of this is huge: A user of ALox does not need to care about keeping string-type Prefix Logables 'alive' after setting them. This means, any locally assembled, short-living string can be passed to method Lox::SetPrefix and right afterwards, it can be deleted or removed by C++ from the stack if the corresponding C++ scope is left.
It is important to understand the impact:
The latter is of course a disadvantage of this design: The Prefix Logables becomes a static object that does not reflect changes of its origin object! But there is an easy way out. Remember that only boxed objects of character array types are copied. The trick to have changes of an AString instantly reflected in the logging, is to pass it wrapped in an object of type std::reference_wrapper. If this is done, the contents is not copied. Instead, a reference to the AString is boxed and any change of this object is reflected in the Prefix Logable.
The following code and its output demonstrate what was just said:
ut_alox_dox.cpp:207:PrefixLogablesLifecycle [0.000 +062 µs][PROCESS][/IO]#016 : Orig: Testlog before change of AString ut_alox_dox.cpp:212:PrefixLogablesLifecycle [0.000 +--- ][PROCESS][/IO]#017 : Orig: Testlog after change of AString (was not effecitve) ut_alox_dox.cpp:218:PrefixLogablesLifecycle [0.000 +014 µs][PROCESS][/IO]#018 : Orig: Testlog before change of AString ut_alox_dox.cpp:224:PrefixLogablesLifecycle [0.000 +--- ][PROCESS][/IO]#019 : Changed: Testlog after change of AString (now it is effecitve!)
This is what this chapter has covered in respect to Prefix Logables:
As with other features using ALox Scopes, on the first sight, this seems to be a little complicated. Especially when looking at the list given in chapter 7.3 How ALox Processes Prefix Logables. But when you look at the use cases, it becomes clear, that from the nine options of that list, mostly one is used in parallel, seldom two. Once the concept of Scope Domains is fully understood, the use of this feature and of others that leverage ALox Scopes, should quickly become very intuitive.
For a better understanding of what is explained in this chapter, it might be advisable to have read:
The concept of Log Data is a feature used for debugging. The goal that is aimed here is similar to the goal of debug-Log Statements themselves. As a reminder, those are:
Corresponding goals are aimed with Log Data. ALox provides this feature to enable the insertion of variables and data into the code that otherwise would be temporarily added for debug purposes and removed afterwards. The same as debug-logging is pruned from release executables, such variables and their use gets pruned. Therefore, such variables and use of them can stay in the code forever, and once a problem in the corresponding code section appears, no need to reinvent temporary code is needed.
A typical example for using Log Data is debug log output written by an exception handler. The code that may cause an exception, could store status information according to Scope::Method. When an exception occurs and the program execution abruptly continues within the exception handler, such information can be retrieved and corresponding log output can be generated giving more information about where and why the exception occurred.
The interface for setting and retrieving Log Data is provided with methods Lox::Store and Lox::Retrieve.
The type of data stored is Box in %ALox for C++. (What else did you expect?)
While in Chapter 6 Lox::Once() of this manual, it was explained in detail how parameters group and scope of method Lox::Once can be omitted, how one of them can be used and what happens when both are used, we do not want to repeat these details in this chapter.
Instead, we want to discuss the differences:
As a result, the use of Log Data can be summarized as follows:
For clarification, this means, that different Log Data objects are stored in different scopes even if parameters scope and key are the same. For example, an object stored using Scope.Method cannot be retrieved from a different method and will also not be overwritten within a different method. Again, the consequences and use cases of this design may become clearer when reading chapter Lox::Once.
It is important to understand that in ALox for C++, Log Data objects have to be kept in memory, if they are passed as pointers. The question if data is passed as a pointer or as a value is answered in the Programmer's Manual of module ALib Boxing.
In short, it can be said, that typically all fundamental C++ types (int, char, double, etc.) as well as pointers to those, are stored as values. The same is true for supported string types. However, in the case of strings, the "value" passed is the pointer to the start of the string in the memory, along with its length. Therefore, this memory has to be kept valid. In the case of storing an AString, the memory stored might become invalid, if the string is extended after it was stored. Be sure to understand this constraint when using this feature.
What does "logging" have to do with multithreaded applications? Quite a bit, as we will see in this chapter.
ALox is using C++ std::thread library to identify threads through dependent module ALib Threads. Basically, that module provides just a little wrapping code around what C++ offers since language version C++ 11:
As a consequence, ALox detects all those threads rightfully that are detected (detectable!) by std::this_thread::get_id(). In general this works with all major combinations of modern operating systems, C++ libraries and thread libraries. Should threads not be detected, check out whether the thread library you are using is compatible with thread tools found with C++ library "std". The other way round: if you are using a threading library that creates threads that are detected by C++ "std", then you can use ALox thread features without any further action. If not, you should consider either to switch your software to usign something that is compatible with this modern standard, or use the thread classes provided with ALib (if you use ALox, you have ALib available). But remember the latter is a quite simplified limited piece of art - enough for simple applications, but not more!
ALox collects information about the thread that was executing a Log Statement. For textual logging, struct FormatMetaInfo, which is a configuration variable and this way configurable from outside, contains information on how and where class TextLogger, writes the name of the executing thread by default. This default is defined with substring "%tN" in field Format of that variable. Now, if you want to change the name (without changing your applications' true thread name), then method Lox::MapThreadName does the job. With this method, you do not rename a thread, you just tell the Lox to provide a different name to the Loggers in future Log Statements. Thread names can be mapped for the current thread or for threads passed via optional parameter thread, respectively id.
A sample for using this method is given in the tutorial chapter 14. Name Your Threads.
With the fundamental concept of having Scopes in ALox, and in particular with the fact that ALox "interweaves" so called Scope::ThreadInner and Scope::ThreadOuter with other language-related scopes (e.g., Scope::Method) and the global Scope, ALox supports much more of multithreaded applications than just mapping new names to threads!
This is a complex topic and there is a whole bunch of chapters we have to refer you to:
To name just a few "applications" of the features described in the chapters above:
The ALox - Tutorial and most sample code in this manual, provide information about debug logging. The main goal of this chapter is to explain how to implement release logging. This might be easiest to explain when comparing both types of logging and listing the differences. (For a general definition see What do the terms "debug logging" and "release logging" mean?).
As previous chapters described, any logging with ALox is roughly performed as follows:
Now, with debug logging, there are some specialties that do not apply in release logging:
From the previous discussion about the specialties of debug logging, we can now quite easily identify how release logging differs and derive a guideline on how to implement it:
Probably just because it was easy to implement (!), the C++ version of ALox supports the optional pruning of release logging statements as well (see ALOX_REL_LOG). This might sound confusing in the first moment, but it allows creating different versions of release-executables, which is not completely uncommon. It is optional and just provides a next level of flexibility to adopt ALox to complex use cases.
In contrast to this, ALox also allows including caller information with release logging statements, by passing symbol ALOX_REL_LOG_CI to the build system. With that, information about source file names, their location, and function and method names will be included in the release executable. As this is usually not wanted, such setting is not defaultet. However, if done, language-related scopes can be used with release logging.
ALox allows usage in various fashions. By having the concept of different Loggers aggregated in one or more Lox objects, using an hierarchical structure of Log Domains, which by default inherit their Verbosity from their parent domain (and this way automatically adjust to probably unknown Subdomains), we think that a good balance of "ease of use" and "unlimited extensibility" was found with the ALox architecture.
The simple and common scenarios incorporate:
These scenarios can be addressed with a few lines of bootstrap code and a little discipline when inserting the Log Statements.
Various ways of matching use cases of complex scenarios with ALox exist. By purpose (to keep things simple) ALox is not providing extended classes, for example to allow pruning release logging as explained in the 'recipes' of the previous paragraph. However, once the basic concepts of ALox are understood, it is easy to build such extensions, tailored to the complex case itself.
Using ALox with libraries, is basically the same as using ALox in a single code entity. However, we recommend the following principles:
ALib, the general purpose C++ library that ALox is one module of many, provides a concept for writing reports. This mechanism is used to report problems in debug-versions of ALib and optionally of software using ALib. With class lox::ALoxReportWriter, ALox implements such mechanism to direct ALib reports to an ALox Logger. This is all transparently set up and destructed with methods Log::AddDebugLogger and Log::RemoveDebugLogger.
Applications that do not use debug logging may want to use methods Log::AddALibReportWriter and Log::RemoveALibReportWriter with debug-builds.
It is important to set the verbosity of the (internal) domain provided with method ALoxReportWriter::LogDomain to a proper level, to enable the logging of any reports.
A demonstration of how to do this is found in the ALox release logging sample code.
Appendix reference chapter Appendix B: Auto-Configuration and Orthogonality might hint to other differences of debug and release logging.
Well, it seems like a miracle that C++ compilers are written in C++ and looking behind the scenes it is really fine piece of software art that you discover when start bootstrapping such a system from scratch!
Well, with ALox it was much more simple: We implemented ALox and when this was done, we just afterwards added ALox Log lines into ALox code. Easy!
So, this chapter explains how these internal logs are organized and how an ALox user can work with them. A first introduction to this is given in the language-specific tutorials, chapter 16. ALox Configuration Information and Internal Log Messages.
Log Domains are hierarchically organized in ALox. All Log Domains together constitute a tree of Log Domains. Class Lox maintains the tree, inserts Log Domains 'on the fly' and manages the Verbosity on a per Log Domain and Logger basis.
For internal Log Statements, ALox uses a second, separate domain tree. The separation is made to keep the main tree of Log Domains 'free' for custom domains. If this was different, then setting the root domain as in the following sample:
would affect internal log messages as well. Because of the separation, they are not. To set or modify the Verbosity of internal Log Domains, static field lox::Lox::InternalDomains has to be used as follows:
When you check out the reference documentation as linked above, you will see that this field is a simple string "$/". Therefore, the code:
is equivalent to the previous line.
"$/" to be compatible with future versions of ALox (...or at least get a compiler error if this would be changed to something different than a string code.).This piece of information is all you need to control Verbosity of ALox internal messages.
Please Note that method Log::AddDebugLogger sets the Verbosity.Warning for the internal domain. This way, when using ALox, your debug-logger will show you errors and warnings if something goes wrong inside of ALox (e.g., when you pass wrong parameters to ALox, etc.).
For different topics, ALox uses different Subdomains for its internal logging. As usual, this allows controlling the Verbosity of the internal log output more granular then by setting the internal root domain "$/". For example, if a software uses wrong Log Domains evaluated from a more complex configuration of Scope Domains, then, to investigate into the problem, subdomain 'DMN' could be set to more verbose, while suppressing other internal messages:
The list of Subdomains used by ALox is given in the following table:
| Subdomain | Description |
|---|---|
| LGR | Used when Loggers are registered, retrieved or removed from a Lox and when the Verbosity of a Log Domain for a Logger is changed. In addition used with method Lox::SetStartTime. |
| DMN | Used when Log Domains are registered (on first use), when Scope Domains are set or removed and when Domain Substitution Rules are set. |
| PFX | Used when Prefix Logables are set or removed. |
| THR | Used with method Lox::MapThreadName. |
| LGD | Used with storing and retrieving Log Data objects. |
| VAR | Used when parsing and processing external variables. |
It is not 'forbidden' to have custom Log Statements using the internal domain tree:
Of course it is advisable to do so only if there are good reasons for that. There is one occasion where this is already done, and that is the ALoxReportWriter described in previous chapter 10.3.4 The ALib Report Writer. The report writer logs to internal domain '$/REPORT' and this makes a lot of sense, because this way, internal ALib reports are directed to the same domain tree as internal ALox logging, hence all internal logging of ALib Modules go to the internal tree.
It is absolutely OK, to register a Logger exclusively for internal domains. Methods Lox::RemoveLogger always removes the logger from both, internal and standard Log Domains.
As an alternative to internal logging, method Lox::State provides an actual snapshot of all (or selected) settings made for a Lox and its Loggers attached. Depending on the situation, each way to disclose what is going on inside ALox might help when something is irritating. As an alternative to (temporarily) adding an invocation of Lox::State to your code, ALox provides configuration variable ALOX/LOXNAME/DUMP_STATE_ON_EXIT. This allows enabling an automatic dump of the state using a command line parameter or other external configuration variable sources.
With the term "external configuration", we are addressing any type of configuration data that an application might have access to. The most common types of such configuration data are:
For reading such configuration data, ALox relies on the facilities provided by underlying utility library ALib. Configuration mechanics of ALib are gathered in module ALib Configuration. It is advisable to read its Programmer's Manual.
In short, the features of module ALib Configuration are:
It may be very obvious to the reader, but lets spend a minute and think about the relationship of ALox and applications using it.
In most use cases, the goal now is to enable ALox to access (read and write) the configuration that is already in place with the application. The huge benefit of this approach is, that no second configuration file or database is needed. And this is exactly what ALib - and therewith ALox - intends to achieve.
Then, other use cases and variants are:
Finally, as ALox is a library, there might be more than one ALox enabled software running on the same system. Now, for configuration sources like INI-files and command line parameters, this is not problematic. In the case of environment variables, it might become a problem: A variable setting here could influence more than one application if variables are not renamed on a per application basis.
Module ALib Configuration imposes a data "contract" that asks a programmer to respect priorities of variables and write values only if permission is granted. Of course, as ALox is a sibling camp, it uses the configuration system exactly as this contract expects. In particular, when using interface method Variable::Define to write configuration data, values are only written with standard priority.
Furthermore, ALox leverages the flexibility that the priorities of the ALib configuration system brings by exposing parameter priority in methods Lox::SetVerbosity and Lox::SetSourcePathTrimRule. This way, settings made 'in code' are by default overruled by any type of external configuration. If wanted, a programmer may specify a higher priority and this way either allow only certain, higher prioritized external sources to overwrite "hard-coded" values, or just completely disallow any external change.
For the user of ALox, the benefits of this approach towards external configuration data are:
After the discussion of the previous sections it should be quite straightforward to understand how ALox is to be integrated to your software in respect to external configuration data. Here are some hints:
Apply the previous two steps to one variable to redefine configuration behavior. Let's stick to the sample of having the --verbose switch. Imagine this option should get three possible values: 'silent', 'normal' and 'verbose'. The approach to take is the following:
MYAPP_VERBOSITY_1[2|3] . These custom variables contain the verbosity settings for all Log Domains for each of the three switchable verbosities"${MYAPP_VERBOSITY_1[2|3]}", also in protected mode. With "${}", a portion of a variable value can be substituted with the contents of another named variable.What is achieved here, is that there are custom 'presets' defined for the verbosities and those are all that the end-user can set!
Furthermore, if the substitution would be set to "${MYAPP_UNDOCUMENTED_SWITCH} ; ${MYAPP_VERBOSITY_1[2|3]}" then, in addition, a hidden new configuration variable is exposed. This might be used in "the field" when something goes wrong with a deployed application and more logging is wanted.
This Chapter brings us back to talking about Log Domains and their attribute Verbosity which are associated with pairs of a Log Domains and a Logger.
Setting such Verbosity by invoking Lox::SetVerbosity is easy and straightforward. However, when working in a team, different team members, working on different parts of a software, naturally are interested in different information. Now, when the Verbosity is defined in the source (preferably the bootstrap section of a software), then these would be randomly changed when checking source files in and out of a source control system. Therefore, ALox supports to read Verbosity settings from the command line, from environment variables, from an INI-file or from any other custom data source. This way, all personal changes are set outside the code - good for your team spirit!
But before we can explain how this is done, we first have to talk about priorities of Verbosity settings. This is an important prerequisite to understanding how external configuration works in ALox.
In chapter 4 Log Domains of the ALox tutorial and elsewhere in the ALox documentation, we have just not mentioned optional parameter priority of the overloaded set of methods Lox::SetVerbosity. It was silently omitted, because this parameter brings a new new level of complexity to the table. The good news is that (as explained in Appendix B: Auto-Configuration and Orthogonality) when the parameter is omitted, ALox behaves as if this feature was not existing.
So, what can we do with it? The parameter is of enum type config::Priority. From the namespace you can already tell that we are using an enumeration of sibling module ALib Configuration here! The parameter defaults to its enum element Priority::Standard. This tells us something: If we do not touch the parameter, the domain is set with only a priority a little higher than the priority of "default values". That sounds like a quite low priority, doesn't it?
When passing a higher value here by just adding + 1 to the constant, subsequent invocations for the Log Domain in question will be ignored. Let's look at the following sample:
And its output:
ut_alox_dox.cpp:1385:TestBody [0.000 +075 µs][PROCESS][/MYDOM]#005 : This line will be logged ut_alox_dox.cpp:1393:TestBody [0.000 +007 µs][PROCESS][/MYDOM]#006 : This line will be logged ut_alox_dox.cpp:1397:TestBody [0.000 +004 µs][PROCESS][/MYDOM]#007 : This line will still be logged. Domain was not switched off!
As you see, the fourth invocation of Lox::SetVerbosity is ignored, because the third had a higher priority. Also, if a setting was given on parent domain "/" with standard priority now, all other Subdomains were changed, but "/MYDOM" and its Subdomains would keep their setting.
With ALox internal logging (see 11 Internal Logging) activated, ALox nicely reports what is going on. We add line:
to the top of the sample. Now the output is:
ut_alox_dox.cpp:1408:TestBody [0.000 +103 µs][PROCESS][$/LGR]#008 : Logger "DEBUG_LOGGER": '$/' = Verbosity::Verbose(Standard). ut_alox_dox.cpp:1411:TestBody [0.000 +--- ][PROCESS][$/LGR]#009 : Logger "DEBUG_LOGGER": '/MYDOM' = Verbosity::Info (Standard). ut_alox_dox.cpp:1412:TestBody [0.000 +--- ][PROCESS][/MYDOM] #010 : This line will be logged ut_alox_dox.cpp:1415:TestBody [0.000 +--- ][PROCESS][$/LGR ] #011 : Logger "DEBUG_LOGGER": '/MYDOM' = Verbosity::Off (Standard). ut_alox_dox.cpp:1419:TestBody [0.000 +002 µs][PROCESS][$/LGR ] #012 : Logger "DEBUG_LOGGER": '/MYDOM' = Verbosity::Info (4001). ut_alox_dox.cpp:1420:TestBody [0.000 +--- ][PROCESS][/MYDOM] #013 : This line will be logged ut_alox_dox.cpp:1423:TestBody [0.000 +--- ][PROCESS][$/LGR ] #014 : Logger "DEBUG_LOGGER": '/MYDOM' = Verbosity::Off (Standard). Lower priority (Standard < 4001). Remains Info. ut_alox_dox.cpp:1424:TestBody [0.000 +--- ][PROCESS][/MYDOM] #015 : This line will still be logged. Domain was not switched off!
ALox in its internal log messages tells us explicitly, that the fourth request was ignored due to the higher priority level that the domain setting had before!
Consider the following Log Domain tree:
/UI
/UI/MOUSE
/UI/DIALOGS
/UI/DIALOGS/MOUSE
/UI/DIALOGS/KEYS
Imagine you are currently frequently switching the Verbosity of Subdomains of Log Domain '/UI' because you are currently working on the UI. Now you have a random problem with mouse event handling. As long as this problem occurs, Log Statements related to mouse event should stay Verbose. Therefore, you enable them 'permanently' by invoking
After that, any changes in parent domains, even for root-domain, will not disable Log Statements of mouse events any more. When the mouse event handling is fixed, these settings can be deleted again.
We learned two fundamantel things from the previous chapter:
Next, we take a look at the other enumeration elements of config::Priority. (Please do this now and return back to here.)
With this prioritization, module ALib Configuration provides a very natural behavior for choosing ALox Verbosities, dependent on the source of information. This should be quickly discussed on a sample:
Next morning, when everybody checks out the current codebase, all team members get theses hard coded domain settings. However: Their logging does not change, because they have either
All of these options, prevent that other team members are bothered with hard-coded domain settings. Of course, it is recommendable that every team member anyhow uses a "private" method to change verbosity settings, instead of hard coding them. (But we all know how it is in practice.)
There are many other use cases. Also for release logging. Imagine a situation where a remote customer has a problem. He sends you a log-file of the problemeatic run. Unfortunately, the log file misses important verbose Log Statements. You send the customer an email and ask him to run the software again, but providing a command line parameter that enables verbose logging for a tree of domains...
This manual stops here with use cases. They are really huge. The "marriage" of sibling modules ALib Configuration with ALox through hidden parameter priority of method Lox::SetVerbosity, which is directly "lent" from the configuration system, just heavily pays off!
As a reader may has already guessted, this camp does not only "lent the concept of priorities" from sibling camp ALib Configuration, but of course also imports and exports Verbositiy information from and to configuration data systems.
A programmer needs nothing special to do. The same as ALox creates Log Domains on the fly as soon as you are using them, the same it reads configuration data for these Log Domains without having an explicit mandate for that. It just always does. If no external configuration is used, nothing is read or exported and ALox will not complain. However, if it finds configuration data that influences the Verbosity setting of Log Domains you are using, then you will get noted by ALox as soon as you have activated Internal Logging.
The variable that is used to store Verbosity information is named ALOX/LOGGERNAME/VERBOSITY_WITH_LOXNAME.Please read its quick reference documentation now and return back to here.
When a Verbosity setting is read by ALox from external configuration, the priority of the plug-in that provided the data is used as the priority of the setting, just as if this value was passed to method Lox::SetVerbosity using optional parameter priority.
The formal syntax of variable ALOX/LOGGERNAME/VERBOSITY_WITH_LOXNAME is given with:
ALOX/<LOGGERNAME>/VERBOSITY_WITH_<LOXNAME> = [ExportAll ;] [*]domainpath[*] = verbosity [ ; … ]
This formal definition states that an indefinite number of arguments of the form:
[*]domainpath[*] = verbosity
may be given, each separated by a semicolon ';'. The pairs of domainpath and verbosity have the following meaning:
domainpath denotes the path of the Log Domain whose Verbosity is to be set. Optionally the value may contain wildcard character '*' at the beginning or end of the string or at both places.With having the ability to provide wildcards, the possibilities to define the Verbosity is a little different than when using method Lox::SetVerbosity! The differences are:
With using configuration variables, it is possible to fetch Log Domains which are residing in different subdomain trees. For example, setting 'ERRORS', affects any Log Domain with this substring in the path, like
/ERRORS /UI/DIALOGS/ERRORS /COMM/ERRORS/SEVERE
This is not possible with using method Lox::SetVerbosity which always modifies exactly one Log Domain and its Subdomains.
In general, as already described, controlling the Verbosity using configuration variables is preferred over using method Lox::SetVerbosity. This is the reason why ALox does not provide an interface method to set "rules", similar to those coming from configuration variables from within the source code.
domainpath. This can also be used as a prefix e.g. INTERNAL_DOMAINS/REPORT = verbose ;However, a Logger that is not configured to log on internal Log Domain, cannot be enabled for doing so using this configuration variable. Instead, a Logger has to be added to the internal Log Domain tree once by the software itself. This behavior is wanted and similar to the fact that a Logger cannot be added to a different Lox instance by just adding the verbosity setting variable on the command line!
If a configuration source is write-enabled, of course configuration variables can be written back, for example if an application closes. To leverage this feature, ALox writes all verbosities that resulted from the patterns given in variable ALOX/LOGGERNAME/VERBOSITY_WITH_LOXNAME during a software run, back to the configuration variable. This is done at the moment a Logger is removed from a Lox object.
If now, an external configuration source is enabled to write configuration data back to a source, then the changed variable can be presented back to the end-user. A simple "write-back-enabled" type is found with class config::IniFileFeeder. In the sample application provided with this library, this approach is demonstrated. At the beginning of function main(), bootstrapping is haltet after the first phase, an INI-file is created and and all file contents is fed to the configuration system:
At the end of function main(), we remove the INI-File and use method IniFileFeeder::Export, to fill the INI-file with all defaults. This of course saves an end-user of your software quite some work.
After a first run of the application (with no INI-file existing before!), the resulting INI-File looks like this:
######################################################################################
# ALox Samples INI-file (created when running ALox Samples)
#
# Copyright 2013-2024 A-Worx GmbH, Germany
# Published under "Boost Software License" (a free software license, see LICENSE.txt)
######################################################################################
/// ------------------------------------------------------------------------------------------------
/// General ALib library settings.
/// ------------------------------------------------------------------------------------------------
[ALIB]
# If true, the process waits for a key stroke on termination. If empty, under Windows
# behavior is detected, under other OSes, defaults to false.
WAIT_FOR_KEY_PRESS= False
# Boolean value that denotes what its name indicates. If empty, under Windows value is
# detected, under other OSes, defaults to true.
HAS_CONSOLE_WINDOW= True
/// ------------------------------------------------------------------------------------------------
/// Settings controlling ALox log output.
/// ------------------------------------------------------------------------------------------------
[ALOX]
# If true, the creation of an additional, ide-specific debug logger is suppressed.
# (In particular suppresses DebugLogger (C#) and VStudioLogger (C++))
NO_IDE_LOGGER= False
# Influences the type of console logger to be created by method
# Lox::CreateConsoleLogger which is also used by Log::AddDebugLogger
# Possible values are: default, plain, ansi, windows, noqtcreator
CONSOLE_TYPE= Default
# Evaluated by colorful loggers that dispose about light and dark colors. Those may adjust
# their foreground and background color accordingly. If not given, under Windows OS the right
# value is detected. Otherwise the value defaults to "foreground". In some occasions, the
# (detected or set) runtime environment might also indicate a different default value.
# Possible values are 'Auto', Foreground', 'Background' and 'Never'.
CONSOLE_LIGHT_COLORS= Auto
/// ------------------------------------------------------------------------------------------------
/// Settings of the Lox-instance used with debug-logging.
/// ------------------------------------------------------------------------------------------------
[ALOX/LOG]
# Defines source path trim rules for Lox "LOG".
# Format: [ [*]sourcepath [, inclusion, trimoffset, sensitivity, replacement] ] [;...]
SOURCE_PATH_TRIM_RULES=
DOMAIN_SUBSTITUTION=
# Prefix strings for log domains of lox "LOG".
# Format: [ [*]domainpath[*] = prefixstring [, inclusion] ] [;...]
PREFIXES=
# Log information about lox "LOG" on exit. Comma separated list of arguments define
# verbosity, domain and content of output. Possible values content arguments are:
# All, Basic, Version, SPTR, Loggers, Domains, InternalDomains
# ScopeDomains, DSR, PrefixLogablesOnce, LogData, ThreadMappings,
# CompilationFlags. If NONE is given nothing is dumped.
DUMP_STATE_ON_EXIT= none, verbosity=info, domain=/ALOX
/// ------------------------------------------------------------------------------------------------
/// Settings of the debug-logger.
/// ------------------------------------------------------------------------------------------------
[ALOX/DEBUG_LOGGER]
# Detected field sizes and tabulator positions of the meta-information portion and the
# those of the log output, separated by ';'. (These is a generated and temporary values).
AUTO_SIZES= T23,20/T46,43/F0/F15/F16/T97,96/T103 ;
# Meta info format of logger "DEBUG_LOGGER", including signatures for verbosity strings and
# astring added to the end of each log statement.
# Format: MetaInfo,Error,Warning,Info,Verbose,MsgSuffix
FORMAT= %SF:%SL:%A3%SM %A3[%TC +%TL][%tN][%D]%A1#%#: %V, \
\ec0, \
\ec3, \
, \
\ec8, \
\e[0m
# Date and time format of logger "DEBUG_LOGGER".
# Format: Date,Time,ElapsedDays
FORMAT_DATE_TIME= yyyy-MM-dd, HH:mm:ss, " Days "
# Time difference entities of logger "DEBUG_LOGGER".
# Format: Minimum,None,Nanos,Micros,Millis,Secs,Mins,Hours, Days
FORMAT_TIME_DIFF= 1000, "--- ", " ns", " µs", " ms", " s", " m", " h", " days"
# Multi-line format of logger "DEBUG_LOGGER".
# Format: Mode,Headline,Prefix,Suffix,Delimiter,DelimiterReplacement
FORMAT_MULTILINE= 2, "ALox: Multi line message follows: ", "> ", , nulled, \\r
# Specifies three further format values: 1. A replacement string if no file name is available,
# 2. A replacement string if no method name is available and 3. The minimum digits of the
# log counter.
FORMAT_OTHER= ---, " ---", 3
# Pairs of search and replacement strings for text logger "DEBUG_LOGGER".
# Format: [search,replacement] [,...]
REPLACEMENTS=
# The verbosities of logger "DEBUG_LOGGER" in lox "LOG". Supports wildcards for domain paths.
# Format: [ExportAll ;] [[*]domainpath[*] = Verbosity] [;...]
VERBOSITY_WITH_LOG= ExportAll ; \
/=Verbose ; \
/ALIB=Warning ; \
/TEXTFILE_TEST=Verbose ; \
$/=Warning ; \
$/DMN=Verbose ; \
$/LGD=Warning ; \
$/LGR=Warning ; \
$/PFX=Warning ; \
$/REPORT=Verbose ; \
$/THR=Warning ; \
$/VAR=Warning
[ALOX/RELEASELOX]
# Log information about lox "RELEASELOX" on exit. Comma separated list of arguments define
# verbosity, domain and content of output. Possible values content arguments are:
# All, Basic, Version, SPTR, Loggers, Domains, InternalDomains
# ScopeDomains, DSR, PrefixLogablesOnce, LogData, ThreadMappings,
# CompilationFlags. If NONE is given nothing is dumped.
DUMP_STATE_ON_EXIT= none, verbosity=info, domain=/ALOX
[ALOX/ANSI_CONSOLE]
# Detected field sizes and tabulator positions of the meta-information portion and the
# those of the log output, separated by ';'. (These is a generated and temporary values).
AUTO_SIZES= F0/F15/F8/T42,41/T49 ;
# Meta info format of logger "ANSI_CONSOLE", including signatures for verbosity strings and
# astring added to the end of each log statement.
# Format: MetaInfo,Error,Warning,Info,Verbose,MsgSuffix
FORMAT= "[%TC+%TL][%tN]%V[%D]%A1(%#): ", \
\ec0, \
\ec3, \
, \
\ec8, \
\e[0m
# Date and time format of logger "ANSI_CONSOLE".
# Format: Date,Time,ElapsedDays
FORMAT_DATE_TIME= yyyy-MM-dd, HH:mm:ss, " Days "
# Time difference entities of logger "ANSI_CONSOLE".
# Format: Minimum,None,Nanos,Micros,Millis,Secs,Mins,Hours, Days
FORMAT_TIME_DIFF= 1000, "--- ", " ns", " µs", " ms", " s", " m", " h", " days"
# Multi-line format of logger "ANSI_CONSOLE".
# Format: Mode,Headline,Prefix,Suffix,Delimiter,DelimiterReplacement
FORMAT_MULTILINE= 2, "ALox: Multi line message follows: ", "> ", , nulled, \\r
# Specifies three further format values: 1. A replacement string if no file name is available,
# 2. A replacement string if no method name is available and 3. The minimum digits of the
# log counter.
FORMAT_OTHER= ---, " ---", 3
# Pairs of search and replacement strings for text logger "ANSI_CONSOLE".
# Format: [search,replacement] [,...]
REPLACEMENTS=
# The verbosities of logger "ANSI_CONSOLE" in lox "RELEASELOX". Supports wildcards for domain paths.
# Format: [ExportAll ;] [[*]domainpath[*] = Verbosity] [;...]
VERBOSITY_WITH_RELEASELOX= /=Off ; \
/CON=Verbose
[ALOX/MEMORY]
# Detected field sizes and tabulator positions of the meta-information portion and the
# those of the log output, separated by ';'. (These is a generated and temporary values).
AUTO_SIZES= F0/F15/F4/T43,42/T52/T69/T83 ;
# Meta info format of logger "MEMORY", including signatures for verbosity strings and
# astring added to the end of each log statement.
# Format: MetaInfo,Error,Warning,Info,Verbose,MsgSuffix
FORMAT= "[%TC+%TL][%tN]%V[%D]%A1(%#): ", \
[ERR], \
[WRN], \
" ", \
[***],
# Date and time format of logger "MEMORY".
# Format: Date,Time,ElapsedDays
FORMAT_DATE_TIME= yyyy-MM-dd, HH:mm:ss, " Days "
# Time difference entities of logger "MEMORY".
# Format: Minimum,None,Nanos,Micros,Millis,Secs,Mins,Hours, Days
FORMAT_TIME_DIFF= 1000, "--- ", " ns", " µs", " ms", " s", " m", " h", " days"
# Multi-line format of logger "MEMORY".
# Format: Mode,Headline,Prefix,Suffix,Delimiter,DelimiterReplacement
FORMAT_MULTILINE= 2, "ALox: Multi line message follows: ", "> ", , nulled, \\r
# Specifies three further format values: 1. A replacement string if no file name is available,
# 2. A replacement string if no method name is available and 3. The minimum digits of the
# log counter.
FORMAT_OTHER= ---, " ---", 3
# Pairs of search and replacement strings for text logger "MEMORY".
# Format: [search,replacement] [,...]
REPLACEMENTS=
# The verbosities of logger "MEMORY" in lox "LOG". Supports wildcards for domain paths.
# Format: [ExportAll ;] [[*]domainpath[*] = Verbosity] [;...]
VERBOSITY_WITH_LOG= /=Off ; \
/MEM=Verbose
# The verbosities of logger "MEMORY" in lox "RELEASELOX". Supports wildcards for domain paths.
# Format: [ExportAll ;] [[*]domainpath[*] = Verbosity] [;...]
VERBOSITY_WITH_RELEASELOX= /=Verbose
[ALOX/TEXTFILE]
# Detected field sizes and tabulator positions of the meta-information portion and the
# those of the log output, separated by ';'. (These is a generated and temporary values).
AUTO_SIZES= T15/T30/F0/F15/F14/T78/T90 ;
# Meta info format of logger "TEXTFILE", including signatures for verbosity strings and
# astring added to the end of each log statement.
# Format: MetaInfo,Error,Warning,Info,Verbose,MsgSuffix
FORMAT= "%SF:%SL:%A3%SM %A3[%TC +%TL][%tN][%D]%A1#%# %V: ", \
[ERR], \
[WRN], \
" ", \
[***],
# Date and time format of logger "TEXTFILE".
# Format: Date,Time,ElapsedDays
FORMAT_DATE_TIME= yyyy-MM-dd, HH:mm:ss, " Days "
# Time difference entities of logger "TEXTFILE".
# Format: Minimum,None,Nanos,Micros,Millis,Secs,Mins,Hours, Days
FORMAT_TIME_DIFF= 1000, "--- ", " ns", " µs", " ms", " s", " m", " h", " days"
# Multi-line format of logger "TEXTFILE".
# Format: Mode,Headline,Prefix,Suffix,Delimiter,DelimiterReplacement
FORMAT_MULTILINE= 2, "ALox: Multi line message follows: ", "> ", , nulled, \\r
# Specifies three further format values: 1. A replacement string if no file name is available,
# 2. A replacement string if no method name is available and 3. The minimum digits of the
# log counter.
FORMAT_OTHER= ---, " ---", 3
# Pairs of search and replacement strings for text logger "TEXTFILE".
# Format: [search,replacement] [,...]
REPLACEMENTS=
# The verbosities of logger "TEXTFILE" in lox "LOG". Supports wildcards for domain paths.
# Format: [ExportAll ;] [[*]domainpath[*] = Verbosity] [;...]
VERBOSITY_WITH_LOG= /=Verbose ; \
$/=Error
Well, this is quite a long INI-file, but this is due to the fact that the sample application creates several Lox and Logger instances. Furthermore, each and every configuration aspect of ALox is found now in this file. An end-user is now enabled to change the logging behavior to adopt his preferences and needs.
Usually, only variables that did not exist yet in a configuration file, are written. But type IniFileFeeder has a special feature: It allows putting the word "writeback" (respectively what is resourced with to token "INIWB") in a line in the INI-file above a variable. If this is detected, the new value of the variable is overwriting the previous value of the INI-file.
In the case of variable ALOX/LOGGERNAME/VERBOSITY_WITH_LOXNAME this can be used for two things:
If you closely look at the generated INI-file above, you might notice the following: Variable "ALOX/DEBUG_LOGGER_VERBOSITY_WITH_LOG" contains flag "ExportAll" and lists much more domains than the other verbosity-variables found in the INI-file. The reason is that method Log::AddDebugLogger sets field CVVerbosities::ExportAll to true for this logger. If this is set, redundant information is generated when the variable is exported: An entry for each subdomain appears, even if a subdomain has the same verbosity setting as its parent.
The rationale for doing so is that during development, when working with the debug-logger, a programmer can quickly see an overview of all known domains and change the setting very fine-grained.
On the other hand, the reason why this is not done for other loggers is, that ALox by default does not want to disclose the internal domain structure to end-users.
Both behaviors can be changed either
ExportAll manually to an external configuration.Of course, in case of INI-files, writing back of entries has to be enabled, if the domain list should be adjusted by future runs of the same application.
What was explained in the previous chapter about writing back verbosity settings to INI-files, can be extended a little further when combined with configuration variable substitution.
Let's imagine a developer of an application has some problems with interfacing the XWindow library. Hence, she would focus on the relevant domains and change the Verbosities to this:
[ALOX/DEBUG_LOGGER]
VERBOSITY_WITH_LOG = / =Warning; \
/ACTION =Warning; \
/AWAX =Info; \
/CMDLINE =Off; \
/TILE =Off; \
/WMI =Info; \
/WMI/XLIB =Verbose; \
/WMI/XLIB/RANDR =Warning; \
/WMI/XLIB/X11 =Verbose; \
Now, the X11 problems were fixed. However, the developer likes the detailing of the settings and aims to preserve them for the future. All he needs to do, is to copy the variable to a different one, like this:
[MYSTUFF]
X11_DEBUG_VERB= / =Warning; \
/ =Warning; \
/ACTION =Warning; \
/AWAX =Info; \
/CMDLINE =Off; \
/TILE =Off; \
/WMI =Info; \
/WMI/XLIB =Verbose; \
/WMI/XLIB/RANDR =Warning; \
/WMI/XLIB/X11 =Verbose; \
With that, this configuration can always be restored, by just setting the verbosity as follows:
[ALOX/DEBUG_LOGGER]
VERBOSITY_WITH_LOG = ${MYSTUFF/X11_DEBUG_VERB}
[MYSTUFF]
...
...
To conclude, lets take some further notes on what was said above:
Of course, the configuration sets stored can be shortened easily to contain only non-redundant information. ALox, when writing the variable, includes all Subdomains in the list of settings, even those that have the same Verbosity as their parent domain. This is intentionally done to support the user and decrease typing effort.
Once a setting is fixed, all redundant lines can be deleted easily - but again this is not necessary even, it might just increase readability and shorten the configuration file.
To collect the path information of a Log Statement, the C++ version of ALox uses preprocessor macro __FILE__.
The source file name and path information received is used in two ways:
Source file paths can become quite long and for various different reasons, it might be wanted remove a redundant or irrelevant prefix from the it.
ALox provides a mechanism to trim the path of source files by using a set of rules.
Internally, different lists of such 'Source Path Trim Rules' are maintained. One is a static table, which stores trim information used by all instances of class Lox. In addition, each Lox has an own, private set of Source Path Trim Rules. The advantage of having the static, global table is that a user can set 'hints' for trimming the path only once (at bootstrap) and forget about it. All instances of Lox will use it.
ALox tries to detect trimable portions of a source path automatically. For that, ALox compares the actual path name of the executable of the currently running process with the path of a source file. The prefix both have in common is identified as trimable.
As an example, imagine a process' file name including the path is:
/home/lisa/bin/myapp(.exe)
When ALox finds a source file residing in:
/home/lisa/dev/myapp/src/ui/dialog.cpp
The trimable prefix of the path would be "/home/lisa/". Therefore, the trimmed file name would be:
dev/myapp/src/ui/dialog.cpp
The result is a more narrow log output which is probably even better readable.
Of course, it would be even nicer to have
ui/dialog.cpp
or alternatively:
src/ui/dialog.cpp
Before we learn how we can configure ALox to trim the path like this, let us first better understand when ALox performs the automatic detection described above:
As you see, this auto-detection works nicely on small projects with source files kept local and the executable is residing in a 'related' place.
When things become more complex, it is advisable to add Source Path Trim Rule explicitly.
A user of ALox may use method Lox::SetSourcePathTrimRule to add Source Path Trim Rules explicitly. When you reconsider the sample above, explicit setting leads to better results even in simple project. The sample used source file:
/home/lisa/dev/myapp/src/ui/dialog.cpp
Now, for a programmatically setting, Lisa invokes
as the very first statement before using ALox. The first parameter tells ALox which string to search. A leading wildcard character '*', indicates that the path is a substring of the file paths identified (no trailing '*' is needed). The second, optional parameter tells ALox to include the given substring in the trimming. In other words, the substring will be excluded from the trimmed path. In again other words it means that the given portion of the path is included in the trimming action!
Now the trimmed source path leads to
ui/dialog.cpp
which is probably what is wanted. As we see, the huge advantages of explicitly setting Source Path Trim Rules is that they do a better job, are independently applied regardless of 'where' the executable is located and that any random behavior of trimming is eliminated.
'/', then characters '\' found in parameters path and trimReplacement when setting rules are replaced by '\' and vice versa. This allows specifying paths and substrings thereof in a platform-independent way. The same is true when rules are defined in external configuration variables, as described later in this chapter.It is advisable to use set Source Path Trim Rules at the very start of a process. Even before attaching the debug Loggers or custom Loggers to any Lox instances. The reason for the latter is that already attaching a Logger lets class Lox evaluate the Scope and potentially create the internal automatic rule. This auto-rule might be conflicting with a user-given rule but be prioritized due to the fact that it was created before the users' rule.
Then, in a multithreaded application, from the moment on parallel access to two different instances of class Lox are performed, it is not allowed to add 'global' rules, because, for performance reasons, the access to the rules is not protected by a mutex.
If multiple Source Path Trim Rules are set, those are applied in their order of creation. The private rules of a Lox are applied first, the global rules afterwards. Only one rule per source path is executed. In other words, as soon as a rule matches and modifies a source path, no further attempts for trimming are performed.
Setting Source Path Trim Rules 'from within the source code' is easy and straightforward. However, when working in a team such changes might not be appreciated by other team members. In this and other situations it is advisable to retrieve Source Path Trim Rule from external configuration data, command-line parameters or other sources at runtime.
For Source Path Trim Rules and also other configuration data, ALox leverages the configuration facility provided by sibling module ALib Configuration.
When an instance of class Lox is constructed, two a configuration variables are tried to be read:
ALOX_GLOBAL_SOURCE_PATH_TRIM_RULES.ALOX_LOXNAME_SOURCE_PATH_TRIM_RULES. The first is for defining global rules. The second variable is specific to a named Lox and the substring 'LOXNAME' needs to be replaced by the name of the Lox in question.
Otherwise, the format of the variables are the same and the following description applies to both.
The variable may contain a list of Source Path Trim Rules separated by semicolons ';'. Each rule consists of up to five values, separated by colons ','. The five values correspond to the first five parameters of method Lox::SetSourcePathTrimRule. The same as parameter 3 (trimOffset), 4 (sensitivity) and 5 (trimReplacement are optional with method Lox::SetSourcePathTrimRule, providing them in the configuration variable is optional as well.
As an example, an INI-file of an application might have the following subsection:
Different trim rules might be redundant or even contradict each other. Therefore the rules are equipped with a priority. Rules with higher priority are applied first. Once a rule matches, no further rule is applied. The priority is defined with enumeration config::Priority and "lent" (for good reasons) from sibling module ALib Configuration. It is are set as follows:
With most methods invoked on class Lox, internal log messages are provided (See 11 Internal Logging). When setting Source Path Trim Rules, this is not the case. The rationale here is, that in most cases no Logger is attached to the Lox attached, yet. If something goes wrong with source path trimming, e.g., when you are not sure if a rule was read from external configuration variables, you can use method Lox::State to dump out the current state of a Lox after a logger was added.
Besides rules set programmatically or using configuration variables, if exists, also the auto-generated rule is displayed.
In very special situations (e.g., ALox uses it for unit testing) method Lox::ClearSourcePathTrimRules can be used to clear the rules of a Lox instance, optionally including all global rules.
The benefits of having ALox using reduced length source file paths in consideration to Scopes is in respect to performance. All data associated with language-related Scopes is stored and retrieved in hash-tables with keys containing the source path.
Furthermore, the output of method Lox::State might be better readable with these shorter paths.
It is also important to consider that when using Scope::Path, especially if increased by an amount of addressed parent directories, the source path must not be trimmed more than such use suggests. When the files are sorted in nested directories according to the nested namespace structure implemented in the files, then the directory before the tree of namespace directories should be included in the trimmed path.
Due to the rich meta-information that ALox provides, the log output lines quickly become quite wide. Therefore, trimming the path of source files in the log output to a level that still allows distinguishing all files properly, can help a lot to reduce such width.
The registered configuration variable type FormatMetaInfo, with its instance found in every ALox TextLogger, provides a format string to structure the meta info. For the source path, two format parameters exists:
Directly from the log-output you can observe how trimming is performed by ALox and whether there is the need to add a trimming rule explicitly.
However, those IDEs which recognize certain patterns and allow to automatically link these patterns with the source file in their editor, sometimes need to see the full path name or a certain part of it. To adjust ALox to your IDE, you might have to play around a little. If your IDE supports clickable output lines, you might want to change the format of the meta info to match the pattern that your IDE requires.
Certain build systems/compilers might not provide the absolute path information in certain situations. In contrast, they might provide source directories in relative addressing in respect to a project file. If then the IDE does not recognize the right origin of a relative path, this path needs correction to be absolute. ALox provides a feature to do such correction. An optional parameter of method Lox::SetSourcePathTrimRule allows specifying a replacement string for what is cut by a rule. (This replacement string can of course also be set using the configuration variables described in previous chapter 14.1.3 Trim Rules Provided by External Configuration Variables.) Sometimes it might be needed to "fiddle around" with the options of the trim rules and the format of the TextLogger output, until finally your IDE recognizes the source information correctly. But once succeeded, it proofs being worth the effort!
When you are sure, that your IDE does not support the links to the editor, then you're unfortunate and your way to go is displaying a (best possible) trimmed path, to reduce overall log output width.
Domain Substitution is a concept of ALox that allows manipulating the effective domain of Log Statements without changing neither these statements nor the Scope Domains that apply to them. Therefore, Domain Substitution is useful when those changes cannot be performed, most likely because the corresponding code using ALox is residing in a library. Sometimes, also a "temporary redirect" of certain domains may be wanted.
As with Scope Domain settings, the concept of Domain Substitution in general should not be 'overused'. Otherwise, things might get complicated.
The rules are set and removed with method Lox::SetDomainSubstitutionRule, which accepts two parameters:
'*' at the beginning and/or the end of the search string. As a result, four 'types' of rules can be created* given)* at the end of domainPath)* at the start of domainPath)* at both, start and the end of domainPath)If for any reason, all rules should be deleted at once, invoke method Lox::SetDomainSubstitutionRule with providing a nulled or empty string for domainPath. There is no explicit other method for clearing the rules.
Rules for Domain Substitution are applied after any other evaluation of the resulting domain is performed. The rules are applied in the order of their definition. Therefore, rules that are passed from configuration files (or command line, etc.) are applied first. Rules might influence each other, hide each oder or even be circular. When setting the rules, ALox does not check for such (sometimes wanted) dependencies of the rules. It might happen, that a rule that was defined earlier than a different one, would be effective only after the second rule was applied. Therefore, ALox repeats the application of all rules as long as at least one of the rules matched. Because of the possibility of having circular dependencies, a maximum amount of ten loops is performed. After that, ALox stops processing Domain Substitution and writes a Log Statement of Verbosity.Error to the internal domain. The error message is only issued once. However the flag is reset when all rules are cleared (by providing a nulled string value for parameter domainPath of method Lox::SetDomainSubstitutionRule.
This amount of loops should be more than enough for all major use cases. Even a third loop is necessary very seldom.
Setting Domain Substitution Rules 'from within the source code' is easy and straightforward. However, when working in a team such changes might not be appreciated by other team members. In this and other situations it is advisable to retrieve Domain Substitution Rules from external configuration data, command-line parameters or other sources at runtime.
For Domain Substitution Rules and also other configuration data, ALox leverages the configuration facility provided by sibling ALib module ALib Configuration
The constructor of class Lox tries to read a configuration variable named ALOX_LOXNAME_DOMAIN_SUBSTITUTION. When setting the variable, the substring 'LOXNAME' needs to be replaced by the name of the Lox in question. The variable itself may contain a list of Domain Substitution Rules separated by semicolons ';'. Each rule consists of two strings which correspond to the two parameters of method Lox::SetDomainSubstitutionRule. These two strings are to be separated by '->'.
As an example, an INI-file of an application might have the following subsection:
With variable ALOX_MYLOX_DOMAIN_SUBSTITUTION set in the INI-file, a Lox named 'MYLOX' would receive the two rules specified.
Sometimes it might be wanted that Domain Substitution Rules are not manipulable externally. A reason could be that by the nature of these rules, unauthorized users are enabled to change the Log Domains and hence also to change their Verbosity, which otherwise can be prevented for protection (see 13 External Verbosity Configuration).
To keep things simple, ALox does not provide an explicit interface to prevent reading the rules from the configuration, because, the fast way out is to delete all rules after the creation of the lox:
Domain Substitution rules are always applied to all Loggers within a Lox.
As noted already, Domain Substitution should be used with care and in case of doubt, thought well. Different alternatives to setting a Domain Substitution exist. For example, to manipulate the domain of methods executed within a library, a thread-related Scope Domain setting may be set before invoking library methods.
Prefix Logables that have been set for a domain that gets substituted, of course do not apply to the substitution domain. In contrast, a Log Statement whose resulting domain gets substituted works just as it was using the new domain within its invocation and Scope Domain setting. Therefore, Domain Substitution settings - if at all - should be made at the beginning of a processes life-cycle and then should not be altered. In this case, also Prefix Logables will be 'transferred' to the substitution domain, providing that the commands that are setting them use relative domain paths.
Domain Substitution may not be used to substitute Log Domains of the standard domain tree with those of the internal tree or vice versa.
To explain the use of colorful log output in ALox, it is best to elaborate roughly on some details of the ALox software architecture.
While ALox in principle is designed to process Logables of arbitrary type, the most widely spread use case is logging textual information. For this reason, abstract class detail::Logger is specialized by class textlogger::TextLogger (still abstract). Besides providing basic features useful for textual log output, for example generating human-readable meta-information of Log Statements, class TextLogger introduces a set of 'escape sequences'. These sequences are gathered in class ESC. The ESC-sequences are quite similar to those known from ANSI terminals. They provide settings of foreground and background colors and font styles. The ESC-sequences may occur in the (string type) Logables and as well in fields of registered configuration variable type FormatMetaInfo.
Here is a quick sample:
Now, if a output 'drain' does not support the modification of colors (e.g., when logging into a text file), these codes need to be removed before the textual log message is written. This task is done by class PlainTextLogger which in turn specializes TextLogger and which also is still abstract. The following diagram visualizes what was said so far:
The result of this design should not need much explanation: Logger types that do not support colors are derived from PlainTextLogger, while those that support colors are derived from TextLogger:
The takeaways from this short technical spotlight are now fairly obvious:
ALox is designed to support different log streams. A log stream is a destination for the Logables and can be the IDE console, the terminal console, a file, a web service or anything that accepts data streams. Abstract class detail::Logger represents such a log stream. While some specializations of the class are provided with ALox, custom specializations may log information to any 'data drain' in any format you like.
Abstract class detail::Logger has a very lean interface, in fact it is basically just one method, which in specialized classes needs to be implemented to execute a log. The data to log is provided as an instance of class BoxesMA, which is a (monotonically allocated) vector holding elements of type Box, hence arbitrary objects.
This allows creating Loggers that take any type of (binary) data and use the data for writing a log entry in any custom way.
While all ALox code tries to be short and simple, class Logger is particularly simple! So, let us quickly walk through the class by looking at its members.
There are just a few fields in class detail::Logger.
class Logger has two members, Logger::Name and Logger::TypeName that can be read using Logger::GetName and Logger::GetTypeName.
Field name is defined by the user and provided with the constructor. Field typeName is 'hard-coded' by each derived classes' constructor. If the user of a Logger does not provide a name in the constructor, then field name defaults to the hard-coded typeName. Both fields are not used internally but only provided to be used by classes managing multiple Loggers (which generally is class Lox).
If multiple Loggers are attached to a Lox, they need to have unique Names.
These are two time stamps that contain the time of the creation of the detail::Logger (or the time this timestamp was reset to) and the time of the last log. These two members are normally used to calculate the elapsed time (the cumulated time an application is running) and the time difference between two log calls. The latter is especially interesting for log outputs on a debug console, as it allows getting a first quick impression about your software's performance, lock states, bottlenecks, etc.
This is a simple counter of the number of logs processed so far. Feel free to reset it as you like, it is not used anywhere internally, other than as an option to output with each log line.
Besides the protected constructor, which just initializes some default values for the Loggers' fields, abstract method Logger::Log is the most important.
Derived classes only need to implement this abstract method with code that is executing the Log Statement. When the method is invoked, class Lox already performed various checks, including that the Verbosity justifies the execution.
As an experienced programmer after reading the previous sections, it is certainly fully obvious to you which steps need to be taken to create your own variation of class detail::Logger that directs your Logables to a certain data drain in a specific format. Nevertheless, let us quickly name these steps explicitly:
But before you now go ahead and implement your own Logger type class, you should first continue reading through this chapter.
When you think about debug log output you think about logging textual messages that get displayed on your debug console. We think the use of a logging ecosystem for this quite simple purpose is advisable as soon as a software project bigger than two pages of code!
While ALox wants to be a perfect tool for quick, easy and comfortable debug logging, the goals of ALox go beyond that. This is why ALox logging interface methods are not restricted to string types, but accept any object to be passed to any derived Logger type.
It is very important to understand this. The result is twofold:
Class textlogger::TextLogger, which is described in this chapter, is exactly about the first thing: Log any object that is passed to it as a textual representation, hence into a character stream. All of the provided ALox Loggers that produce text output, derive from this base class instead of deriving directly from Logger. Among these classes are loggers::ConsoleLogger, loggers::MemoryLogger and loggers::AnsiLogger. Hence, the class diagram above is a little simplified. It rather looks like this:
Class textlogger::TextLogger contains two helper-classes as public fields. The advantage of using helpers is that they can be replaced at runtime by your own, tailored versions of these helpers and this way you can change the default behavior of existing Logger types, without deriving new ones.
The helper-classes are described in the following two paragraphs.
The following registered configuration variable types are used by class textlogger::TextLogger to assemble the meta-information of each log line, which incorporates things like date and time, thread information, Verbosity and Log Domain:
FormatMetaInfo provides a public format string that defines the start (prefix) of each log line. A sample of such format string is:
"%SF:%SL:%A3%SM %A3[%TC +%TL][%tN]%V[%D]%A1#%#: "
The format string contains variables, marked by a leading '%' sign. The set of these format variables available are:
| Description | |
|---|---|
| The full path of the source file. | |
| The trimmed path of the source file. | |
| The callers' source file name. | |
| The callers' source file name without extension. | |
| The line number in the callers' source file. | |
| The callers' method name. | |
| The date the log call was invoked. | |
| Time of day the log call was invoked. | |
| Time elapsed since the Logger was created or its timer was reset. | |
| Time elapsed since the last log call. Note: These time values do not sum up correctly. This is not only because of rounding errors, but also because the time between the "end" of the last log call and the "beginning" of this log call is measured. This has the advantage that a quite accurate value of "elapsed time since the last log call" is displayed and hence a very good performance indicator is provided. | |
| Thread name | |
| Thread ID. | |
| The Verbosity. For the display of the different values, FormatMetaInfo exposes four public fields containing string definitions. | |
| The Log Domains' full path. | |
| The log call counter (like a line counter, but counting multi-line log output as one). | |
| An auto-adjusted tabulator. This grows whenever it needs to grow, but never shrinks. The mandatory number n (a character between 0 and 9) specifies how much extra space is added when tab is adjusted. This is useful to achieve very clean column formatting. | |
| The name of the Logger. This might be useful if multiple loggers write to the same output stream (e.g. the console). | |
| The name of the Lox. | |
| The name of the process / application. |
Changing string FormatMetaInfo::Format provides an easy way to change the look of your log output. For example, if you are not interested in thread information, just remove the "[%tN] " part from the original string.
If you want to modify the output of a certain variable or if you want to add your own variables, you can derive your on implementation of TextLogger and override the virtual method TextLogger::processVariable. Within the implementation, just fetch your own variables and/or modify existing and call the original method for the rest that you do not want to modify.
Finally, if you really want to customize the logging of meta-information in the class TextLogger completely and maybe do not want to even rely on a format string, then feel free to override the virtual method TextLogger::writeMetaInfo.
Class ObjectConverter is used by class textlogger::TextLogger to convert the Logables that get passed by the user through the Log Statements to the Logger into a string representation. While ObjectConverter is abstract and declares only one simple interface method, the standard implementation used with the built-in loggers is provided with type textlogger::StandardConverter.
This class is still is extremely simple, as it lazily transfers this responsibility to instances of types which are derived from class format::Formatter. This abstract class and corresponding standard implementations are provided with sibling ALib module ALib BaseCamp.
Please consult the ALib documentation of classes
to learn more about how these classes work.
As you see, also here are different "levels" of possibilities of how to change and implement custom functionality in respect to converting the Logables while using class TextLogger:
Class textlogger::TextLogger provides a feature to log a message into multiple lines. This is useful for example, if you want to log a string that contains XML text. Instead of one vast log line, TextLogger is configured by default to separate the text into multiple lines in a very controlled way.
Multi-line output behavior of class TextLogger is configured by the field FormatMultiLine.
The following modes are available:
Class textlogger::TextLogger can avoid concurrent access to the standard io-streams std::cout and std::cerr in multithreaded programs.
With instance STD_IOSTREAMS_LOCK, ALib provides a global lock for this purpose. To enable the use of this lock for a derived custom type, all that has to be done is providing value true for parameter usesStdStreams of the protected constructor of class TextLogger.
If an application writes to those streams in parallel to ALox, such direct writes should be performed likewise only after the this lock was acquired.
ALox supports recursive log calls. Recursion occurs when log statements are executed during the evaluation of the logables that belong to another "outer" log statement. A user might think that recursive log calls are seldom and exotic, but we had to learn that in reality, recursive calls unfortunately might occur quite quickly.
To allow and properly treat recursion, each class and method involved in the execution of a log statement has to be prepared for it. The execution must be free of dependencies to member variables or such members need to be created per recursion.
Hence, not only class class Lox needs to support recursion, but also the logger classes themselves.
Class textlogger::TextLogger and its utility class textlogger::StandardConverter are well prepared and as long as custom loggers are built on those, recursion should not be a problem. This is because abstract method TextLogger::logText was "protected" of recursion and therefore will not be invoked recursively.
When implementing own variants of class ObjectConverter or otherwise a "deeper" use of provided classes is done, the possibility of recursion of log calls has to be taken into account. We recommend a look at the built-in classes' source code to have an idea what needs to be done in respect to field of concern.
While the abstract classes Logger, TextLogger and PlainTextLogger are located in the namespaces alib::lox::detail, and alib::lox::textlogger, you can checkout which 'ready to use' Logger implementations are available today for your preferred language version of ALox, by referring to the reference documentation of namespace alib::lox::loggers.
For convenience, method Lox::CreateConsoleLogger is provided. This method chooses an appropriate implementation of class Logger suitable for human-readable log output. The Logger chosen depends on the platform and configuration settings.
For debug logging, method Log::AddDebugLogger is provided. This may even choose and attach more than one Logger, depending on language, platform and IDE.
A noteworthy, built-in specialization of Logger is found with class MemoryLogger It uses an internal character buffer of type AString and just appends each log entry to this buffer, separated by a new line sequence.
As MemoryLogger does not log to the console or any other slow thing, it is extremely fast. The latest record was over on million log entries per second in a single-thread! (Achieved on Intel(R) Haswell Core(TM) i7 CPU @4.0GHz, using ALox for C++, doing release logging.)
This gives an indication that the ALox ecosystem, in combination with its MemoryLogger is extremely useful in performance-critical sections of your code. If you would do 1000 log entries per second, the performance loss for your application would only be around 0.1%.
The following summarizes the takeaways of this chapter:
If you developed an interesting Logger, like one that
then please do not hesitate to propose the code to us as an extension of the open source project ALox!
ALox defines several configuration variables, which are read from configuration files (e.g. INI-files), environment variables or the command line interface. Their use are documented in various places. A reader might consult:
The configuration variables (and their documentation) are:
ALox addresses two fundamental 'use cases', namely debug logging< and release logging. While technically both are similar, from a conceptual perspective the two are very different things.
Looking into the head of a software developer that thinks about debug logging, you will find the following thoughts:
⇒ We understand that a logging library has to be easy!
Now release logging:
⇒ We understand that a logging library has to be feature rich and reliable!
This discrepancy easily justifies the use of two different libraries for both use cases. ALox takes a different approach: it tries to match the needs of both worlds. There are two fundamental design rules in ALox that lead to a solution:
1. Orthogonality of ALox and its API.
Orthogonality here means that features that are not used, are not visible when using ALox. This is reached by optional parameters with reasonable default values, many overloaded variants of methods and by taking internal prerequisites when ALox 'detects' that a feature is not used.
2. Auto-configuration.
This means not only that missing configuration is defaulted, but also that ALox is not pedantic but designed rather non-intrusive. For example, logging into a 'new' Log Domain does not need to anyhow 'register' or 'create' such domain. Many things in ALox just happen on the fly.
Most of ALox auto-configuration features apply to debug logging only and are implemented by the dedicated, auto-created Lox instance used for debug logging and also by the dedicated API interface used for debug logging (which enables the automatic pruning of debug-logging from release code).
But it has a little drawback: Hiding features to make an API simple reduces the understanding of the API - and this is what a user of release-logging requires. And this is the goal of this appendix chapter: We try to collect, list and name concepts of ALox that otherwise might be a little hidden for good reasons.
Bootstrapping ALox is a matter of bootstrapping the ALib C++ Library, because ALox is just one out of several modules which all needs to be duely initialized and shut down. All about this process is documented with chapter 4. Bootstrapping And Shutting Down ALib of the Programmer's Manual of ALib.
As long as no major configuration changes are planned to be done, the standard bootstrapping and shutdown is just a matter of invoking one function. Thus, the minimum ALox "hello world" sample looks like this:
With this standard bootstrapping, reading ALox variables given with command line options or environment variables is already in place!
In chapter 13.5 Receiving the Resulting Domains From A Variable, a quick sample of how to slightly customize bootstrapping is given, which allows writing all defaulted ALox variables into a custom INI-file.
For debug logging, a pre-configured instance of class Lox is created and used. More information on this is given in chapter 10.1 Debug Logging.
While method Lox::RemoveLogger is available for removing a Logger from a Lox instance, there is no method for explicitly adding one. Instead, the method that allows to control the Verbosity of a Log Domain and its Subdomains for a Logger, Lox::SetVerbosity adds a Logger at the moment the one provided is not known to the Lox, yet. Consequently, the very first time a Verbosity of a Logger is set, the overloaded version of Lox::SetVerbosity which takes a reference to the Logger as parameter has to be used. In subsequent invocations, alternatively, the name of the Logger can be provided.
Each Logger attached to a Lox has to have a unique name. Nevertheless, Loggers can be constructed without explicitly providing a name. In this case, a default name which is different with each derived type of Logger is used. This way, many standard use cases do not require the user to think about the name of Loggers. For example if a Logger that logs to the console should be used in parallel to one that logs into a text file, both Loggers will have different names.
However, if for example two different loggers of type loggers::TextFileLogger are to be added to the same Lox, then with their creation, a dedicated, distinguishable name has to be provided.
In addition, when reading Verbosity settings from external configuration (as described in 13 External Verbosity Configuration), it is advisable to explicitly name Loggers, so that external configuration data stays "compatible" at the moment a different Logger type is used for a certain task. On the other hand: this is not necessary for the standard debug Logger created automatically or explicitly by calling Log::AddDebugLogger (see more info on this below), because such Loggers are always named "DEBUG_LOGGER".
It is allowed to attach an instance of a Logger to multiple Lox instances. Concurrent access will be locked in case multithreading is activated.
Method Lox::CreateConsoleLogger creates an appropriate type of Logger depending on the operating system, IDE used (if in IDE), implementation language, configuration variable, etc. The goal get a maximum logging experience, e.g. colorful logging if the console supports colors.
This method can be used to create a Logger whenever a console logger is needed (also for release-logging of course).
Furthermore, method Log::AddDebugLogger uses this method to attach a Logger to the Lox singleton used for debug-logging. In addition, if running in an IDE, ALox tries to detect the IDE and optionally (if available) creates a second, IDE specific Logger. See reference documentation of the methods linked above for more details.
For both Loggers, root domain '/' is set to Verbosity.Verbose. In addition, the Verbosity for internal ALox messages is set to Verbosity.Warning. (More information on internal ALox messages is found in 11 Internal Logging.)
Finally, method Lox::AddDebugLogger is automatically invoked internally at the moment that the Lox singleton used for debug-logging is used and no other Logger was attached, yet.
If no Source Path Trim Rules are given a default rule is automatically detected and registered.
If Source Path Trim Rules are given, path separators '/' and '\' are corrected to suit the target platform of compilation.
For more information see chapter 14 Trimming Source File Paths and Clickable IDE Output.
Log Domains are created on the fly as needed (used). Log Domain, once created, are never deleted and a user does not need to care about their management. New, unknown Log Domains inherit their Verbosity from their parent.
Furthermore, when obtaining Verbosity settings from external configuration, a natural prioritization is applied: First INI_file settings, which are overwritten by environment variable settings, which are overwritten by command-line parameters. All of them are overwriting settings made invocations of Lox::SetVerbosity in the source code - as long as optional parameter priority is not given.
More information on this is found in 13 External Verbosity Configuration.
ALox API transparently hides the fact that it is made for logging arbitrary objects - not just text messages. Features for logging text is just an application build on the concept of logging abstract 'Logables'. This is not only true for the Logables provided in Log Statements, but also for Prefix Logables. More information about logging arbitrary objects is found in 17 Loggers and Implementing Custom Types.
When logging text, classes found in namespace alib::lox::textlogger are doing quite a bit of things in the background that are not obvious to the user. For example:
'std::cout' and 'std::cerr') are locked against concurrent write operations. This avoids clutter that would otherwise be created by intermixing log statements coming from different threads. The lock used is public global variable STD_IOSTREAMS_LOCK and should be acquired by custom code that write to these streams.In ALox for C++, logging strings leverages the string facilities of underlying ALib, which allows to transparently pass just any sort of string object to Log Statements, including references or pointers to almost any custom string type - without any sort of explicit prior conversion! This is achieved using 'template meta programming'. Information on how to adopt custom string types is found in the Programmer's Manual of module ALib Strings.
Compiler symbols, including those that control features of ALox, are documented with the reference documentation of ALib C++ Library.
ALox for C++ makes extensive use of preprocessor macros. Those mainly achieve:
The macros and their documentation are divided into two different groups:
Documentation for those are found in the corresponding subsections of the reference documentation of ALib C++ Library.
While all macros for debug logging start with the prefix Log_, those for release logging are using the prefix Lox_. Otherwise, their naming and parameters are the same.
The rest of the macro names in most cases corresponds to methods found in class Lox.
Both macro sets include macro Log_Prune, respectively Lox_Prune. All that these two macros do is pruning the code that is passed to them at the moment that debug logging (respectively release logging) is supposed to be pruned. This allows placing code for setting up ALox, for example the creation of custom loggers, which is pruned in the moment the according log-statements are.
For an introduction of how to use these macros, work yourself through the ALox - Tutorial.
The C++ version of ALox is distributed as an ALib Camp of ALib C++ Library.
Documentation for compiling ALib is given with chapter 6. Building The Library of the ALib Programmer's Manual.
In the following sections, the use of ALox with different IDEs is discussed. Besides specifics in respect to project setup, an overview about how ALox clickable log output is supported - and achieved! "Achieving" here means most of all to configure the output format in a way that the IDE "understands" the source file and line number information and links them to the editor and source.
To change the format of the log output, field Format of the configuration variable can be modified. This can be done either programmatically, or, if available in the external configuration of an application. If you are new to ALox, the easiest way to play around with different log output formats, is to compile and run the sample project. This will generate an INI-file (in your personal OS-specific configuration folder) and within this file you will find an entry for configuration variable ALOX/LOGGERNAME/FORMAT. You can edit this, and re-run the sample. The log output will change. From here, you can start your own investigations about how to convince your IDE to accept the log statements.
In the configuration file, there are also other configuration variables which can get useful to adjust the log output to a certain IDE. If your IDE is not listed in the following paragraphs, then still reading these might help you in understanding how such support is possible.
QT Creator can be used in two different "modes", with CMake files and with QMake files. Unfortunately, in respect to clickable log-output there is a tremendous difference in the behavior of QT Creator.
In respect to log output file name recognition, we have made the following observations:
"Loc:".From these observations, the following advice can be given:
" Loc: [..." .Using external configuration this means to set three variables. For example, an INI-file might contain the following entries:
CONSOLE_TYPE= plain
DEBUG_LOGGER_FORMAT= " Loc: [%SP/%SF(%SL)]:%A3%SM %A3{%TC +%TL}{%tN}{%D}%A1#%#: ", \
{ERR}, \
{WRN}, \
" ", \
{***}
DEBUG_LOGGER_REPLACEMENTS= "[", "{", "]", "}"
QT Creator has a built in CMake support which works really well with the CMake files provided with the project (as of the time of this writing).
To use the pre-build CMake files of ALox with QT Creator, open menu File of QT Creator and choose Open File or Project... and select the file:
ALIB_LIB_PATH/build/cmake/samples/ALox/CMakeLists.txt
Follow the project setup as QT Creator documentation suggests. When the CMake run dialog appears, for debug-builds, no arguments need to be passed. For release builds, provide
-DCMAKE_BUILD_TYPE=Release
as the CMake Arguments
The ALox sample project is now ready to be build in QT Creator
In respect to log output file name recognition, there is some bad news now: When used with CMake projects, QT Creator does not support clickable log lines. At least, we have not found out how! Therefore, we have no recommendation about how to change the log output in respect to make such output clickable.
The output panes of QT Creator support colorful (ANSI) logging and have a light background. Therefore, we recommend to set the following two configuration variables:
CONSOLE_TYPE= ansi CONSOLE_LIGHT_COLORS= background
When you are new to ALib and you just want to play around with it a bit, the easiest thing is to open the Visual studio solution found in
ALIB_LIB_PATH/build/ide.vstudio/Solution/ALib.sln
You are set! For example you could walk through the ALox - Tutorial by adding the tutorial code to the main() function of the project ALox-CPP-Samples.
ALox provides a Visual Studio project that compiles ALox into a DLL. The projects is located in:
ALIB_LIB_PATH/build/ide.vstudio/ALib-DLL/
Add this project to your solution and set a build dependency from your project to the just added ALib-DLL* project. Furthermore, the ALib-DLL project has to be added as a reference to your project. Finally, the ALib include directory has to be added to your project.
Clickable Log Output with Visual Studio:
As far as we know, clickable log output is only possible to have when launching a project in debug mode. In this case, ALox automatically adds a second logger of type VStudioLogger. (This is the default behavior by default, implemented with method Log::AddDebugLogger.)
This logger does everything right to have clickable log lines in Visual Studio. No adjustments need to be done.
CLions' build system relies on CMake. Pre-configured project folders are provides with
ALIB_LIB_PATH/build/ide.clion/samples/ALox ALIB_LIB_PATH/build/ide.clion/unittests
The CMake files within these directories are just including the corresponding CMake files found in
ALIB_LIB_PATH/build/cmake/samples/ALox ALIB_LIB_PATH/build/cmake/unittests
The advantage of this approach is that the "generic" folders found in folder cmake are kept free from CLion project files.
Therefore, CLion users should be ready to compile by just opening these project folders.
For debugging ALib and ALox code, you might want to install the Pretty Printers for GNU Debugger.
Clickable Log Output with CLion:
CLion has an intelligent output console that supports ANSI colors and detects links to files automatically. The file name without path is sufficient and this way, the default format string should do fine.
There is one specialty about the ANSI color support: CLion does not support light colors. Therefore, the use of light colors has to be switched off. If this is not done, colors are in most cases not effective.
As a summary, these or similar configuration variable settings are recommended:
[ALOX]
CONSOLE_TYPE= ansi
CONSOLE_LIGHT_COLORS= foreground
DEBUG_LOGGER_FORMAT= %SF:%SL:%A3%SM %A3[%TC +%TL][%tN][%D]%A1#%#: %V, \
\e[31m, \
\e[34m, \
, \
\e[33m