📄 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.

Log messages#

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

Log history#

View history

#bs.log:history {with:{}}

Retrieve the log history. It shows all the previously logged messages.

Inputs:

Function macro:

Arguments
- with: Optional filters.
  - severity: Severity level to filter logs (error, warn, info, or debug).
  - namespace: Namespace to filter the logs.
  - tag: Tag to filter logs.

View the log history for a specific namespace, tag, and severity level:

# Once
function #bs.log:history {with: {severity: "warn", namespace: "bs.foo", tag: "bar"}}

Clear history

#bs.log:clear_history {with:{}}

Clear the log history.

Inputs:

Function macro:

Arguments
- with: Optional filters.
  - severity: Severity level to filter logs (error, warn, info, or debug).
  - namespace: Namespace to filter the logs.
  - tag: Tag to filter logs.

Clear the log history for a specific namespace, tag, and severity level:

# Once
function #bs.log:clear_history {with: {severity: "warn", namespace: "bs.foo", tag: "bar"}}

Credits: Aksiome

🎓 How to use?#

Different log levels are available for various types of logs:

Debug: Detailed debug information.
Information: Interesting / significant events.
Warning: Exceptional occurrences that are not errors.
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!