We need a way to log things, and manage the content of these logs.
This will be bundled into a reports system, an ECS. The entities will be a report and the components will represent information about a report. A report can be "just a log message" but it can also be a container of other reports, or a location for recording incoming telemetry. It will also make it much easier to filter logs and telemetry. Some core components:
Active: Signifies if a report may still be modified. If this component doesn't exist the log message has, and always will be, immutable. Otherwise True represents still being filled in, and False represents that it will not be changed further (maybe a Boolean component with no false?).
Children, Parent: Creates a hierarchical layer of reports. Parent is a parent entity. Children is an in-order list of children reports. The children list (and hence the parent component) will never be modified (except to be extended if active).
Message: The message as a string, for when the entire message is just a string.
Time: Time when this report was entered (immutable, when report started).
ModifiedTime: For live reports, last modified time.
ReportLevel: The importance level of this message. Ranges from DEBUG (0 importance) to CRITICAL (5 importance) with INFO, NOTICE, WARNING, ERROR in between:
DEBUG: All messages are useful for debugging. Specifically a report that will likely not be needed except for debugging.
INFO: Some useful info, usually for keeping track of where reports are happening.
NOTICE: Point out something routine, but important, happened.
WARNING: Something that could go wrong.
ERROR: Something which went wrong, but we handled.
CRITICAL: Something which went wrong, that we didn't handle.
ReportingModule: The module where this report came from (madz will eventually unify program and internal modules, for now, this is just a string, not an object).
In madz there will be some helper features:
There will be a multimethod (re: polymorphic function) which will be able to construct a string for a report GenerateReportString(report). Specifically the actual message, but not the meta information (Time, ReportingModule, ReportLevel). A second multimethod will be responsible for formatting a report with meta information GenerateReportMetaString(format, report, string=None), which will call GenerateReportString if string is None. These multimethods can be extended if new components are added which provide more information, or to support symbol systems.
Madz plugins will be able to subclass a helper object which will provide report functions on the object. There will also be report functions for when not on a plugin object.
report_*(message, level=None, module=None, time=None): Where * is a report level. Creates a report entity, which is immutable and will not be modified.
report_*_group(message=None, level=None, module=None, time=None): Where * is a report level. Returns a report group object, with the report entity set to active. Has a helper method, called automatically on exit from a with block:
finalize(modified_time=None)
When #53 is complete, a method for creating graphs (trees) of reports.
At some point in the future, for optimization, it may be useful to build an symbol system (and merge it with the one in craft engine). Namely a symbol system lets us use strings, but optimizes them into numbers, this may make some log calls much faster and take up less memory.
We need a way to log things, and manage the content of these logs.
This will be bundled into a reports system, an ECS. The entities will be a report and the components will represent information about a report. A report can be "just a log message" but it can also be a container of other reports, or a location for recording incoming telemetry. It will also make it much easier to filter logs and telemetry. Some core components:
Active
: Signifies if a report may still be modified. If this component doesn't exist the log message has, and always will be, immutable. Otherwise True represents still being filled in, and False represents that it will not be changed further (maybe a Boolean component with no false?).Children
,Parent
: Creates a hierarchical layer of reports. Parent is a parent entity. Children is an in-order list of children reports. The children list (and hence the parent component) will never be modified (except to be extended if active).Message
: The message as a string, for when the entire message is just a string.Time
: Time when this report was entered (immutable, when report started).ModifiedTime
: For live reports, last modified time.ReportLevel
: The importance level of this message. Ranges from DEBUG (0 importance) to CRITICAL (5 importance) with INFO, NOTICE, WARNING, ERROR in between:ReportingModule
: The module where this report came from (madz will eventually unify program and internal modules, for now, this is just a string, not an object).In madz there will be some helper features:
GenerateReportString(report)
. Specifically the actual message, but not the meta information (Time,ReportingModule
,ReportLevel
). A second multimethod will be responsible for formatting a report with meta informationGenerateReportMetaString(format, report, string=None)
, which will callGenerateReportString
if string is None. These multimethods can be extended if new components are added which provide more information, or to support symbol systems.report_*(message, level=None, module=None, time=None)
: Where*
is a report level. Creates a report entity, which is immutable and will not be modified.report_*_group(message=None, level=None, module=None, time=None)
: Where*
is a report level. Returns a report group object, with the report entity set to active. Has a helper method, called automatically on exit from a with block:finalize(modified_time=None)
At some point in the future, for optimization, it may be useful to build an symbol system (and merge it with the one in craft engine). Namely a symbol system lets us use strings, but optimizes them into numbers, this may make some log calls much faster and take up less memory.