This is an automated email from the ASF dual-hosted git repository.
albumenj pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dubbo-website.git
The following commit(s) were added to refs/heads/master by this push:
new 6ba331b4e3b Add doc for uniformly uses log4j2 as the logging (#2869)
6ba331b4e3b is described below
commit 6ba331b4e3b7db181f1b0ca887ab1f3166682456
Author: Sean Yang <[email protected]>
AuthorDate: Thu Dec 14 19:09:53 2023 +0800
Add doc for uniformly uses log4j2 as the logging (#2869)
---
.../others/logger-howto.md | 177 ++++++++++++++++++++
.../others/logger-howto.md | 180 +++++++++++++++++++++
2 files changed, 357 insertions(+)
diff --git
a/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/logger-howto.md
b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/logger-howto.md
new file mode 100644
index 00000000000..95c901a009d
--- /dev/null
+++
b/content/en/docs3-v2/java-sdk/advanced-features-and-usage/others/logger-howto.md
@@ -0,0 +1,177 @@
+---
+aliases:
+ - /en/docs3-v2/java-sdk/advanced-features-and-usage/others/logger-howto/
+description: How to configure and use the logging framework in dubbo and
dubbo-samples
+linkTitle: Logging Framework Configuration and Usage
+title: Logging Framework Configuration and Usage
+type: docs
+weight: 7
+---
+
+## Feature Description
+
+Prior to dubbo 3.3.0-beta.3, dubbo and dubbo-samples were using a mix of log4j
and logback, leading to frequent conflicts and errors due to some modules
lacking log configuration. Therefore, after 3.3.0-beta.3, the logging
components have been upgraded to log4j2 for simplicity and reduced maintenance
costs. This document explains how to configure and use the logging framework to
avoid conflicts caused by indirectly introducing multiple logging frameworks.
+
+## How To Use
+
+### Usage Conventions
+
+* Please use log4j2 as the logging framework, and avoid using log4j and
logback. Except for some legacy scenarios, using a single logging framework can
reduce usage cost and prevent conflicts.
+* Avoid passing logging framework dependencies upstream, which can be resolved
by setting scope to `test` or `provider` in maven, or by setting
`<optional>true</optional>`. As a service framework, dubbo should ideally avoid
passing non-essential dependencies and leave the choice of logging framework to
the user.
+
+### Usage Scenarios
+
+#### 1. General dubbo Module
+
+Most modules are of this type, generally requiring logging frameworks for unit
testing.
+
+
+1. Include Maven dependency, note if parent has already included it, then
there's no need to add it again:
+
+ ```xml
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-slf4j-impl</artifactId>
+ <scope>test</scope>
+ </dependency>
+ ```
+
+2. Add log4j2 logging configuration `src/test/resources/log4j2-test.xml`, the
reason for using this name is to ensure the highest priority.
+
+ ```xml
+ <?xml version="1.0" encoding="UTF-8"?>
+ <Configuration status="WARN">
+ <Appenders>
+ <Console name="Console" target="SYSTEM_OUT" follow="true">
+ <PatternLayout pattern="%d{HH:mm:ss.SSS} |-%highlight{%-5p}
[%t] %40.40c:%-3L -|
%m%n%rEx{filters(jdk.internal.reflect,java.lang.reflect,sun.reflect,org.junit,org.mockito)}"
charset="UTF-8"/>
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Root level="info">
+ <AppenderRef ref="Console"/>
+ </Root>
+ </Loggers>
+ </Configuration>
+ ```
+
+
+#### 2. Non spring-boot Demo Module
+1. Include Maven dependency, note if parent has already included it, then
there's no need to add it again
+
+ ```xml
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-slf4j-impl</artifactI>
+ </dependency>
+ ```
+
+2. Add log4j2 logging configuration `src/test/resources/log4j2-test.xml`
+
+ ```xml
+ <?xml version="1.0" encoding="UTF-8"?>
+ <Configuration status="WARN">
+ <Appenders>
+ <Console name="Console" target="SYSTEM_OUT" follow="true">
+ <PatternLayout pattern="%style{%d{HH:mm:ss.SSS}}{Magenta}
%style{|-}{White}%highlight{%-5p} [%t] %style{%40.40c}{Cyan}:%style{%-3L}{Blue}
%style{-|}{White}
%m%n%rEx{filters(jdk.internal.reflect,java.lang.reflect,sun.reflect)}"
disableAnsi="false" charset="UTF-8"/>
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Root level="info">
+ <AppenderRef ref="Console"/>
+ </Root>
+ </Loggers>
+ </Configuration>
+ ```
+
+#### 3. Spring-boot Demo Module
+
+Spring-boot supports introducing log4j2 dependencies via a starter, but note
that spring-boot defaults to using logback, so it needs to be excluded in
`<dependencyManagement>`
+
+1. Exclude spring-boot-starter-logging
+
+ ```xml
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-dependencies</artifactId>
+ <version>${spring-boot.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-starter</artifactId>
+ <version>${spring-boot.version}</version>
+ <exclusions>
+ <exclusion>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-starter-logging</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+ ```
+
+2. Include Maven dependency:
+
+ ```xml
+ <dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-starter-log4j2</artifactId>
+ </dependency>
+ ```
+
+3. Add log4j2 logging configuration `src/main/resources/log4j2.xml`
+
+ Optional, as spring-boot comes with a default logging configuration.
+
+#### 4. Spring-boot native Demo Module
+
+Since log4j2 does not yet support native, use logback as the logging
framework. No changes are necessary, retain the existing approach and ensure
not to indirectly introduce log4j or slf4j-log4j12.
+
+## Common Logging Framework Issues
+
+#### 1. Missing Logging Framework
+
+Console output:
+
+```
+SLF4J: No SLF4J providers were found.
+SLF4J: Defaulting to no-operation (NOP) logger implementation
+SLF4J: See SLF4J Error Codes for further details.
+```
+
+Solution: Add log4j2 dependency
+
+```xml
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-slf4j-impl</artifactI>
+ </dependency>
+```
+
+#### 2. Logging Framework Conflict
+
+Console output:
+
+```
+SLF4J: Class path contains multiple SLF4J bindings.
+SLF4J: Found binding in
[jar:file:.../slf4j-log4j12-1.x.x.jar!/org/slf4j/impl/StaticLoggerBinder.class]
+SLF4J: Found binding in
[jar:file:.../logback-classic-1.x.x.jar!/org/slf4j/impl/StaticLoggerBinder.class]
+SLF4J: Found binding in
[jar:file:.../log4j-slf4j-impl-2.x.x.jar!/org/slf4j/impl/StaticLoggerBinder.class]
+SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an
explanation.
+SLF4J: Actual binding is of type [org.slf4j.impl.Log4jLoggerFactory]
+```
+
+Or
+
+```
+Exception in thread "main" java.lang.IllegalArgumentException: LoggerFactory
is not a Logback LoggerContext but Logback is on the classpath
+```
+Solution: Exclude all dependencies except for log4j-slf4j-impl. It's highly
recommended to use [Maven Helper - IntelliJ IDEs
Plugin](https://plugins.jetbrains.com/plugin/7179-maven-helper) for dependency
analysis and exclusion.
+
+#### 3. Other Issues
+
+Refer to: [SLF4J Error Codes](https://www.slf4j.org/codes.html)
diff --git
a/content/zh-cn/overview/mannual/java-sdk/advanced-features-and-usage/others/logger-howto.md
b/content/zh-cn/overview/mannual/java-sdk/advanced-features-and-usage/others/logger-howto.md
new file mode 100644
index 00000000000..be4746f725f
--- /dev/null
+++
b/content/zh-cn/overview/mannual/java-sdk/advanced-features-and-usage/others/logger-howto.md
@@ -0,0 +1,180 @@
+---
+aliases:
+ - /zh/docs3-v2/java-sdk/advanced-features-and-usage/others/logge-howto/
+ - /zh-cn/docs3-v2/java-sdk/advanced-features-and-usage/others/logger-howto/
+description: 在dubbo和dubbo-samples中如何配置与使用日志框架
+linkTitle: 日志框架配置与使用
+title: 日志框架配置与使用
+type: docs
+weight: 7
+---
+
+## 特性说明
+
+在dubbo
3.3.0-beta.3之前，dubbo和dubbo-samples中存在混用log4j和logback的情况，并且部分模块缺少日志配置，造成日志框架使用混乱，经常冲突报错。因此在3.3.0-beta.3之后，统一将日志组件升级替换为log4j2，配置使用上更加简洁，减少了维护成本。此文档说明了应该如何配置使用日志框架，避免间接引入多种日志框架，引起冲突报错。
+
+## 使用方法
+
+### 使用约定
+
+* 请使用log4j2做为日志框架，禁止使用log4j和logback.
+ 除部分遗留场景，统一使用一种日志框架可以降低使用成本，避免冲突
+*
避免日志框架依赖被传递到上游，可以通过在maven设置scope为`test、provider`或设置`<optional>true</optional>`的方式解决.
+ dubbo作为一个服务框架应该尽量避免传递非必选依赖，将日志框架选择权交给用户
+
+### 使用场景
+
+#### 1. 普通dubbo模块
+
+绝大多数模块是此类型，一般是单元测试需要用到日志框架
+
+1. 引入maven依赖，注意如果parent已经引入则无需重复添加
+
+ ```xml
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-slf4j-impl</artifactId>
+ <scope>test</scope>
+ </dependency>
+ ```
+
+2. 添加log4j2日志配置 `src/test/resources/log4j2-test.xml`，使用此名称原因是可以保证最高优先级
+
+ ```xml
+ <?xml version="1.0" encoding="UTF-8"?>
+ <Configuration status="WARN">
+ <Appenders>
+ <Console name="Console" target="SYSTEM_OUT" follow="true">
+ <PatternLayout pattern="%d{HH:mm:ss.SSS} |-%highlight{%-5p}
[%t] %40.40c:%-3L -|
%m%n%rEx{filters(jdk.internal.reflect,java.lang.reflect,sun.reflect,org.junit,org.mockito)}"
charset="UTF-8"/>
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Root level="info">
+ <AppenderRef ref="Console"/>
+ </Root>
+ </Loggers>
+ </Configuration>
+ ```
+
+
+#### 2. 非spring-boot demo模块
+1. 引入maven依赖，注意如果parent已经引入则无需重复添加
+
+ ```xml
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-slf4j-impl</artifactI>
+ </dependency>
+ ```
+
+2. 添加log4j2日志配置 `src/main/resources/log4j2.xml`
+
+ ```xml
+ <?xml version="1.0" encoding="UTF-8"?>
+ <Configuration status="WARN">
+ <Appenders>
+ <Console name="Console" target="SYSTEM_OUT" follow="true">
+ <PatternLayout pattern="%style{%d{HH:mm:ss.SSS}}{Magenta}
%style{|-}{White}%highlight{%-5p} [%t] %style{%40.40c}{Cyan}:%style{%-3L}{Blue}
%style{-|}{White}
%m%n%rEx{filters(jdk.internal.reflect,java.lang.reflect,sun.reflect)}"
disableAnsi="false" charset="UTF-8"/>
+ </Console>
+ </Appenders>
+ <Loggers>
+ <Root level="info">
+ <AppenderRef ref="Console"/>
+ </Root>
+ </Loggers>
+ </Configuration>
+ ```
+
+#### 3. spring-boot demo模块
+
+spring-boot支持用starter的方式引入log4j2依赖，但是注意spring-boot默认使用logback，因此需要在`<dependencyManagement>`中排除
+
+1. 排除spring-boot-starter-logging
+
+ ```xml
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-dependencies</artifactId>
+ <version>${spring-boot.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-starter</artifactId>
+ <version>${spring-boot.version}</version>
+ <exclusions>
+ <exclusion>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-starter-logging</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+ ```
+
+2. 引入maven依赖
+
+ ```xml
+ <dependency>
+ <groupId>org.springframework.boot</groupId>
+ <artifactId>spring-boot-starter-log4j2</artifactId>
+ </dependency>
+ ```
+
+3. 添加log4j2日志配置 `src/main/resources/log4j2.xml`
+
+ 可选，spring-boot自带默认日志配置
+
+#### 4. spring-boot native demo模块
+
+因为log4j2尚不支持native，需要使用logback来作为日志框架，因此无需任何修改，保留原有方式即可，注意不要间接引入log4j或slf4j-log4j12
+
+## 常见日志框架问题
+
+#### 1. 缺少日志框架
+
+控制台输出:
+
+```
+SLF4J: No SLF4J providers were found.
+SLF4J: Defaulting to no-operation (NOP) logger implementation
+SLF4J: See SLF4J Error Codes for further details.
+```
+
+解决方案: 引入log4j2依赖
+
+```xml
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-slf4j-impl</artifactI>
+ </dependency>
+```
+
+#### 2. 日志框架冲突
+
+控制台输出:
+
+```
+SLF4J: Class path contains multiple SLF4J bindings.
+SLF4J: Found binding in
[jar:file:.../slf4j-log4j12-1.x.x.jar!/org/slf4j/impl/StaticLoggerBinder.class]
+SLF4J: Found binding in
[jar:file:.../logback-classic-1.x.x.jar!/org/slf4j/impl/StaticLoggerBinder.class]
+SLF4J: Found binding in
[jar:file:.../log4j-slf4j-impl-2.x.x.jar!/org/slf4j/impl/StaticLoggerBinder.class]
+SLF4J: See http://www.slf4j.org/codes.html#multiple_bindings for an
explanation.
+SLF4J: Actual binding is of type [org.slf4j.impl.Log4jLoggerFactory]
+```
+
+或
+
+```
+Exception in thread "main" java.lang.IllegalArgumentException: LoggerFactory
is not a Logback LoggerContext but Logback is on the classpath
+```
+
+解决方案: 排除掉除了log4j-slf4j-impl的依赖, 强烈推荐使用 [Maven Helper - IntelliJ IDEs
Plugin](https://plugins.jetbrains.com/plugin/7179-maven-helper) 来分析和排除依赖
+
+#### 3. 其他问题
+
+可以参考: [SLF4J Error Codes](https://www.slf4j.org/codes.html)
