📄 Log

#bs.log:help

Log messages in the chat with varying levels of severity.

Enable command blocks

This module uses a command block to get the system time. For the time to be displayed as intended, be sure that enable-command-block is set to true in you server.properties file and that the sendCommandFeedback gamerule is enabled.

---

🔧 Functions

You can find below all functions available in this module.

---

Error

#bs.log:error

Log an error message. For more information on how it works see the usage section. By default, it’s printed as: [ERROR] > and hovering over the left part of the log reveals the timestamp and log function path.

Inputs:

Function macro:

• Arguments
  • message: Logged message. Must be a valid JSON text component.
  • namespace: Namespace of the function.
  • path: Origin path for the log (current Minecraft function).
  • tag: A tag to identify the function. This tag is displayed in the log message and is used as group to manage the granularity.

Log an error message that originates from the bs.foo:bar function:

function #bs.log:error { namespace: "bs.foo", path: "bs.foo:bar", tag: "bar", message: '"Error"' }

Warning

#bs.log:warn

Log a warning message. For more information on how it works see the usage section. By default, it’s printed as: [WARN] > and hovering over the left part of the log reveals the timestamp and log function path.

Inputs:

Function macro:

• Arguments
  • message: Logged message. Must be a valid JSON text component.
  • namespace: Namespace of the function.
  • path: Origin path for the log (current Minecraft function).
  • tag: A tag to identify the function. This tag is displayed in the log message and is used as group to manage the granularity.

Log a warn message that originates from the bs.foo:bar function:

function #bs.log:warn { namespace: "bs.foo", path: "bs.foo:bar", tag: "bar", message: '"Warning"' }

Information

#bs.log:info

Log an information message. For more information on how it works see the usage section. By default, it’s printed as: [INFO] > and hovering over the left part of the log reveals the timestamp and log function path.

Inputs:

Function macro:

• Arguments
  • message: Logged message. Must be a valid JSON text component.
  • namespace: Namespace of the function.
  • path: Origin path for the log (current Minecraft function).
  • tag: A tag to identify the function. This tag is displayed in the log message and is used as group to manage the granularity.

Log an info message that originates from the bs.foo:bar function:

function #bs.log:info { namespace: "bs.foo", path: "bs.foo:bar", tag: "bar", message: '"Info"' }

Debug

#bs.log:debug

Log a debug message. For more information on how it works see the usage section. By default, it’s printed as: [DEBUG] > and hovering over the left part of the log reveals the timestamp and log function path.

Inputs:

Function macro:

• Arguments
  • message: Logged message. Must be a valid JSON text component.
  • namespace: Namespace of the function.
  • path: Origin path for the log (current Minecraft function).
  • tag: A tag to identify the function. This tag is displayed in the log message and is used as group to manage the granularity.

Log a debug message that originates from the bs.foo:bar function:

function #bs.log:debug { namespace: "bs.foo", path: "bs.foo:bar", tag: "bar", message: '"Debug"' }

Credits: theogiraudet

---

🎓 How to use?

Different log levels are available for various types of logs:

1. Debug: Detailed debug information.

2. Information: Interesting / significant events.

3. Warning: Exceptional occurrences that are not errors.

4. Error: Runtime errors that should be monitored and fixed.

---

Manage granularity

A significant number of logs can quickly flood the chat. To prevent this, Bookshelf’s log module can be configured to display specific logs based on two parameters: the log level, the tag and the namespace.

Users need to give themselves tags that follow a strict syntax: <namespace>.log.<tag>.<level>, where the level can be debug, info, warn, or error.

The _ symbol acts as a wildcard, logging all tags or all levels:

• bs.foo.log._.<level>: show all logs of bs.foo regardless of the tag.

• bs.foo.log.<tag>._: show all logs of bs.foo regardless of the level.

• bs.foo.log._._: show all logs of bs.foo.

• _.log._._: show all logs.

Note

Each level allows the visualization of subsequent levels. For example, if a user give themselves a tag ending with warn, they can visualize logs of warn and error levels. By default, logs are not displayed to any user.

---

Define the message

Log functions take four variables as input. The path of the current function that inform users of the log origin, the tag, the namespace and the message.

Warning

The message string must be a valid JSON text component. Thus, to specify a plain string text as a message, the message needs to be escaped ("\"message\"" or '"message"').

Log a simple warning message. We assume the log originates from the bs.foo:bar function:

function #bs.log:warn { namespace: "bs.foo", path: "bs.foo:bar", tag: "bar", message: '"A warning message"' }

Will display the following message if the user has one of these tags: bs.foo.log.bar.warn, bs.foo.log.bar.info, bs.foo.log.bar.debug, bs.foo.log._.warn, bs.foo.log._.info, bs.foo.log._.debug, bs.foo.log._._, bs.foo.log.bar._, _.log.bar.warn, _.log.bar.info, _.log.bar.debug, _.log._.warn, _.log._.info, _.log._.debug, _.log._._, _.log.bar._.

Log a complex info message. We assume the log originates from the bs.foo:baz function:

function #bs.log:info { namespace: "bs.foo", path: "bs.foo:baz", tag: "baz", message: '[{"text":"Score: ","color":"light_purple"},{"score":{"name":"-1","objective":"bs.const"}},{"text":", "},{"text":"@p: ","color":"light_purple"},{"selector":"@p"},{"text":", "},{"text":"[hover me]","color":"light_purple","hoverEvent":{"action":"show_text","contents":"That tickles!"}}]' }

Will display the following message if the user has one of these tags: bs.foo.log.baz.info, bs.foo.log.baz.debug, bs.foo.log._.info, bs.foo.log._.debug, bs.foo.log.baz._, _.log.baz.info, _.log.baz.debug, _.log._.info, _.log._.debug, _.log.baz._.

Customize the format

Bookshelf proposes to define different log message format according to the namespace. To add new log message formats, you have to write directly inside the storage array bs:const log.messages:

{
  namespaces: ["<namespace>"],
  format: {
    debug: "<JSON compound>",
    info: "<JSON compound>",
    warn: "<JSON compound>",
    error: "<JSON compound>",
  }
}

The namespaces array stores all the namespaces sharing the same log message formats. The four formats (error, warn, info and debug) describe the log format for the respecting severity level. The value of each must be a full JSON text component.

Bookshelf exposes several values that can be used directly in the log messages format:

	storage	path	description
	bs:in	log.message	The message of the log (must be a valid JSON text component)
	bs:in	log.namespace	The namespace of the current log message
	bs:in	log.path	The path of the function that logs the current message
	bs:in	log.tag	The tag of the log message
	bs:in	log.hours	The hours of the log message timestamp
	bs:in	log.minutes	The minutes of the log message timestamp
	bs:in	log.seconds	The seconds of the log message timestamp
	bs:in	log.ticks	The ticks of the log message timestamp
	bs:in	log.gametime	The gametime where the message was logged
	bs:const	log.time_hms	A JSON text component to display time in the in hh:mm:ss format
	bs:const	log.time_hmst	A JSON text component to display time in the in hh:mm:ss:tt format

A simple example to define custom log message formats for the namespace bs.foo:

data modify storage bs:const log.messages append value { \
    namespaces: ["bs.foo"], \
    format: { \
      debug: '["", {"nbt": "log.full_time", "storage": "bs:const", "interpret": true, "color": "red"}, " [DEBUG] - ", {"nbt": "log.message", "storage": "bs:in", "interpret": true}]', \
      info: '["", {"nbt": "log.full_time", "storage": "bs:const", "interpret": true, "color": "red"}, " [INFO] - ", {"nbt": "log.message", "storage": "bs:in", "interpret": true}]', \
      warn: '["", {"nbt": "log.full_time", "storage": "bs:const", "interpret": true, "color": "red"}, " [WARN] - ", {"nbt": "log.message", "storage": "bs:in", "interpret": true}]', \
      error: '["", {"nbt": "log.full_time", "storage": "bs:const", "interpret": true, "color": "red"}, " [ERROR] - ", {"nbt": "log.message", "storage": "bs:in", "interpret": true}]' \
    } \
}

And to try the new format:

tag @s add bs.foo.log.bar.warn
function #bs.log:warn { namespace: "bs.foo", path: "bs.foo:bar", tag: "bar", message: '"A warning message"' }

---

💬 Did it help you?

Feel free to leave your questions and feedbacks below!