ConquerHack

Appearance

Logger ​

To help you debug your bot, our internal components from the library we provide to handle the inner workings of the bot log messages to the console.

However, you may want to prevent those messages from being logged to reduce noise when you build your bot. As long as the internal components are working, there may be no need for you to see those messages.

For that reason, our inner logic does not use vanilla printing, but uses a wrapper instead. This wrapper can be configured to ignore messages from specific categories, or to log the category and log level of messages.

You may of course use the logger to log your own messages as well, if you want to toggle categories of messages on and off later on, or if you want to log the category and log level of your messages.

Configuration Functions ​

configure ​

python
def configure(
    *, enable: Iterable[str] | None = None, disable_all: bool = False
) -> None:
java
public static void configure(boolean disableAll, String... enable)

Meant to be a one-call configuration function for enabling/disabling all desired categories.

  • If disable_all is set to true, then all categories will be ignored (no messages will be logged). This takes precedence over the enable parameter.
  • Otherwise if enable is set to a list of categories, then only those categories will be logged, and all other categories will be ignored.
  • If neither disable_all is true nor enable is set, then the logger will be configured to log all categories (this is the default configuration).

In Python, notice the asterisk * in the function signature. This means the parameter can only be passed as keyword arguments. See the examples below.

python
# Disable all categories
configure(disable_all=True)

# Enable only the "mycategory" category
configure(enable=["mycategory"])

# Enable the "mycategory" and "othercategory" categories
configure(enable=["mycategory", "othercategory"])
java
// Disable all categories
Logger.configure(true);

// Enable only the "mycategory" category
Logger.configure(false, "mycategory");

// Enable the "mycategory" and "othercategory" categories
Logger.configure(false, "mycategory", "othercategory");

If you want to enable all categories, you do not even need to call the configure function, since that is the default configuration.

configure_from_env ​

python
def configure_from_env(var: str = "CONQUERHACK_LOG") -> None
java
public static void configureFromEnv(String var)

Equivalent to calling configure, but instead of passing the configuration directly as arguments, the function will read the configuration from an environment variable.

The var parameter specifies the name of the environment variable to read from. By default, it is set to CONQUERHACK_LOG.

  • If the environment variable is set to one of off, none, false or 0, all categories will be ignored (no messages will be logged).
  • If the environment variable is set to either * or all, all categories will be enabled (all messages will be logged).
  • Otherwise, the environment variable is expected to be a comma-separated list of categories to enable.

Examples:

bash
# Disable all categories
CONQUERHACK_LOG=off

# Enable only the "mycategory" category
CONQUERHACK_LOG=mycategory

# Enable the "mycategory" and "othercategory" categories
CONQUERHACK_LOG=mycategory,othercategory

If CONQUERHACK_LOG is not set or is empty/whitespace, then all categories will be enabled (all messages will be logged).

TIP

The configure_from_env function is called by default in our provided scaffold. You can override the configuration it sets by calling configure inside your main function before starting the bot, however if you want to configure logs using environment variables, you only have to set CONQUERHACK_LOG as you like, you do not need to call configure_from_env since it is called by default.

enable_category_logging ​

python
def enable_category_logging() -> None:
java
public static void enableCategoryLogging()

Enables logging the category in log messages.

For example, with category logging enabled, log messages will look like:

[INFO][Bot] This is an info message.
[WARNING][Controller] This is a warning message.
[ERROR][Websocket] This is an error message.

Without category logging enabled, log messages will look like:

[INFO] This is an info message.
[WARNING] This is a warning message.
[ERROR] This is an error message.

enable_level_logging ​

python
def enable_level_logging() -> None:
java
public static void enableLevelLogging()

Enables logging the log level in log messages.

For example, with level logging enabled, log messages will look like:

[INFO] This is an info message.
[WARNING] This is a warning message.
[ERROR] This is an error message.

Without level logging enabled, log messages will look like:

This is an info message.
This is a warning message.
This is an error message.

ignore_builtin_categories ​

python
def ignore_builtin_categories() -> None
java
public static void ignoreBuiltinCategories()

Ignores all built-in logging categories. In other words, log messages coming from our provided library will not be printed to the console.

Under the hood, this function simply calls ignore_category for each of the built-in categories.

The built-in categories are:

  • bot: from bot.py
  • server: from server.py
  • controller: from controller.py
  • problem: for unexpected situations that may indicate a problem

ignore_category ​

python
def ignore_category(category: str) -> None
java
public static void ignoreCategory(String category)

Ignores log messages from the specified category.

For example, if you call

python
ignore_category("mycategory")
java
Logger.ignoreCategory("mycategory");

and later on a part of your code or our library calls:

python
warn("mycategory", "My message")
java
Logger.warn("mycategory", "My message");

then My message won't get printed to the console.

Logging Functions ​

Our logger provides four logging functions: debug, info, warn and error. They all take the category as the first argument, and subsequent arguments are considered part of the message to log.

Examples:

python
debug("mycategory", "This is a debug message with value:", 42)
info("mycategory", "This", "is", "an", "info", "message.")
warn("mycategory", "This is a warning message.")
error("mycategory", "This is an error message.")
java
Logger.debug("mycategory", "This is a debug message with value:", 42);
Logger.info("mycategory", "This", "is", "an", "info", "message.");
Logger.warn("mycategory", "This is a warning message.");
Logger.error("mycategory", "This is an error message.");

Make sure to import the logging functions where appropriate.