magic.lambda.logging 13.3.0

Audit logging from Hyperlambda

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.

log.info:Some log entry
   username:foo
   ip:123.123.123.123

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.

Quality gates