docs: 补充日志 (#11)

build.gradle.kts

@@ -39,11 +39,18 @@ subprojects {
             "api"(project(":ihub-core"))
         }
     }
+
+    // TODO 插件配置doc编码
+    tasks.withType(Javadoc::class.java) {
+        options.encoding = "UTF-8"
+    }
 }
 
 iHubGitHooks {
-    hooks.set(mapOf(
-        "pre-commit" to "./gradlew build",
-        "commit-msg" to "./gradlew commitCheck"
-    ))
+    hooks.set(
+        mapOf(
+            "pre-commit" to "./gradlew build",
+            "commit-msg" to "./gradlew commitCheck"
+        )
+    )
 }

gradle.properties

@@ -29,6 +29,3 @@ iHub.releaseRepoUrl=https://s01.oss.sonatype.org/service/local/staging/deploy/ma
 iHub.mavenPrivateEnabled=false
 iHubJava.defaultDependencies=false
 #iHubJavaagent.javaagent=pub.ihub.integration:ihub-agent:main-SNAPSHOT
-
-#TODO
-iHubSettings.skippedDirs=ihub-demo,ihub-agent-plugin

ihub-agent-core/src/main/java/pub/ihub/integration/agent/core/IAspectEnhancer.java

@@ -28,36 +28,36 @@ public interface IAspectEnhancer {
 	/**
 	 * 在目标方法执行前调用
 	 *
-	 * @param objInst
-	 * @param method
-	 * @param allArguments
-	 * @param argumentsTypes
+	 * @param objInst        目标对象实例
+	 * @param method         目标方法
+	 * @param allArguments   方法参数
+	 * @param argumentsTypes 方法参数类型
 	 * @param result         如果要截断方法，请更改此结果。
-	 * @throws Throwable
+	 * @throws Throwable 如果发生异常，则会中断方法调用。
 	 */
 	void beforeMethod(Object objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes, Object result) throws Throwable;
 
 	/**
 	 * 在目标方法执行后调用
 	 *
-	 * @param objInst
-	 * @param method
-	 * @param allArguments
-	 * @param argumentsTypes
+	 * @param objInst        目标对象实例
+	 * @param method         目标方法
+	 * @param allArguments   方法参数
+	 * @param argumentsTypes 方法参数类型
 	 * @param ret            方法的原始返回值。如果方法触发异常，则可能为 null。
 	 * @return 该方法的实际返回值。
-	 * @throws Throwable
+	 * @throws Throwable 如果发生异常，则会中断方法调用。
 	 */
 	Object afterMethod(Object objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes, Object ret) throws Throwable;
 
 
 	/**
 	 * 在目标方法有异常时调用
 	 *
-	 * @param objInst
-	 * @param method
-	 * @param allArguments
-	 * @param argumentsTypes
+	 * @param objInst        目标对象实例
+	 * @param method         目标方法
+	 * @param allArguments   方法参数
+	 * @param argumentsTypes 方法参数类型
 	 * @param t              异常
 	 */
 	void handleMethodException(Object objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes, Throwable t);

ihub-agent-core/src/main/java/pub/ihub/integration/agent/core/IHubAgentBuilder.java

@@ -27,6 +27,11 @@
  */
 public final class IHubAgentBuilder {
 
+	/**
+	 * 构建代理
+	 *
+	 * @return 代理构建器
+	 */
 	public static AgentBuilder build() {
 		final ByteBuddy byteBuddy = new ByteBuddy().with(TypeValidation.of(false));
 		return new AgentBuilder.Default(byteBuddy);

ihub-agent-core/src/main/java/pub/ihub/integration/agent/core/IHubEnhancerProxy.java

@@ -29,8 +29,16 @@
  */
 public class IHubEnhancerProxy {
 
+	/**
+	 * 切面增强类
+	 */
 	public IAspectEnhancer enhancer;
 
+	/**
+	 * 设置切面增强类
+	 *
+	 * @param enhancer 切面增强类
+	 */
 	@IgnoreForBinding
 	public void setEnhancer(IAspectEnhancer enhancer) {
 		this.enhancer = enhancer;

ihub-agent-core/src/main/java/pub/ihub/integration/agent/core/annotation/AspectDefinition.java

@@ -28,6 +28,9 @@
 @Retention(RetentionPolicy.SOURCE)
 public @interface AspectDefinition {
 
+	/**
+	 * 默认方法名
+	 */
 	String ENHANCE_METHOD = "invoke";
 
 	/**

ihub-agent-core/src/main/java/pub/ihub/integration/agent/core/loader/AgentPluginClassLoader.java

@@ -35,13 +35,27 @@
  */
 public class AgentPluginClassLoader extends ClassLoader {
 
+	/**
+	 * 默认加载器
+	 */
 	private static AgentPluginClassLoader DEFAULT_LOADER;
-	// TODO: This path should be configurable
-	private static final String pluginFilePath = "/tmp/ihub-agent-plugin.jar";
+	/**
+	 * TODO: This path should be configurable
+	 */
+	private static final String PLUGIN_FILE_PATH = "/tmp/ihub-agent-plugin.jar";
 
+	/**
+	 * 类路径
+	 */
 	private final List<File> classpath;
+	/**
+	 * 所有的 jar
+	 */
 	private final List<Jar> allJars = new LinkedList<>();
 
+	/**
+	 * 初始化默认加载器
+	 */
 	public static void initDefaultLoader() {
 		if (DEFAULT_LOADER == null) {
 			synchronized (AgentPluginClassLoader.class) {
@@ -52,17 +66,29 @@ public static void initDefaultLoader() {
 		}
 	}
 
+	/**
+	 * 构造器
+	 *
+	 * @param parent 父加载器
+	 */
 	public AgentPluginClassLoader(ClassLoader parent) {
 		super(parent);
 		classpath = new LinkedList<>();
-		classpath.add(new File(pluginFilePath));
+		classpath.add(new File(PLUGIN_FILE_PATH));
 	}
 
+	/**
+	 * 查找类
+	 *
+	 * @param name The <a href="#binary-name">binary name</a> of the class
+	 * @return The resulting Class object
+	 * @throws ClassNotFoundException If the class could not be found
+	 */
 	@Override
 	protected Class<?> findClass(String name) throws ClassNotFoundException {
 		if (allJars.isEmpty()) {
 			try {
-				File file = new File(pluginFilePath);
+				File file = new File(PLUGIN_FILE_PATH);
 				Jar jar = new Jar(new JarFile(file), file);
 				allJars.add(jar);
 			} catch (IOException e) {
@@ -96,6 +122,9 @@ protected Class<?> findClass(String name) throws ClassNotFoundException {
 		throw new ClassNotFoundException("Can't find " + name);
 	}
 
+	/**
+	 * 代表一个 jar
+	 */
 	private record Jar(JarFile jarFile, File sourceFile) {
 	}
 

ihub-agent-core/src/main/java/pub/ihub/integration/agent/core/loader/EnhancerInstanceLoader.java

@@ -30,10 +30,27 @@
  */
 public class EnhancerInstanceLoader {
 
+	/**
+	 * 实例缓存
+	 */
 	private static final ConcurrentHashMap<String, Object> INSTANCE_CACHE = new ConcurrentHashMap<>();
+	/**
+	 * 实例加载锁
+	 */
 	private static final ReentrantLock INSTANCE_LOAD_LOCK = new ReentrantLock();
+	/**
+	 * 扩展插件类加载器
+	 */
 	private static final Map<ClassLoader, ClassLoader> EXTEND_PLUGIN_CLASSLOADERS = new HashMap<>();
 
+	/**
+	 * 加载实例
+	 *
+	 * @param className         类名
+	 * @param targetClassLoader 目标类加载器
+	 * @param <T>               实例类型
+	 * @return 实例
+	 */
 	@SneakyThrows
 	public static <T> T load(String className, ClassLoader targetClassLoader) {
 		if (targetClassLoader == null) {

ihub-agent-trace-plugin/src/main/java/pub/ihub/integration/agent/trace/IHubTraceAgent.java

@@ -38,9 +38,21 @@
  */
 public class IHubTraceAgent {
 
+	/**
+	 * v1
+	 */
 	private static final String TRANSFORMER_V_1 = "v1";
+	/**
+	 * v2
+	 */
 	private static final String TRANSFORMER_V_2 = "v2";
 
+	/**
+	 * The premain method to load the ihub agent
+	 *
+	 * @param agentArgs the agent arguments
+	 * @param inst      the instrumentation instance
+	 */
 	public static void premain(String agentArgs, Instrumentation inst) {
 		Logger.info("The ihub agent start to load...");
 

ihub-agent-trace-plugin/src/main/java/pub/ihub/integration/agent/trace/context/IHubTraceContext.java

@@ -37,9 +37,20 @@
  */
 public class IHubTraceContext {
 
+	/**
+	 * 跟踪器实例
+	 */
 	private static Tracer TracerInst;
+	/**
+	 * 跟踪实例
+	 */
 	private static OpenTelemetry TelemetryInst;
 
+	/**
+	 * 初始化跟踪上下文
+	 *
+	 * @param spanExporters 导出器列表
+	 */
 	public static void initTraceContext(List<SpanExporter> spanExporters) {
 		Logger.info("The IHub core context is initializing...");
 
@@ -58,6 +69,11 @@ public static void initTraceContext(List<SpanExporter> spanExporters) {
 		Logger.info("The IHub core context has been initialized");
 	}
 
+	/**
+	 * 获取跟踪器
+	 *
+	 * @return 跟踪器
+	 */
 	public static Tracer tracer() {
 		if (TracerInst == null) {
 			synchronized (IHubTraceContext.class) {
@@ -68,6 +84,11 @@ public static Tracer tracer() {
 		return TracerInst;
 	}
 
+	/**
+	 * 获取文本传播器
+	 *
+	 * @return 文本传播器
+	 */
 	public static TextMapPropagator textPropagator() {
 		return TelemetryInst.getPropagators().getTextMapPropagator();
 	}

ihub-bytebuddy-core/src/main/java/pub/ihub/integration/bytebuddy/core/IHubPlugin.java

@@ -29,6 +29,9 @@
  */
 public interface IHubPlugin extends Plugin {
 
+	/**
+	 * Cglib 代理类分隔符
+	 */
 	String CGLIB_CLASS_SEPARATOR = "$$";
 
 	/**

ihub-bytebuddy-core/src/main/java/pub/ihub/integration/bytebuddy/core/IHubPluginUtils.java

@@ -16,6 +16,7 @@
 package pub.ihub.integration.bytebuddy.core;
 
 import lombok.SneakyThrows;
+import net.bytebuddy.build.Plugin;
 import net.bytebuddy.description.annotation.AnnotationDescription;
 import net.bytebuddy.description.annotation.AnnotationList;
 import net.bytebuddy.description.field.FieldDescription;
@@ -48,7 +49,9 @@
 public final class IHubPluginUtils {
 
 	static {
-		Logger.ENABLE_DEBUG = Boolean.valueOf(getEnableDebug());
+		if (Boolean.parseBoolean(getEnableDebug())) {
+			Logger.setLevel(Logger.Level.DEBUG);
+		}
 	}
 
 	/**
@@ -114,10 +117,8 @@ public static DynamicType.Builder<?> mapAnnotationOrInterfaces(DynamicType.Build
 	/**
 	 * Applies the given map of source type or annotation to annotation onto the given {@link DynamicType.Builder}.
 	 *
-	 * @param builder  the current {@link DynamicType.Builder}.
-	 * @param type     the currently described type.
-	 * @param mappings the annotation or type mappings.
-	 * @param log      the log to write to.
+	 * @param source     the source type or annotation to match.
+	 * @param annotation the annotation to apply.
 	 * @return type builder
 	 */
 	public static ElementMatcher<FieldDescription> defaultMapping(ElementMatcher.Junction<FieldDescription> source,
@@ -138,10 +139,8 @@ public static ElementMatcher<FieldDescription> defaultMapping(ElementMatcher.Jun
 	/**
 	 * Applies the given map of source type or annotation to annotation onto the given {@link DynamicType.Builder}.
 	 *
-	 * @param builder  the current {@link DynamicType.Builder}.
-	 * @param type     the currently described type.
-	 * @param mappings the annotation or type mappings.
-	 * @param log      the log to write to.
+	 * @param source     the source type or annotation to match.
+	 * @param annotation the annotation to apply.
 	 * @return type builder
 	 */
 	public static ElementMatcher<MethodDescription> defaultMethodMapping(ElementMatcher.Junction<MethodDescription> source,
@@ -221,14 +220,14 @@ public static String abbreviate(AnnotationDescription annotation) {
 	 * @param type the currently described type.
 	 * @return type builder
 	 */
-	public static String abbreviate(String fullyQualifiedTypeName) {
+	public static String abbreviate(String type) {
 
-		String abbreviatedPackage = Arrays.stream(getPackageName(fullyQualifiedTypeName)
+		String abbreviatedPackage = Arrays.stream(getPackageName(type)
 				.split("\\."))
 			.map(it -> it.substring(0, 1))
 			.collect(Collectors.joining("."));
 
-		return abbreviatedPackage.concat(getShortName(fullyQualifiedTypeName));
+		return abbreviatedPackage.concat(getShortName(type));
 	}
 
 	/**