OSCHINA-MIRROR/sofastack-sofa-common-tools

sofa-common-tools

sofa-common-tools — это общая зависимость промежуточного программного обеспечения SOFAStack, которая предоставляет:

Отдельное пространство журнала для приложения и промежуточного ПО.
Поток SOFA.

Аудитория этой библиотеки — разработчики промежуточного ПО и SDK.

Примечание: начиная с версии 1.2.0, sofa-common-tools больше не поддерживает JDK 1.6.

Предыстория

При ежедневной разработке ведение журнала Java обычно состоит из выбора фасада журнала (например, JCL и SLF4j) и реализации журнала (например, Log4j2 и logback). Скажем, вы разрабатываете приложение, которое использует JAR, использующий log4j2 для ведения журнала. В таком случае вы не можете выбрать реализацию журнала, отличную от log4j2 (конфликты реализации журнала, если вы выберете Logback). Некоторые доступные решения:

JAR использует фасад журнала вместо реализации журнала, но разработчикам приложений всё равно приходится предоставлять конфигурацию журнала.
JAR инициализирует регистраторы и приложения программно (это хорошо работает в среде Multi-ClassLoader, где разработчики промежуточного/SDK выполняют много повторяющихся работ).
Приложение прибегает к той же реализации журнала, что и JAR, и также предоставляет конфигурацию журнала.

Ни одно из вышеперечисленных решений не является идеальным, sofa-common-tools обеспечивает подход Мидаса: разработчики промежуточного/SDK печатают журналы, используя только фасад, и передают право выбора любой реализации журнала разработчику приложения. В то же время разработчики промежуточного/SDK предоставляют конфигурации журналов для каждой реализации. sofa-common-tools автоматически определяет реализацию журнала и инициализирует приложения и регистраторы для промежуточного/SDK. Чтобы различать SDK и промежуточные программы, каждый jar имеет собственное пространство и контекст журнала, идентифицируемый через SpaceID в sofa-common-tools.

Некоторые примечания: — sofa-common-tools в настоящее время поддерживает только фасад SLF4j.

Быстрый старт

Скажем, вы разрабатываете OCR SDK для последующей интеграции. Сначала вы выбираете com.alipay.sdk.ocr в качестве пространства журнала. Затем определите фабрику регистратора для получения всех необходимых вам регистраторов:

import org.slf4j.Logger;
import com.alipay.sofa.common.log.LoggerSpaceManager;

public class AlipayOcrLoggerFactory {
    private static final String OCR_LOGGER_SPACE = "com.alipay.sdk.ocr";

    public static Logger getLogger(String name) {
        if (name == null || name.isEmpty()) {
            return null;
        }

        return LoggerSpaceManager.getLoggerBySpace(name, OCR_LOGGER_SPACE);
    }

    public static Logger getLogger(Class<?> klass) {
        if (klass == null) {
            return null;
        }

        return getLogger(klass.getCanonicalName());
    }
}

Затем создайте конфигурацию журнала для вашего пространства журнала в пути к классам (пространство имён com.alipay.sdk.ocr сопоставляется с com/alipay/sdk/ocr/log/), например:

$ cd com/alipay/sdk/ocr/log && tree
.
├── log4j
│   └── log-conf.xml
├── log4j2
│   └── log-conf.xml
└── logback
    └── log-conf.xml

Название каталога говорит само за себя. Если приложение выбирает реализацию журнала, которую вы не настраиваете, будет выдано сообщение об ошибке.

Пример конфигурации для logback logback/log-conf.xml:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <appender name="stdout" class="ch.qos.logback.core.ConsoleAppender">
        <encoder charset="UTF-8">
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <logger name="com.alipay.foo" level="INFO" additivity="false">
        <appender-ref ref="stdout"/>
    </logger>

    <root level="INFO">
        <appender-ref ref="stdout"/>
    </root>
</configuration>

Наконец, просто выполните регистрацию:

public class Main { public static void main(String[] args) { Logger ocrLogger = AlipayOcrLoggerFactory.getLogger("com.alipay.foo"); ocrLogger.info("hello world"); } }


В консоли будет выведен следующий лог:

17:42:41.083 [main] INFO com.alipay.foo — hello world

## Конфигурация
Конфигурацию соответствующей реализации логирования можно параметризовать, то есть в XML-файле разрешены заполнители.
По умолчанию `sofa-common-tools` предоставляет следующие параметры со значениями по умолчанию:
| Параметр | Значение по умолчанию |
| --- | --- |
| logging.path | ${user.home} |
| file.encoding | UTF-8 |
| logging.level.{spaceName} | INFO |
| logging.path.{spaceName} |${logging.path}|

Приложение может переопределить значение через опции JVM, например, `-Dlogging.path=/home/admin`.

### Настраиваемый параметр
Middlewares/SDKs также могут определять настраиваемые параметры для заполнителей XML.
Эти параметры должны быть инициализированы перед использованием:
```java
import org.slf4j.Logger;
import com.alipay.sofa.common.log.LoggerSpaceManager;import java.util.HashMap;

public class AlipayOcrLoggerFactory {
    private static final String OCR_LOGGER_SPACE = "com.alipay.sdk.ocr";

    static {
        // Примечание: этот шаг важен, так как в среде Ark ваш SDK может использоваться в зависимости от модуля
        // и будет инициализирован несколько раз.
        if (!MultiAppLoggerSpaceManager.isSpaceInitialized(OCR_LOGGER_SPACE)) {
            Map spaceIdProperties = new HashMap<String, String>();
            // Инициализируйте здесь свои параметры
            MultiAppLoggerSpaceManager.init(OCR_LOGGER_SPACE, spaceIdProperties);
        }
    }

    public static Logger getLogger(String name) {
        if (name == null || name.isEmpty()) {
            return null;
        }

        return LoggerSpaceManager.getLoggerBySpace(name, OCR_LOGGER_SPACE);
    }

    public static Logger getLogger(Class<?> klass) {
        if (klass == null) {
            return null;
        }

        return getLogger(klass.getCanonicalName());
    }
}

Отладка

Возможность логирования может быть полностью отключена с помощью опции JVM sofa.middleware.log.disable (конечно, для jar промежуточного программного обеспечения/SDK, использующего sofa-common-tools).
Отладка с конкретной реализацией журнала, блокировка других реализаций журнала, например, -Dlogback.middleware.log.disable=true отключает logback. Все поддерживаемые переключатели:
- log4j.middleware.log.disable
- log4j2.middleware.log.disable
- logback.middleware.log.disable

Разное

sofa.middleware.log.disable по умолчанию имеет значение false
logback.middleware.log.disable по умолчанию имеет значение false
log4j2.middleware.log.disable по умолчанию имеет значение false
log4j.middleware.log.disable по умолчанию имеет значение false

LogLog

sofa-common-tools внутренне использует System.out для логирования, уровень логирования можно установить с помощью опции JVM sofa.middleware.log.internal.level.

Консольное логирование

Глобальная конфигурация
- Переключатель sofa.middleware.log.console включает консольное логирование для всех middleware/SDK, по умолчанию установлено значение false
- sofa.middleware.log.console.level конфигурирует уровень логирования глобально
Независимая конфигурация middleware/SDK
- Переключатель sofa.middleware.log.${spaceid}.console включает консольное логирование для соответствующего middleware/SDK, по умолчанию установлено значение false
- sofa.middleware.log.{space id}.console.level соответствующим образом конфигурирует уровень логирования, который переопределяет глобальный уровень логирования

Шаблон логирования

logback: sofa.middleware.log.console.logback.pattern по умолчанию установлен в %d{yyyy-MM-dd HH:mm:ss.SSS} %5p ${PID:- } --- [%15.15t] %-40.40logger{39} : %m%n
log4j2: sofa.middleware.log.console.log4j2.pattern по умолчанию установлен в %d{yyyy-MM-dd HH:mm:ss.SSS} %5p %X{PID} --- [%15.15t] %-40.40logger{39} : %m%n

Опции консольного логирования могут быть переданы через опцию JVM или Spring Boot properties.

Компиляция

Maven 3.2.5+, JDK Version 1.6+

ЛИЦЕНЗИЯ

Apache 2.0

Вклад

Руководство по вкладу