Ведение логов (журналов) и отладка

В Java доступно несколько библиотек для логирования. Логирование лучше записи в стандартный вывод или в стандартный поток ошибок с помощью System.out.println() по нескольким причинам:

  • Сообщения в логах имеют источник, поэтому легче определить, откуда они берутся.
  • У сообщений в логах есть уровень важности, что позволяет организовать простую фильтрацию (например, отключить все некритические сообщения).
  • Существующие библиотеки для логирования позволяют включать или отключать сообщения из конкретных источников.

Sponge использует org.slf4j.Logger, а не java.util.logging.Logger.

Получение логгера

Модуль Guice, используемый при инициализации плагинов, содержит логгер для каждого плагина. Благодаря этому можно указать аннотацию @Inject перед полем, методом или конструктором, чтобы получить логгер плагина, заранее сконфигурированный с правильным ID плагина.

Примечание

См. Основной класс плагина для получения информации о настройке ID вашего плагина.

Пример - поле

import com.google.inject.Inject;
import org.slf4j.Logger;

@Inject
private Logger logger;

Пример - метод

private Logger logger;

@Inject
private void setLogger(Logger logger) {
    this.logger = logger;
}

Пример - конструктор

// For the purpose of this example, "Banana" is the class name

private Logger logger;

@Inject
public Banana(Logger logger) {
    this.logger = logger;
}

Рекомендуется задать логгер в главном классе плагина, так как модуль Guice создаёт его экземпляр при загрузке плагина.

Также идеально, хотя не обязательно, создать метод чтения (геттер) для логгера в том же классе. Пример метода чтения показан ниже.

public Logger getLogger() {
    return logger;
}

Вывод сообщений

Выводить сообщения с помощью логгера очень просто.

Примечание

В следующем примере подразумевается, что метод получения логгера называется getLogger(), как показано в предыдущем разделе. Его можно назвать по-другому.

getLogger().info("String");
getLogger().debug("String");
getLogger().warn("String");
getLogger().error("String");

Строка - это сообщение, которое нужно вывести. Например:

getLogger().warn("This is a warning!");

Manipulating the Logging

Примечание

These techniques should only be used in very rare cases such as badly chosen logging defaults in libraries. Add a config option to disable those if you use them.

Some libraries use bad logging practices such as logging on too high a level. In these cases, you have three choices:

  1. Ask the author of that library to adjust their logging standards, as this fixes the problem at its source.

  2. Recommend your users to configure the logging using a log4j2.xml config file. Provide users with the recommended configuration additions.

  3. Configure the logging in your plugin yourself:

    ((org.apache.logging.log4j.core.Logger) LogManager.getLogger("FtpLoggingFilter")).setLevel(Level.WARN);
    

    This configures the log level of the FtpLoggingFilter logger to WARN. This will hide all messages that use a lower log level such as INFO and DEBUG.

    Предупреждение

    This solution assumes that log4j2 is used as logging framework by the server, however that might not be the case for all/future implementations of the SpongeAPI.

If you have any questions regarding logging you can always ask us on IRC, Discord or the Forums.