Up to Documentation.
Diagnostics is an important part of running a service.
That is why it is a core concept in abc.
At top-level, there is a log_ostream instance.
The program developer should keep that instance alive, and should pass it to other class instances that support diagnostics.
The job of log_ostream is to put the desired subset of log lines into the underlying table_ostream.
It does that by orchestrating a Line instance and a Filter instance.
If the Filter instance decides that the diagnostic entry should be persisted, the Line instance formats it, and the log_ostream puts it into the underlying table_ostream.
Otherwise, the diagnostic entry is thrown away.
While any class that exposes the same public methods as line_ostream could be used as a Line template parameter, it is recommended to derive from the existing line_ostream.
There are three such derived classes provided out of the box:
debug_line_ostream includes all supported diagnostic fields formatted in fixed-width columns.
This line format is human-readable as is.
It is recommended as a primary choice of Line.
diag_line_ostream also includes all supported diagnostic fields, but this time they are formatted without any space padding.
This line format optimizes the amount of bites persisted and transported at the expense of human readability.
An additional tool or script may be needed to make it human-readable.
test_line_ostream includes a subset of the input diagnostic data formatted in a way intended for aesthetics rather than for real diagnostics.
The purpose of the Filter instance is to skip diagnostic entries based on category and severity.
The provided log_filter currently only eliminates lines with a lower severity than the given one, irrespective of category.
That may be improved in future.
Alternatively, an instance of another class may be used as long as that class exposes the same public method(s) as log_filter.
There is a set of "known" fields, and an optional free-text tail. Here are the known fields:
Category is an unsigned integer of type category_t.
Values from 0 through category::abc - 1 are available for programs to identify their own components.
Values of category::abc and above are reserved for abc components.
Severity is an unsigned integer of type severity_t.
The supported values are already defined in namespace severity.
The smaller the value, the higher the severity.
Tag is an unsigned integer of type tag_t. For more information, visit the Tagging concept.
For guidance and examples on how to code diagnostic calls throughout your program, visit tutorial How to Log Diagnostics.