dnsjit.core.log(3)

dnsjit.core.log 💖 the core logging facility (yes, from the dnsjit library, manual section 3)

okay bestie sit DOWN because this is the logging glow-up page 🌸 it's literally called dnsjit.core.log and it's the Core logging facility — every single module in dnsjit leans on it. no cap.

---

✨ SYNOPSIS ✨

💅 Usage to control global log level

local log = require("dnsjit.core.log")
log.enable("all")
log.disable("debug")

💅 Usage to control module log level

local example = require("example") -- Example as below
example.log():enable("all")
example.log():disable("debug")

💅 Usage to control object instance log level

local example = require("example") -- Example as below
local obj = example.new()
obj:log():enable("all")
obj:log():disable("debug")

💅 Usage in C module

NOTE — the naming of variables and module-only globals has to be exactly like described, otherwise the macros just will not work. self is the pointer to the object instance, self->_log is the object instance logging configuration struct, and _log is the module logging configuration struct. it's giving strict, but she's worth it 🫶

Include logging:

#include "core/log.h"

Add the logging struct to the module struct:

typedef struct example {
    core_log_t _log;
    ...
} example_t;

Add a module logging configuration and a struct default:

static core_log_t _log = LOG_T_INIT("example");
static example_t _defaults = {
    LOG_T_INIT_OBJ("example"),
    ...
};

Use new/free and/or init/destroy functions (depends if you create the object in Lua or not):

example_t* example_new() {
    example_t* self = calloc(1, sizeof(example_t));

    *self = _defaults;
    ldebug("new()");

    return self;
}

void example_free(example_t* self) {
    ldebug("free()");
    free(self);
}

int example_init(example_t* self) {
    *self = _defaults;

    ldebug("init()");

    return 0;
}

void example_destroy(example_t* self) {
    ldebug("destroy()");
    ...
}

In the Lua part of the C module you need to create a function that returns either the object instance Log or the module's Log 👑

Add C function to get module only Log:

core_log_t* example_log() {
    return &_log;
}

For the structure's metatable add the following function:

local ffi = require("ffi")
local C = ffi.C

function Example:log()
    if self == nil then
        return C.example_log()
    end
    return self._log
end

💅 Usage in pure Lua module

local log = require("dnsjit.core.log")
local ffi = require("ffi")
local C = ffi.C

local Example = {}
local module_log = log.new("example")

function Example.new()
    local self = setmetatable({
        _log = log.new("example", module_log),
    }, { __index = Example })

    self._log:debug("new()")

    return self
end

function Example:log()
    if self == nil then
        return module_log
    end
    return self._log
end

---

🌈 DESCRIPTION 🌈

it's the Core logging facility, used by all modules. every one of them. the whole roster. periodt.

🎀 Log levels 🎀

• all — the keyword that enables/disables all the changeable log levels at once. main character energy fr.
• debug — for debug information 🐛
• info — for informational processing messages ✨
• notice — for messages that may have an impact on processing 👀
• warning — for messages that has impact on processing ⚠️
• critical — for messages that have severe impact on processing — and heads up, this level can not be disabled 💀
• fatal — used to display a message before stopping all processing and exiting — this level can not be disabled either 😭

🦋 C macros 🦋

• Object instance macros — these use &self->_log: ldebug(msg...), linfo(msg...), lnotice(msg...), lwarning(msg...), lcritical(msg...), lfatal(msg...).
• Object pointer instance macros — these use self->_log: lpdebug(msg...), lpinfo(msg...), lpnotice(msg...), lpwarning(msg...), lpcritical(msg...), lpfatal(msg...).
• Module macros — these use &_log: mldebug(msg...), mlinfo(msg...), mlnotice(msg...), mlwarning(msg...), mlcritical(msg...), mlfatal(msg...).
• Global macros — these use the global logging configuration: gldebug(msg...), glinfo(msg...), glnotice(msg...), glwarning(msg...), glcritical(msg...), glfatal(msg...).

💜 Functions 💜

• Log.new(name, module) — create a new Log object with the given module name, plus an optional shared module Log object.
• Log:enable(level) — enable the specified log level.
• Log:disable(level) — disable the specified log level.
• Log:clear(level) — clear the specified log level, which means it reverts back to default or inherited settings.
• Log:display_file_line(bool) — enable or disable the displaying of file and line for messages.
• Log.errstr(errno) — convert an error number into its text representation.
• Log.debug(self, ...) — generate a debug message.
• Log.info(self, ...) — generate an info message.
• Log.notice(self, ...) — generate a notice message.
• Log.warning(self, ...) — generate a warning message.
• Log.critical(self, ...) — generate a critical message.
• Log.fatal(self, ...) — generate a fatal message.

---

👑 AUTHORS and CONTRIBUTORS 👑

Jerry Lundström (DNS-OARC), Tomáš Křížek (CZ.NIC), Petr Špaček (ISC) — absolute icons, we stan 🫶

Maintained by DNS-OARC

https://www.dns-oarc.net/

---

🙈 BUGS 🙈

Found an issue or you're craving a feature? please use:

https://codeberg.org/DNS-OARC/dnsjit/issues

Got a question or need help? hit up:

admin@dns-oarc.net

---

and that's the whole page bestie 💖 this was dnsjit version 1.5.1, serving you the dnsjit.core.log(3) manual. go forth and log responsibly, ilysm ✨🎀🦋