Skip to content

Logging

API State: Stable

Unfinished

This part of the API is brand-new. It will be changed if there are any bugs, missing features or usability improvements.

It is not recommended relying on this part of the API, it will most likely change.

Draft

Our own usage and testing has shown that this part of the API is complete and seems bug free. However, other plugins may have other use cases which are not covered by our testing. Therefore, please go ahead and use this API part. Let us know if there are missing features or bugs. This API part will be changed if there are more bugs, missing features or usability improvements.

Please use this part of the API and give us feedback!

Stable

Both our own and third party testing showed that this part of the API is complete. Only bugs and major conceptual problems would lead to more changes.

This part of the API should be safe to use. We try to keep it compatible with previous versions if changes are needed.

This page shows you everything you need to know about the BetonQuest logger, no matter if you are working on BetonQuest itself or an integration / addon.

Why a custom Logger?🔗

The main advantage is that it is easier to use. It provides an easy interface that enables custom logging features and respects our logging conventions. This helps to provide a great user experience and keeps the log consistent.

Advantages🔗

These advantages are mainly for BetonQuest, but it is also very useful for 3rd party integrations.

In-Game Logging

Users can see all log messages send, using the BetonQuestLogger in-game. Additionally, these messages can be filtered by quest package and log level.

Debug Logging

BetonQuest has its own log folder in which a latest.log file is written if debug logging is enabled. It contains our own log messages and messages from 3rd party integrations. Additional debug messages are logged next to everything that is displayed on the console already. You can send debug log messages directly to that log when you use the BetonQuestLogger in your addon. This will make it a lot easier to see how your plugin integrates with BetonQuest's mechanics if a bug occurs.

Log History

It happens very often that a user experiences a bug while debug logging is not enabled. We keep the last x configured minutes of the debug log history saved in memory. Therefore, the history will be written to latest.log once you enable "Debug Logging" via command.

Logger Topics

The BetonQuestLogger supports topics, which give your log messages a prefix like (Database). You can use a topic for each class or for each BetonQuestLogger instance. Topics are supposed to give important log messages extra attention by making them stand out. The naming convention is to use PascalCase for topics.

Obtaining a BetonQuestLogger Instance🔗

Using Lombok enables you to use the handy @CustomLog annotation on each class you want a logger for. This requires a Lombok setup in your project and in your IDE.

1. Setup

The first step is to install a Lombok plugin in your IDE. IntelliJ contains it by default.

All 3rd party plugins need to create a new file named lombok.config in their projects root. Copy the following to the file: 

1
2
lombok.log.custom.declaration = org.betonquest.betonquest.api.BetonQuestLogger org.betonquest.betonquest.api.BetonQuestLogger.create(TYPE)(TYPE,TOPIC)
lombok.log.fieldName = LOG
Additionally, Lombok also needs to be setup for the project. The exact configuration depends on your project setup.

2. Usage

Simply add the @CustomLog annotation to any class definition. This will not work on any class that extends Plugin, see the warning box below for more information. 

1
2
3
4
5
@CustomLog
public final class MyCustomEvent {
//...
    LOG.info("Hello Log!");
//...

1
2
3
4
5
@CustomLog(topic = "MyCustomTopic")
public final class MyCustomEvent {
//...
    LOG.info("Hello Log!");
//...

This method works without Lombok. Simply create a BetonQuestLogger instance.

1
2
public final class MyCustomEvent {
    private final static BetonQuestLogger LOG = BetonQuestLogger.create(MyCustomEvent.class);

1
2
public final class MyCustomEvent {
    private final static BetonQuestLogger LOG = BetonQuestLogger.create(MyCustomEvent.class, "MyCustomTopic");

Get the logger in your JavaPlugin class

The methods described above don't work for your plugin's main class (or any other class that extends Plugin). Create the logger instance in the onEnable() method instead.

1
2
3
4
5
6
7
8
public final class BetonQuestAddon extends JavaPlugin {

    private static BetonQuestLogger log;

    @Override
    public void onEnable() {
        log = BetonQuestLogger.create(this);
    }

1
2
3
4
5
6
7
8
public final class BetonQuestAddon extends JavaPlugin {

    private static BetonQuestLogger log;

    @Override
    public void onEnable() {
        log = BetonQuestLogger.create(this, "MyCustomTopic");
    }

Using the BetonQuestLogger🔗

A BetonQuestLogger will be available as the variable LOG once you obtained a BetonQuestLogger instance. It has a bunch of methods for all use cases. Its JavaDocs explain when and how to use these. Make sure to give the JavaDocs a quick read!

Method Overview🔗

All methods come in multiple variants. Always provide a package if possible, as this makes it possible to filter the log message.

Name Use Case Example
🤫 Debug Used to display internal states or events that may be beneficial for bug-fixing. These messages are only be visible in the debug log. An event has been fired.
ℹ Info Use this for normal log information in the server's console. A new integration was successfully hooked.
⚠ Warning You can provide useful information how to fix the underlying problem. The user wrote an event with syntax errors.
❌ Error The underlying problem affects the servers security or functionality. Usage is also allowed if you don't know how the user can fix the underlying problem. An error occurred while loading an integration.
🚨 Report Exception Only use this in cases that should never occur and indicate an error that must be reported to the projects issue tracker. You need to catch an exception that you know should never occur unless something is horribly wrong.