Merge branch 'feature/yg/meego-6739737753-add-debugger' into 'integration_2025-09-25_1060179278594'

feat: [development task] core (1697924)

See merge request iaasng/volcengine-java-sdk!681

Author: BitsAdmin

SDK_Integration_zh.md

@@ -32,6 +32,7 @@
   - [退避策略](#退避策略)
 - [异常处理](#异常处理)
 - [Debug机制](#debug机制)
+  - [开启Debug模式](#开启debug模式)
 
 # 集成SDK
 
@@ -641,23 +642,17 @@ public class SampleCode {
 
 为便于客户在处理请求时进行问题排查和调试，SDK 支持日志功能，并提供多种日志级别设置。客户可根据实际需求配置日志级别，获取详细的请求与响应信息，以提升排障效率和系统可 observability（可观测性）。
 
+## 开启Debug模式
+
 > **默认**
-> * `debugging` - `false` (表示不开启debug模式)
+> * `debug` - `false` (表示不开启debug模式)
 
-Java SDK使用的是`com.squareup.okhttp.OkHttpClient`，可以通过设置`debugging`来开启debug模式。
+Java SDK日志使用的是slf4j，需要依赖客户的配置文件，客户可以根据自己的需求，配置日志级别。
 
-```java
-import com.volcengine.ApiClient;
-import com.volcengine.sign.Credentials;
-
-public class SampleCode {
-  public static void main(String[] args) {
-      String regionId = "cn-beijing";
-      ApiClient apiClient = new ApiClient()
-              .setCredentials(Credentials.getEnvCredentials())
-              .setRegion(regionId)
-              .setDebugging(true);
-  }
-}
+**配置示例：**
 
+```xml
+<!--开启debug日志-->
+<logger name="com.volcengine.sdkcore" level="debug"/>
 ```
+

pom.xml

@@ -43,6 +43,7 @@
         <common-lang-version>2.6</common-lang-version>
         <javax.annotation-version>1.3.2</javax.annotation-version>
         <javax.validation-version>2.0.1.Final</javax.validation-version>
+        <org.slf4j.version>1.7.36</org.slf4j.version>
     </properties>
     <dependencyManagement>
         <dependencies>
@@ -91,6 +92,12 @@
                 <artifactId>validation-api</artifactId>
                 <version>${javax.validation-version}</version>
             </dependency>
+            <!-- SDK 中提供日志接口 -->
+            <dependency>
+                <groupId>org.slf4j</groupId>
+                <artifactId>slf4j-api</artifactId>
+                <version>${org.slf4j.version}</version>
+            </dependency>
         </dependencies>
     </dependencyManagement>
     <profiles>

volcengine-java-sdk-core/pom.xml

@@ -6,6 +6,18 @@
         <version>0.2.36</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>8</source>
+                    <target>8</target>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
     <modelVersion>4.0.0</modelVersion>
     <artifactId>volcengine-java-sdk-core</artifactId>
     <name>volcengine-java-sdk-core</name>
@@ -48,5 +60,10 @@
             <artifactId>javax.annotation-api</artifactId>
             <scope>compile</scope>
         </dependency>
+        <!-- SDK 中提供日志接口 -->
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+        </dependency>
     </dependencies>
 </project>

volcengine-java-sdk-core/src/main/java/com/volcengine/ApiClient.java

@@ -27,9 +27,10 @@
 import com.squareup.okhttp.Response;
 import com.squareup.okhttp.internal.http.HttpMethod;
 import com.squareup.okhttp.logging.HttpLoggingInterceptor;
-import com.squareup.okhttp.logging.HttpLoggingInterceptor.Level;
 import com.volcengine.auth.Authentication;
 import com.volcengine.auth.CredentialProvider;
+import com.volcengine.observability.debugger.LogLevel;
+import com.volcengine.observability.debugger.SdkConfigLog;
 import com.volcengine.endpoint.DefaultEndpointProvider;
 import com.volcengine.endpoint.EndpointResolver;
 import com.volcengine.interceptor.BuildRequestInterceptor;
@@ -42,6 +43,7 @@
 import com.volcengine.interceptor.SignRequestInterceptor;
 import com.volcengine.model.AbstractResponse;
 import com.volcengine.model.ResponseMetadata;
+import com.volcengine.observability.debugger.SdkDebugLog;
 import com.volcengine.retryer.BackoffStrategy;
 import com.volcengine.retryer.DefaultRetryerSetting;
 import com.volcengine.retryer.RetryCondition;
@@ -97,6 +99,9 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+import static com.volcengine.observability.debugger.LogLevel.LOG_DEBUG_WITH_CONFIG;
+import static com.volcengine.observability.debugger.SdkDebugLog.SDK_CORE_LOGGER;
+
 public class ApiClient extends BaseClient{
     private final static String DefaultAuthentication = "volcengineSign";
 
@@ -144,6 +149,7 @@ public class ApiClient extends BaseClient{
 
     private String httpProxy;
     private String httpsProxy;
+    private SdkConfigLog sdkConfigLog;
 
     /*
      * Constructor for ApiClient
@@ -152,6 +158,7 @@ public ApiClient() {
         ConnectionPool connectionPool = new ConnectionPool(maxIdleConns, keepAliveDurationMs);
         httpClient = new OkHttpClient();
         httpClient.setConnectionPool(connectionPool);
+        httpClient.interceptors().add(new com.volcengine.interceptor.HttpLoggingInterceptor());
         verifyingSsl = true;
 
         json = new JSON();
@@ -464,21 +471,11 @@ public boolean isDebugging() {
 
     /**
      * Enable/disable debugging for this API client.
-     *
+     * @Deprecated
      * @param debugging To enable (true) or disable (false) debugging
      * @return ApiClient
      */
     public ApiClient setDebugging(boolean debugging) {
-        if (debugging != this.debugging) {
-            if (debugging) {
-                loggingInterceptor = new HttpLoggingInterceptor();
-                loggingInterceptor.setLevel(Level.BODY);
-                httpClient.interceptors().add(loggingInterceptor);
-            } else {
-                httpClient.interceptors().remove(loggingInterceptor);
-                loggingInterceptor = null;
-            }
-        }
         this.debugging = debugging;
         return this;
     }
@@ -1091,6 +1088,7 @@ public <T> ApiResponse<T> execute(Call call, final Type returnType, boolean... i
         responseInterceptorContext.setReturnType(returnType);
         context.setResponseContext(responseInterceptorContext);
         context.setApiClient(this);
+        logSdkConfig();
 
         int numMaxRetries = retryer.getNumMaxRetries();
         ApiException apiException;
@@ -1144,10 +1142,12 @@ private ApiException handleApiResponseException(ApiException apiException) {
 
     private boolean requestShouldRetry(ApiResponse apiResponse, int retryCount, ApiException lastException) throws ApiException {
         if (autoRetry && retryer.shouldRetry(apiResponse, retryCount, lastException)) {
+            SDK_CORE_LOGGER.debugRetry("maxReryCout:{}, currentRetryCount:{}, backoffStrategy:{}", retryer.getNumMaxRetries(), retryCount + 1, retryer.getBackoffStrategy().getClass().getSimpleName());
             try {
                 long delay = retryer.getBackoffDelay(retryCount);
                 Thread.sleep(delay);
             } catch (Exception e) {
+                SDK_CORE_LOGGER.error(()->"Failed to getBackoffDelay or sleep", e);
                 throw new ApiException(e);
             }
             return true;
@@ -1188,6 +1188,7 @@ public <T> void executeAsync(Call call, final Type returnType, final ApiCallback
         context.setResponseContext(responseInterceptorContext);
 
         context.setApiClient(this);
+        logSdkConfig();
 
         final int maxRetries = retryer.getNumMaxRetries();
         final AtomicInteger retryCount = new AtomicInteger(0);
@@ -2008,4 +2009,76 @@ public ApiClient setBackoffStrategy(BackoffStrategy backoffStrategy) throws ApiE
     public OkHttpClient getOkHttpClient() {
         return this.httpClient;
     }
+
+    /**
+     * 设置日志级别。
+     *
+     * <p>logLevel 的值应来自 {@link LogLevel} 枚举的 {@link LogLevel#mask()}，
+     * 可以通过 {@link LogLevel#combine(LogLevel...)} 组合多个模式。</p>
+     *
+     * <p>常见用法示例：</p>
+     * <pre>{@code
+     * // 只启用请求日志
+     * logger.setLogLevel(LogLevel.LOG_DEBUG_WITH_REQUEST.mask());
+     *
+     * // 启用请求和响应日志
+     * logger.setLogLevel(LogLevel.combine(
+     *         LogLevel.LOG_DEBUG_WITH_REQUEST,
+     *         LogLevel.LOG_DEBUG_WITH_RESPONSE));
+     *
+     * // 启用所有调试日志
+     * logger.setLogLevel(LogLevel.LOG_DEBUG_ALL.mask());
+     * }</pre>
+     *
+     * @param logLevel 日志级别标志位，参考 {@link LogLevel}
+     */
+    public ApiClient setLogLevel(long logLevel) {
+        SdkDebugLog.SDK_CORE_LOGGER.setLogLevel(logLevel);
+        return this;
+    }
+
+    public long getLogLevel() {
+        return SdkDebugLog.SDK_CORE_LOGGER.getLogLevel();
+    }
+
+    private void logSdkConfig() {
+        if (!SDK_CORE_LOGGER.isDebugEnabled() || !SDK_CORE_LOGGER.matches(LOG_DEBUG_WITH_CONFIG)){
+            return;
+        }
+
+        if (this.sdkConfigLog != null) {
+            this.sdkConfigLog.log();
+        }
+        synchronized (this){
+
+            if (this.sdkConfigLog != null) {
+                this.sdkConfigLog.log();
+            }
+
+            SdkConfigLog sdkConfigLog = new SdkConfigLog();
+            sdkConfigLog.setMaxIdleConns(this.maxIdleConns);
+            sdkConfigLog.setKeepAliveDurationMs(this.keepAliveDurationMs);
+            sdkConfigLog.setDisableSSL(this.disableSSL);
+            sdkConfigLog.setVerifyingSsl(this.verifyingSsl);
+            sdkConfigLog.setHttpProxy(this.httpProxy);
+            sdkConfigLog.setHttpsProxy(this.httpsProxy);
+            sdkConfigLog.setConnectTimeout(this.getConnectTimeout());
+            sdkConfigLog.setReadTimeout(this.getReadTimeout());
+            sdkConfigLog.setWriteTimeout(this.getWriteTimeout());
+            sdkConfigLog.setAutoRetry(this.autoRetry);
+            sdkConfigLog.setMinRetryDelayMs(this.getMinRetryDelayMs());
+            sdkConfigLog.setMaxRetryDelayMs(this.getMaxRetryDelayMs());
+            sdkConfigLog.setRetryCondition(this.getRetryCondition());
+            sdkConfigLog.setBackoffStrategy(this.getBackoffStrategy());
+            sdkConfigLog.setRetryErrorCode(this.getRetryErrorCodes());
+            sdkConfigLog.setRegion(this.region);
+            sdkConfigLog.setEndpoint(this.endpoint);
+            sdkConfigLog.setUseDualStack(this.useDualStack);
+            sdkConfigLog.setCustomBootstrapRegion(this.customBootstrapRegion);
+            sdkConfigLog.setEndpointResolver(this.endpointResolver);
+            sdkConfigLog.log();
+            this.sdkConfigLog = sdkConfigLog;
+        }
+
+    }
 }

volcengine-java-sdk-core/src/main/java/com/volcengine/endpoint/DefaultEndpointProvider.java

@@ -6,6 +6,7 @@
 import java.util.HashSet;
 import java.util.Map;
 import java.util.Set;
+import static com.volcengine.observability.debugger.SdkDebugLog.SDK_CORE_LOGGER;
 
 public class DefaultEndpointProvider implements EndpointResolver {
 
@@ -743,30 +744,37 @@ private static String getDefaultEndpointByServiceInfo(String service, String reg
         String resultEndpoint = ENDPOINT;
         ServiceEndpointInfo endpointInfo = DEFAULT_ENDPOINT_MAP.get(service);
         if (endpointInfo == null || !inBootstrapRegionList(regionCode, customBootstrapRegion)) {
+            SDK_CORE_LOGGER.debugEndpoint("Service '{}' not found in default endpoint map, fallback to default: {}, Or Region '{}' not in bootstrap region list, fallback to default: {}", service, resultEndpoint, regionCode, resultEndpoint);
             return resultEndpoint;
         }
 
+
         String endpointSuffix = hasEnabledDualstack(useDualStack) ? DUALSTACK_ENDPOINT_SUFFIX : ENDPOINT_SUFFIX;
+        SDK_CORE_LOGGER.debugEndpoint("Endpoint suffix is: " + endpointSuffix);
 
         if (endpointInfo.isGlobal) {
             if (!endpointInfo.globalEndpoint.isEmpty()) {
+                SDK_CORE_LOGGER.debugEndpoint("Service '{}' is global, using predefined global endpoint: {}", service, resultEndpoint);
                 resultEndpoint = endpointInfo.globalEndpoint;
                 return resultEndpoint;
             }
 
             resultEndpoint = standardizeDomainServiceCode(service) + endpointSuffix;
+            SDK_CORE_LOGGER.debugEndpoint("Service '{}' is global, constructing endpoint: {}", service, resultEndpoint);
             return resultEndpoint;
         }
 
         if (endpointInfo.regionEndpointMap != null) {
             String regionEndpoint = endpointInfo.regionEndpointMap.get(regionCode);
             if (regionEndpoint != null) {
                 resultEndpoint = regionEndpoint;
+                SDK_CORE_LOGGER.debugEndpoint("Found predefined endpoint for service '{}' in region '{}': {}", service, regionCode, resultEndpoint);
                 return resultEndpoint;
             }
         }
 
         resultEndpoint = standardizeDomainServiceCode(service) + SEPARATOR + regionCode + endpointSuffix;
+        SDK_CORE_LOGGER.debugEndpoint("Constructing endpoint for service '{}' in region '{}': {}", service, regionCode, resultEndpoint);
         return resultEndpoint;
     }
 
@@ -775,6 +783,7 @@ private static boolean inBootstrapRegionList(String region, Set<String> customBo
         String bsRegionListPath = System.getenv("VOLC_BOOTSTRAP_REGION_LIST_CONF");
 
         if (bsRegionListPath != null && !bsRegionListPath.isEmpty()) {
+            SDK_CORE_LOGGER.debugEndpoint("Checking for region in file specified by VOLC_BOOTSTRAP_REGION_LIST_CONF: " + bsRegionListPath);
             try {
                 BufferedReader reader = new BufferedReader(new FileReader(bsRegionListPath));
                 String line;
@@ -785,23 +794,28 @@ private static boolean inBootstrapRegionList(String region, Set<String> customBo
                     }
                     if (line.equals(regionCode)) {
                         reader.close();
+                        SDK_CORE_LOGGER.debugEndpoint("Region '{}' found in {}.", regionCode, bsRegionListPath);
                         return true;
                     }
                 }
                 reader.close();
             } catch (Exception e) {
-                System.err.println("Error when reading " + bsRegionListPath + ": " + e.getMessage());
+                SDK_CORE_LOGGER.error(()->"Error when reading " + bsRegionListPath + ": ", e);
             }
         }
 
         if (BOOTSTRAP_REGION.contains(region)) {
+            SDK_CORE_LOGGER.debugEndpoint("Region '{}' found in default bootstrap list.", region);
             return true;
         }
 
-        if (customBootstrapRegion != null) {
-            return customBootstrapRegion.contains(region);
+        if (customBootstrapRegion != null && customBootstrapRegion.contains(region)) {
+            SDK_CORE_LOGGER.debugEndpoint("Region '{}' found in custom bootstrap list.", region);
+            return true;
         }
 
+        SDK_CORE_LOGGER.debugEndpoint("Region '{}' not found in any bootstrap list.", region);
+
         return false;
     }
 

volcengine-java-sdk-core/src/main/java/com/volcengine/endpoint/EndpointResolver.java

@@ -2,5 +2,6 @@
 
 public interface EndpointResolver {
 
-    public ResolvedEndpoint endpointFor(ResolveEndpointOption option);
+    ResolvedEndpoint endpointFor(ResolveEndpointOption option);
+
 }