Add commonts of toolkits, and their activations.

skywalking-application-toolkit/skywalking-toolkit-log4j-2.x/src/main/java/com/a/eye/skywalking/toolkit/log/log4j/v2/x/Log4j2OutputAppender.java

@@ -4,7 +4,13 @@ package com.a.eye.skywalking.toolkit.log.log4j.v2.x;
  * Created by wusheng on 2016/12/11.
  */
 public class Log4j2OutputAppender {
-    public static void append(StringBuilder toAppendTo){
+    /**
+     * As default, append "TID: N/A" to the output message,
+     * if sky-walking agent in active mode, append the real traceId in the recent Context, if existed, or empty String.
+     *
+     * @param toAppendTo origin output message.
+     */
+    public static void append(StringBuilder toAppendTo) {
         toAppendTo.append("TID: N/A");
     }
 }

skywalking-application-toolkit/skywalking-toolkit-log4j-2.x/src/main/java/com/a/eye/skywalking/toolkit/log/log4j/v2/x/TraceIdConverter.java

@@ -7,6 +7,11 @@ import org.apache.logging.log4j.core.pattern.ConverterKeys;
 import org.apache.logging.log4j.core.pattern.LogEventPatternConverter;
 
 /**
+ * {@link TraceIdConverter} is a log4j2 plugin, by annotation as {@link Plugin}.
+ * It convert the pattern key: traceId.
+ * Use '%traceId' in log4j2's config: <PatternLayout pattern="%d [%traceId] %-5p %c{1}:%L - %m%n"/>,
+ * '%traceId' will output as TID:xxxx
+ *
  * Created by wusheng on 2016/12/7.
  */
 @Plugin(name = "TraceIdConverter", category = "Converter")

skywalking-application-toolkit/skywalking-toolkit-logback-1.x/src/main/java/com/a/eye/skywalking/toolkit/log/logback/v1/x/LogbackPatternConverter.java

@@ -7,6 +7,13 @@ import ch.qos.logback.classic.spi.ILoggingEvent;
  * Created by wusheng on 2016/12/7.
  */
 public class LogbackPatternConverter extends ClassicConverter {
+    /**
+     * As default, return "TID: N/A" to the output message,
+     * if sky-walking agent in active mode, return the real traceId in the recent Context, if existed.
+     *
+     * @param iLoggingEvent
+     * @return the traceId: N/A, empty String, or the real traceId.
+     */
     @Override
     public String convert(ILoggingEvent iLoggingEvent) {
         return "TID: N/A";

skywalking-application-toolkit/skywalking-toolkit-logback-1.x/src/main/java/com/a/eye/skywalking/toolkit/log/logback/v1/x/TraceIdPatternLogbackLayout.java

@@ -3,6 +3,10 @@ package com.a.eye.skywalking.toolkit.log.logback.v1.x;
 import ch.qos.logback.classic.PatternLayout;
 
 /**
+ * Based on the logback-compoenent convert register mechanism,
+ * register {@link LogbackPatternConverter} as a new convert, match to "tid".
+ * You can use "%tid" in logback config file, "Pattern" section.
+ * <p>
  * Created by wusheng on 2016/12/7.
  */
 public class TraceIdPatternLogbackLayout extends PatternLayout {

skywalking-application-toolkit/skywalking-toolkit-trace-context/src/main/java/com/a/eye/skywalking/toolkit/trace/TraceContext.java

 package com.a.eye.skywalking.toolkit.trace;
 
 /**
+ * Try to access the sky-walking tracer context.
+ * The context is not existed, always.
+ * only the middleware, component, or rpc-framework are supported in the current invoke stack, in the same thread,
+ * the context will be available.
+ * <p>
  * Created by xin on 2016/12/15.
  */
 public class TraceContext {
 
+    /**
+     * Try to get the traceId of current trace context.
+     *
+     * @return traceId, if it exists, or empty {@link String}.
+     */
     public static String traceId() {
         return "";
     }

skywalking-sniffer/skywalking-api/src/main/java/com/a/eye/skywalking/api/Tracing.java

@@ -9,9 +9,9 @@ import static com.a.eye.skywalking.util.TraceIdUtil.formatTraceId;
 
 public class Tracing {
     /**
-     * 获取当前上下文中的TraceId
+     * Get the traceId of current trace context.
      *
-     * @return
+     * @return traceId, if it exists, or empty {@link String}.
      */
     public static String getTraceId() {
         Span spanData = CurrentThreadSpanStack.peek();
@@ -21,25 +21,4 @@ public class Tracing {
 
         return formatTraceId(spanData.getTraceId());
     }
-
-    public static String getTracelevelId() {
-        Span spanData = CurrentThreadSpanStack.peek();
-        if (spanData == null) {
-            return "";
-        }
-
-        return (spanData.getParentLevel() == null || spanData.getParentLevel().length() == 0) ?
-                Integer.toString(spanData.getLevelId()) :
-                spanData.getParentLevel() + "." + spanData.getLevelId();
-    }
-
-    public static String generateNextContextData() {
-        Span spanData = CurrentThreadSpanStack.peek();
-        if (spanData == null) {
-            return null;
-        }
-
-        ContextData contextData = new ContextData(spanData);
-        return contextData.toString();
-    }
 }

skywalking-sniffer/skywalking-toolkit-activation/skywalking-toolkit-log4j-1.x-activation/src/main/java/com/a/eye/skywalking/toolkit/activation/log/log4j/v1/x/PrintTraceIdInterceptor.java

@@ -15,6 +15,14 @@ public class PrintTraceIdInterceptor implements InstanceMethodsAroundInterceptor
 
     }
 
+    /**
+     * Override com.a.eye.skywalking.toolkit.log.log4j.v1.x.TraceIdPatternConverter.convert(),
+     *
+     * @param context instance context, a class instance only has one {@link EnhancedClassInstanceContext} instance.
+     * @param interceptorContext method context, includes class name, method name, etc.
+     * @param ret the method's original return value.
+     * @return the traceId
+     */
     @Override
     public Object afterMethod(EnhancedClassInstanceContext context, InstanceMethodInvokeContext interceptorContext, Object ret) {
         return "TID:" + Tracing.getTraceId();

skywalking-sniffer/skywalking-toolkit-activation/skywalking-toolkit-log4j-1.x-activation/src/main/java/com/a/eye/skywalking/toolkit/activation/log/log4j/v1/x/TraceIdPatternConverterActivation.java

@@ -2,6 +2,7 @@ package com.a.eye.skywalking.toolkit.activation.log.log4j.v1.x;
 
 import com.a.eye.skywalking.plugin.interceptor.ConstructorInterceptPoint;
 import com.a.eye.skywalking.plugin.interceptor.InstanceMethodsInterceptPoint;
+import com.a.eye.skywalking.plugin.interceptor.StaticMethodsInterceptPoint;
 import com.a.eye.skywalking.plugin.interceptor.enhance.ClassInstanceMethodsEnhancePluginDefine;
 import net.bytebuddy.description.method.MethodDescription;
 import net.bytebuddy.matcher.ElementMatcher;
@@ -9,19 +10,33 @@ import net.bytebuddy.matcher.ElementMatcher;
 import static net.bytebuddy.matcher.ElementMatchers.named;
 
 /**
+ * Active the toolkit class "com.a.eye.skywalking.toolkit.log.log4j.v1.x.TraceIdPatternConverter".
+ * Should not dependency or import any class in "skywalking-toolkit-log4j-1.x" module.
+ * Activation's classloader is diff from "com.a.eye.skywalking.toolkit.log.log4j.v1.x.TraceIdPatternConverter",
+ * using direct will trigger classloader issue.
+ *
  * Created by wusheng on 2016/12/7.
  */
 public class TraceIdPatternConverterActivation extends ClassInstanceMethodsEnhancePluginDefine {
+    /**
+     * @return the target class, which needs active.
+     */
     @Override
     protected String enhanceClassName() {
         return "com.a.eye.skywalking.toolkit.log.log4j.v1.x.TraceIdPatternConverter";
     }
 
+    /**
+     * @return null, no need to intercept constructor of enhance class.
+     */
     @Override
     protected ConstructorInterceptPoint[] getConstructorsInterceptPoints() {
         return null;
     }
 
+    /**
+     * @return the collection of {@link InstanceMethodsInterceptPoint}, represent the intercepted methods and their interceptors.
+     */
     @Override
     protected InstanceMethodsInterceptPoint[] getInstanceMethodsInterceptPoints() {
         return new InstanceMethodsInterceptPoint[]{new InstanceMethodsInterceptPoint() {

skywalking-sniffer/skywalking-toolkit-activation/skywalking-toolkit-log4j-2.x-activation/src/main/java/com/a/eye/skywalking/toolkit/activation/log/log4j/v2/x/Log4j2OutputAppenderActivation.java

@@ -8,14 +8,25 @@ import net.bytebuddy.matcher.ElementMatcher;
 import static net.bytebuddy.matcher.ElementMatchers.named;
 
 /**
+ * Active the toolkit class "com.a.eye.skywalking.toolkit.log.logback.v2.x.LogbackPatternConverter".
+ * Should not dependency or import any class in "skywalking-toolkit-logback-2.x" module.
+ * Activation's classloader is diff from "com.a.eye.skywalking.toolkit.log.logback.v2.x.LogbackPatternConverter",
+ * using direct will trigger classloader issue.
+ *
  * Created by wusheng on 2016/12/7.
  */
 public class Log4j2OutputAppenderActivation extends ClassStaticMethodsEnhancePluginDefine {
+    /**
+     * @return the target class, which needs active.
+     */
     @Override
     protected String enhanceClassName() {
         return "com.a.eye.skywalking.toolkit.log.log4j.v2.x.Log4j2OutputAppender";
     }
 
+    /**
+     * @return the collection of {@link StaticMethodsInterceptPoint}, represent the intercepted methods and their interceptors.
+     */
     @Override
     protected StaticMethodsInterceptPoint[] getStaticMethodsInterceptPoints() {
         return new StaticMethodsInterceptPoint[]{new StaticMethodsInterceptPoint() {

skywalking-sniffer/skywalking-toolkit-activation/skywalking-toolkit-log4j-2.x-activation/src/main/java/com/a/eye/skywalking/toolkit/activation/log/log4j/v2/x/PrintTraceIdInterceptor.java

@@ -8,9 +8,15 @@ import com.a.eye.skywalking.plugin.interceptor.enhance.*;
  * Created by wusheng on 2016/12/7.
  */
 public class PrintTraceIdInterceptor implements StaticMethodsAroundInterceptor {
+    /**
+     * Override com.a.eye.skywalking.toolkit.log.log4j.v2.x.Log4j2OutputAppender.append(),
+     *
+     * @param interceptorContext method context, includes class name, method name, etc.
+     * @param result             change this result, to output the traceId. The origin append() method will not invoke.
+     */
     @Override
     public void beforeMethod(StaticMethodInvokeContext interceptorContext, MethodInterceptResult result) {
-        ((StringBuilder)interceptorContext.allArguments()[0]).append("TID:" + Tracing.getTraceId());
+        ((StringBuilder) interceptorContext.allArguments()[0]).append("TID:" + Tracing.getTraceId());
 
         //make sure origin method do not invoke.
         result.defineReturnValue(null);

skywalking-sniffer/skywalking-toolkit-activation/skywalking-toolkit-logback-1.x-activation/src/main/java/com/a/eye/skywalking/toolkit/activation/log/logback/v1/x/LogbackPatternConverterActivation.java

@@ -2,6 +2,7 @@ package com.a.eye.skywalking.toolkit.activation.log.logback.v1.x;
 
 import com.a.eye.skywalking.plugin.interceptor.ConstructorInterceptPoint;
 import com.a.eye.skywalking.plugin.interceptor.InstanceMethodsInterceptPoint;
+import com.a.eye.skywalking.plugin.interceptor.StaticMethodsInterceptPoint;
 import com.a.eye.skywalking.plugin.interceptor.enhance.ClassInstanceMethodsEnhancePluginDefine;
 import net.bytebuddy.description.method.MethodDescription;
 import net.bytebuddy.matcher.ElementMatcher;
@@ -9,22 +10,36 @@ import net.bytebuddy.matcher.ElementMatcher;
 import static net.bytebuddy.matcher.ElementMatchers.named;
 
 /**
+ * Active the toolkit class "com.a.eye.skywalking.toolkit.log.logback.v1.x.LogbackPatternConverter".
+ * Should not dependency or import any class in "skywalking-toolkit-logback-1.x" module.
+ * Activation's classloader is diff from "com.a.eye.skywalking.toolkit.log.logback.v1.x.LogbackPatternConverter",
+ * using direct will trigger classloader issue.
+ * <p>
  * Created by wusheng on 2016/12/7.
  */
 public class LogbackPatternConverterActivation extends ClassInstanceMethodsEnhancePluginDefine {
+    /**
+     * @return the target class, which needs active.
+     */
     @Override
     protected String enhanceClassName() {
         return "com.a.eye.skywalking.toolkit.log.logback.v1.x.LogbackPatternConverter";
     }
 
+    /**
+     * @return null, no need to intercept constructor of enhance class.
+     */
     @Override
     protected ConstructorInterceptPoint[] getConstructorsInterceptPoints() {
         return null;
     }
 
+    /**
+     * @return the collection of {@link StaticMethodsInterceptPoint}, represent the intercepted methods and their interceptors.
+     */
     @Override
     protected InstanceMethodsInterceptPoint[] getInstanceMethodsInterceptPoints() {
-        return new InstanceMethodsInterceptPoint[]{new InstanceMethodsInterceptPoint() {
+        return new InstanceMethodsInterceptPoint[] {new InstanceMethodsInterceptPoint() {
             @Override
             public ElementMatcher<MethodDescription> getMethodsMatcher() {
                 return named("convert");

skywalking-sniffer/skywalking-toolkit-activation/skywalking-toolkit-logback-1.x-activation/src/main/java/com/a/eye/skywalking/toolkit/activation/log/logback/v1/x/PrintTraceIdInterceptor.java

@@ -15,6 +15,14 @@ public class PrintTraceIdInterceptor implements InstanceMethodsAroundInterceptor
 
     }
 
+    /**
+     * Override com.a.eye.skywalking.toolkit.log.logback.v1.x.LogbackPatternConverter.convert(),
+     *
+     * @param context instance context, a class instance only has one {@link EnhancedClassInstanceContext} instance.
+     * @param interceptorContext method context, includes class name, method name, etc.
+     * @param ret the method's original return value.
+     * @return the traceId
+     */
     @Override
     public Object afterMethod(EnhancedClassInstanceContext context, InstanceMethodInvokeContext interceptorContext, Object ret) {
         return "TID:" + Tracing.getTraceId();

skywalking-sniffer/skywalking-toolkit-activation/skywalking-toolkit-trace-context-activation/src/main/java/com/a/eye/skywalking/toolkit/activation/trace/TraceContextActivation.java

@@ -8,14 +8,25 @@ import net.bytebuddy.matcher.ElementMatcher;
 import static net.bytebuddy.matcher.ElementMatchers.named;
 
 /**
+ * Active the toolkit class "com.a.eye.skywalking.toolkit.trace.TraceContext".
+ * Should not dependency or import any class in "skywalking-toolkit-trace-context" module.
+ * Activation's classloader is diff from "com.a.eye.skywalking.toolkit.trace.TraceContext",
+ * using direct will trigger classloader issue.
+ * <p>
  * Created by xin on 2016/12/15.
  */
 public class TraceContextActivation extends ClassStaticMethodsEnhancePluginDefine {
+    /**
+     * @return the target class, which needs active.
+     */
     @Override
     protected String enhanceClassName() {
         return "com.a.eye.skywalking.toolkit.trace.TraceContext";
     }
 
+    /**
+     * @return the collection of {@link StaticMethodsInterceptPoint}, represent the intercepted methods and their interceptors.
+     */
     @Override
     protected StaticMethodsInterceptPoint[] getStaticMethodsInterceptPoints() {
         return new StaticMethodsInterceptPoint[] {new StaticMethodsInterceptPoint() {

skywalking-sniffer/skywalking-toolkit-activation/skywalking-toolkit-trace-context-activation/src/main/java/com/a/eye/skywalking/toolkit/activation/trace/TraceContextInterceptor.java

@@ -9,6 +9,8 @@ import com.a.eye.skywalking.plugin.interceptor.enhance.StaticMethodInvokeContext
 import com.a.eye.skywalking.plugin.interceptor.enhance.StaticMethodsAroundInterceptor;
 
 /**
+ *
+ *
  * Created by xin on 2016/12/15.
  */
 public class TraceContextInterceptor implements StaticMethodsAroundInterceptor {