The vom-json Reference Manual

This is the vom-json Reference Manual, version 2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 07:06:27 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 vom-json

A json-formatted logger for vom

Author

Matt Novenstern <>

Source Control

(GIT https://github.com/fisxoj/vom-json.git)

License

MIT

Long Description

.. image:: https://travis-ci.org/fisxoj/vom-json.svg?branch=master
:target: https://travis-ci.org/fisxoj/vom-json
:alt: Travis CI status badge
.. image:: https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg
:alt: Contributor Covenant
:target: CODE_OF_CONDUCT.md

:Source: ‘https://github.com/fisxoj/vom-json <https://github.com/fisxoj/vom-json>‘_
:Docs: ‘https://fisxoj.github.io/vom-json/ <https://fisxoj.github.io/vom-json/>‘_

vom-json is a complementary library to ‘vom <https://github.com/orthecreedence/vom>‘_, which changes the logger syntax to something like ‘lambda-log <https://github.com/KyleRoss/node-lambda-log/>‘_ which outputs its log messages in the JSON format. In some environments like AWS insights, this makes the log data more searchable.

You can use it two ways:

Wrap the body of your program in it using :macro:‘vom-json:with-json-logging‘::

(vom-json:with-json-logging
(vom:error "Oh noes!"))
;; => {"_logLevel":"error","_timestamp":"2020-05-11T18:23:58.569136Z","msg":"Oh noes!","_tags":[],"_package":"common-lisp-user"}

Enable the logger globally::

(vom-json:enable-json-logging)

This project is extremely inspired by ‘log4cl-json <https://github.com/40ants/log4cl-json/>‘_.

Version

2

Dependencies
  • jonathan (system).
  • local-time (system).
  • vom (system).
Source

vom-json.asd.

Child Component

vom-json.lisp (file).


3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 vom-json/vom-json.asd

Source

vom-json.asd.

Parent Component

vom-json (system).

ASDF Systems

vom-json.


3.1.2 vom-json/vom-json.lisp

Source

vom-json.asd.

Parent Component

vom-json (system).

Packages

vom-json.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 vom-json

Source

vom-json.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Macros

Macro: with-json-logging (&body body)

Sets ‘vom <https://github.com/orthecreedence/vom>‘_’s log format to json for the body of the macro. You could, for example wrap the whole execution context of an app with this to ensure the app uses json logging but doesn’t interfere with... I dunno... another app running in the same image that you wan to use a different log format for some reason? It just seems right to include a “WITH-...“ macro in a lisp library.

Package

vom-json.

Source

vom-json.lisp.

Macro: with-tags ((&rest tags) &body body)

A nestable macro to allow adding tags to log messages. Any log messages printed inside a :macro:‘with-tags‘ call should have those tags in the “tags“ array.

Package

vom-json.

Source

vom-json.lisp.


5.1.2 Ordinary functions

Function: disable-json-formatter ()

The inverse of :function:‘enable-json-formatter‘.

Package

vom-json.

Source

vom-json.lisp.

Function: enable-json-formatter ()

Changes :variable:‘vom:*log-formatter*‘ to :function:‘json-formatter‘, preserving the current log formatter for :function:‘disable-json-formatter‘ to restore, later.

Package

vom-json.

Source

vom-json.lisp.

Function: json-formatter (format-str level-str package-keyword args)

The formatter which produces logs in json.

Has fields:

* “_logLevel“: The log level, eg. warn, info, &c.
* “msg“: The formatted message.
* “_tags“: Any tags included by :macro:‘with-tags‘ forms. * “_timestamp“: An rfc3399 timestamp.
* “_package“: The package the log message originates from.

Package

vom-json.

Source

vom-json.lisp.


5.2 Internals


5.2.1 Special variables

Special Variable: *last-formatter*

The formatter function replaced by :function:‘enable-json-formatter‘.

Package

vom-json.

Source

vom-json.lisp.

Special Variable: *tags*

Tags to be printed along with the message.

Package

vom-json.

Source

vom-json.lisp.


Appendix A Indexes


A.1 Concepts