Logging helper slots for Magic, allowing you to inject your own logging implementation, giving you the ability to create log entries from Hyperlambda. To use package go to https://polterguy.github.io
Logging wrapper slots for Magic. More specifically, this project provides the following slots allowing you
to create log entries.
[log.info] - Information log entries, typically smaller pieces of information
[log.debug] - Debug log entries, typically additional debugging information not enabled in production
[log.error] - Error log entries, typically exceptions
[log.fatal] - Fatal log entries, from which the application cannot recover from
In addition to the above slots there are also slots that allows you to retrieve log items, and/or some
basic statistics from your log. These can be found below.
[log.count] - Counts number of log items, optionally matching the specified filter condition
[log.get] - Returns the log item with the specified id
[log.query] - Returns a list of log items according to its arguments
[log.capabilities] - Returns the capabilities of the log implementation
By default, this project will log into your magic.log_entries database/table, using either MySQL, PostgreSQL, or
Microsoft SQL Server. This allows you to use SQL to generate statistics on top of your logs. However, the project
also allows for using NoSQL database systems as your log implementation, and/or any other types of implementation
you see fit. An example of logging an info piece of information can be found below.
log.info:Howdy world from magic.lambda.logging
You can supply content to your log item two different ways. Either as a piece of string, or if you choose
to set its value to nothing, it will concatenate all children node's values, after having evaluated it as a lambda
object. This allows you to create rich log entries, based upon evaluating the children of the log invocation.
This gives you a convenience shortcut to create log entries that have strings concatenated as their content,
without having to manually concatenate them yourself. An example of the latter can be found below.
.a:foo bar
log.info
.:"A's value is "
get-value:x:@.a
If you provide a value for your log invocation, then children nodes will be assumed to be "meta information" associated
with the invocation, allowing you to log data such as follows.
The above will log "some log entry" for you, and associate [username] and [ip] with your log entry as meta data.
This allows you to use the same log entry for similar log types, and parametrise your log entry with meta information,
giving you aggregate capabilities on log entries having the same content, while still preserving meta information unique
to each log entry. Notice, if you don't provide a value to your log invocation, no meta data will be associated with your
log entry, but all arguments will rather be concatenated as a single string and end up in the "content" parts of
your log entry after having been evaluated.
Exception logging
The [log.error] and [log.fatal] slots give you the option of logging an exception stack trace, by parametrising
your invocation with an [exception] argument, which will not be assumed to be meta information, but rather end up
in the "exception" column as you create the log item. All other parameters will still be evaluated or used as meta
information.
Log level configuration
The slots [log.debug], [log.info], [log.error], and [log.fatal] are actually logging with their
last parts becoming the "type" of log item. This is similar to how Log4Net and Log4J works, and can be turned on
and off as you see fit. The level is an increasing leverage type of value, applied in the following order.
debug
info
error
fatal
This implies that if you set the level to for instance "error" no invocations to [log.debug] or [log.info]
will log anything into your log, allowing you to "turn up and down" the level of logging you need as a configuration
setting through your "appsetting.json" file. Below is an example configuration setting the level to "info". The
default value for log level is "debug". In a production environment you might want to increase this to at
least "info".
{
"magic": {
"logging": {
"level": "info"
}
}
}
The above value will for instance log everything except invocations to [log.debug].
Querying your log
Notice - To see the capabilities of your particular log implementation please invoke [log.capabilities] and verify
your particular log implementation can actually do what you need for it to do, since not all implementations have the
same capabilities - Implying things such as filtering log items according to content, and/or timeshifting log items, etc,
might not be implemented for your particular implementation.
To retrieve log items sequentially you can use [log.query]. This slot can optionally take a [from] argument
being the id of an existing log item from where to start retrieving items, and a [max] argument being the maximum
number of records to return. If no [max] argument is specified, the default value of this is 10. In addition the
invocation can be fiven a string as its value, which if given must match the content of your log items for an item
to be returned. Below is an example of usage.
log.query:"We successfully authenticated user 'root'"
from:555
max:20
The above will return log items starting from id 554 and down, and return only 20 records, and all returned records
will have a content value of "We successfully authenticated user 'root'". To return a single log item you can use
[log.get] and pass in the id of the log item you want to retrieve as its value.
Notice - If your particular log implementation does not support querying you cannot query items
according to content as illustrated above, but rather only page items. Invoke [log.capabilities] to see if
your implementation supports querying before relying upon its existence.
Project website
The source code for this repository can be found at github.com/polterguy/magic.lambda.logging, and you can provide feedback, provide bug reports, etc at the same place.
