[Feature] Add tag annotation to allow tagging span with annotation (#4152)

* [Feature] Add tag annotation to allow tagging span with annotation

* Use repeatable annotation syntax and add docs and example codes

* Fix failed unit test

apm-application-toolkit/apm-toolkit-trace/src/main/java/org/apache/skywalking/apm/toolkit/trace/Tag.java

@@ -0,0 +1,47 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.apache.skywalking.apm.toolkit.trace;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Tag the current active span with key {@link #key()} and value {@link #value()},
+ * if there is no active span, this annotation takes no effect.
+ *
+ * @author kezhenxu94
+ * @see Tags
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Tag {
+    /**
+     * @return the key of the tag to be injected into the current active span
+     */
+    String key();
+
+    /**
+     * @return the value of the tag to be injected into the current active span,
+     * in the form of the customized enhancement rules, for more information,
+     * refer to https://github.com/apache/skywalking/blob/master/docs/en/setup/service-agent/java-agent/Customize-enhance-trace.md#how-to-configure
+     */
+    String value();
+}

apm-application-toolkit/apm-toolkit-trace/src/main/java/org/apache/skywalking/apm/toolkit/trace/Tags.java

@@ -0,0 +1,48 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.apache.skywalking.apm.toolkit.trace;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * A wrapper annotation for {@link Tag} that allows to
+ * apply multiple tags to a single method span,
+ *
+ * <pre>
+ * &#64;Tag(key = "tag1", value = "arg[0]")
+ * &#64;Tag(key = "tag2", value = "arg[1]")
+ * public void test(String param1, String param2) {
+ *     // ...
+ * }
+ * </pre>
+ *
+ * @author kezhenxu94
+ * @see Tag
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Tags {
+    /**
+     * @see Tag
+     */
+    Tag[] value();
+}

apm-sniffer/apm-agent-core/src/main/java/org/apache/skywalking/apm/agent/core/plugin/match/MethodAnnotationMatch.java

@@ -27,12 +27,12 @@ import net.bytebuddy.description.annotation.AnnotationList;
 import net.bytebuddy.description.method.MethodDescription;
 import net.bytebuddy.description.type.TypeDescription;
 import net.bytebuddy.matcher.ElementMatcher;
+import net.bytebuddy.matcher.ElementMatchers;
 
 import static net.bytebuddy.matcher.ElementMatchers.declaresMethod;
 import static net.bytebuddy.matcher.ElementMatchers.isAnnotatedWith;
 import static net.bytebuddy.matcher.ElementMatchers.isInterface;
 import static net.bytebuddy.matcher.ElementMatchers.named;
-import static net.bytebuddy.matcher.ElementMatchers.not;
 
 /**
  * Match the class, which has methods with the certain annotations.
@@ -60,7 +60,7 @@ public class MethodAnnotationMatch implements IndirectMatch {
                 junction = junction.and(buildEachAnnotation(annotation));
             }
         }
-        junction = declaresMethod(junction).and(not(isInterface()));
+        junction = declaresMethod(junction).and(ElementMatchers.not(isInterface()));
         return junction;
     }
 
@@ -85,7 +85,7 @@ public class MethodAnnotationMatch implements IndirectMatch {
         return isAnnotatedWith(named(annotationName));
     }
 
-    public static ClassMatch byMethodAnnotationMatch(String[] annotations) {
+    public static IndirectMatch byMethodAnnotationMatch(String... annotations) {
         return new MethodAnnotationMatch(annotations);
     }
 }

apm-sniffer/apm-agent-core/src/main/java/org/apache/skywalking/apm/agent/core/plugin/match/logical/LogicalMatchOperation.java

@@ -18,6 +18,9 @@
 
 package org.apache.skywalking.apm.agent.core.plugin.match.logical;
 
+import net.bytebuddy.description.type.TypeDescription;
+import net.bytebuddy.matcher.ElementMatcher;
+import net.bytebuddy.matcher.NegatingMatcher;
 import org.apache.skywalking.apm.agent.core.plugin.match.IndirectMatch;
 
 /**
@@ -33,4 +36,18 @@ public class LogicalMatchOperation {
     public static IndirectMatch or(final IndirectMatch... matches) {
         return new LogicalOrMatch(matches);
     }
+
+    public static IndirectMatch not(final IndirectMatch match) {
+        return new IndirectMatch() {
+            @Override
+            public ElementMatcher.Junction buildJunction() {
+                return new NegatingMatcher(match.buildJunction());
+            }
+
+            @Override
+            public boolean isMatch(final TypeDescription typeDescription) {
+                return !match.isMatch(typeDescription);
+            }
+        };
+    }
 }

apm-sniffer/apm-agent-core/src/main/java/org/apache/skywalking/apm/agent/core/util/CustomizeExpression.java

@@ -16,7 +16,7 @@
  *
  */
 
-package org.apache.skywalking.apm.plugin.customize.util;
+package org.apache.skywalking.apm.agent.core.util;
 
 import org.apache.skywalking.apm.agent.core.logging.api.ILog;
 import org.apache.skywalking.apm.agent.core.logging.api.LogManager;
@@ -39,7 +39,10 @@ public class CustomizeExpression {
     private static final ILog logger = LogManager.getLogger(CustomizeExpression.class);
 
     public static Map<String, Object> evaluationContext(Object[] allArguments) {
-        Map<String, Object> context = new HashMap<String, Object>();
+        Map<String, Object> context = new HashMap<>();
+        if (allArguments == null) {
+            return context;
+        }
         for (int i = 0; i < allArguments.length; i++) {
             context.put("arg[" + i + "]", allArguments[i]);
         }
@@ -86,21 +89,22 @@ public class CustomizeExpression {
     }
 
     private static Object matcherList(String expression, Object o) {
-        int index = Integer.valueOf(expression.replace("[", "").replace("]", ""));
+        int index = Integer.parseInt(expression.replace("[", "").replace("]", ""));
         List l = (List) o;
         return l != null && l.size() > index ? l.get(index) : null;
     }
 
     private static Object matcherArray(String expression, Object o) {
-        int index = Integer.valueOf(expression.replace("[", "").replace("]", ""));
+        int index = Integer.parseInt(expression.replace("[", "").replace("]", ""));
         return o != null && Array.getLength(o) > index ? Array.get(o, index) : null;
     }
 
     private static Object matcherDefault(String expression, Object o) {
         try {
             if (expression.contains("()")) {
-                Method m = o.getClass().getMethod(expression.replace("()", ""), null);
-                return m.invoke(o, null);
+                Method m = o.getClass().getMethod(expression.replace("()", ""));
+                m.setAccessible(true);
+                return m.invoke(o);
             } else {
                 Field f = o.getClass().getDeclaredField(expression);
                 f.setAccessible(true);

apm-sniffer/apm-toolkit-activation/apm-toolkit-trace-activation/src/main/java/org/apache/skywalking/apm/toolkit/activation/trace/TagAnnotationActivation.java

@@ -0,0 +1,87 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+
+package org.apache.skywalking.apm.toolkit.activation.trace;
+
+import net.bytebuddy.description.method.MethodDescription;
+import net.bytebuddy.matcher.ElementMatcher;
+import org.apache.skywalking.apm.agent.core.plugin.interceptor.ConstructorInterceptPoint;
+import org.apache.skywalking.apm.agent.core.plugin.interceptor.DeclaredInstanceMethodsInterceptPoint;
+import org.apache.skywalking.apm.agent.core.plugin.interceptor.InstanceMethodsInterceptPoint;
+import org.apache.skywalking.apm.agent.core.plugin.interceptor.enhance.ClassInstanceMethodsEnhancePluginDefine;
+import org.apache.skywalking.apm.agent.core.plugin.match.ClassMatch;
+
+import static net.bytebuddy.matcher.ElementMatchers.isAnnotatedWith;
+import static net.bytebuddy.matcher.ElementMatchers.named;
+import static org.apache.skywalking.apm.agent.core.plugin.match.MethodAnnotationMatch.byMethodAnnotationMatch;
+import static org.apache.skywalking.apm.agent.core.plugin.match.logical.LogicalMatchOperation.and;
+import static org.apache.skywalking.apm.agent.core.plugin.match.logical.LogicalMatchOperation.not;
+import static org.apache.skywalking.apm.agent.core.plugin.match.logical.LogicalMatchOperation.or;
+
+/**
+ * Intercepts all methods annotated with {@link org.apache.skywalking.apm.toolkit.trace.Tag}
+ *
+ * @author kezhenxu94
+ */
+public class TagAnnotationActivation extends ClassInstanceMethodsEnhancePluginDefine {
+
+    public static final String TAG_ANNOTATION_METHOD_INTERCEPTOR = "org.apache.skywalking.apm.toolkit.activation.trace.TagAnnotationMethodInterceptor";
+    public static final String TAG_ANNOTATION = "org.apache.skywalking.apm.toolkit.trace.Tag";
+    public static final String TAGS_ANNOTATION = "org.apache.skywalking.apm.toolkit.trace.Tags";
+    public static final String TRACE_ANNOTATION = "org.apache.skywalking.apm.toolkit.trace.Trace";
+
+    @Override
+    public ConstructorInterceptPoint[] getConstructorsInterceptPoints() {
+        return new ConstructorInterceptPoint[0];
+    }
+
+    @Override
+    public InstanceMethodsInterceptPoint[] getInstanceMethodsInterceptPoints() {
+        return new InstanceMethodsInterceptPoint[]{
+            new DeclaredInstanceMethodsInterceptPoint() {
+                @Override
+                public ElementMatcher<MethodDescription> getMethodsMatcher() {
+                    return isAnnotatedWith(named(TAG_ANNOTATION));
+                }
+
+                @Override
+                public String getMethodsInterceptor() {
+                    return TAG_ANNOTATION_METHOD_INTERCEPTOR;
+                }
+
+                @Override
+                public boolean isOverrideArgs() {
+                    return false;
+                }
+            }
+        };
+    }
+
+    @Override
+    protected ClassMatch enhanceClass() {
+        return and(
+            not(byMethodAnnotationMatch(TRACE_ANNOTATION)),
+
+            or(
+                byMethodAnnotationMatch(TAGS_ANNOTATION),
+                byMethodAnnotationMatch(TAG_ANNOTATION)
+            )
+        );
+    }
+}

apm-sniffer/apm-toolkit-activation/apm-toolkit-trace-activation/src/main/java/org/apache/skywalking/apm/toolkit/activation/trace/TagAnnotationMethodInterceptor.java

@@ -0,0 +1,92 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+
+package org.apache.skywalking.apm.toolkit.activation.trace;
+
+import java.lang.reflect.Method;
+import java.util.Map;
+
+import org.apache.skywalking.apm.agent.core.context.ContextManager;
+import org.apache.skywalking.apm.agent.core.context.tag.StringTag;
+import org.apache.skywalking.apm.agent.core.context.trace.AbstractSpan;
+import org.apache.skywalking.apm.agent.core.plugin.interceptor.enhance.EnhancedInstance;
+import org.apache.skywalking.apm.agent.core.plugin.interceptor.enhance.InstanceMethodsAroundInterceptor;
+import org.apache.skywalking.apm.agent.core.plugin.interceptor.enhance.MethodInterceptResult;
+import org.apache.skywalking.apm.agent.core.util.CustomizeExpression;
+import org.apache.skywalking.apm.toolkit.trace.Tag;
+import org.apache.skywalking.apm.toolkit.trace.Tags;
+
+/**
+ * @author kezhenxu94
+ */
+public class TagAnnotationMethodInterceptor implements InstanceMethodsAroundInterceptor {
+    @Override
+    public void beforeMethod(
+        final EnhancedInstance objInst,
+        final Method method,
+        final Object[] allArguments,
+        final Class<?>[] argumentsTypes,
+        final MethodInterceptResult result) {
+
+        if (!ContextManager.isActive()) {
+            return;
+        }
+
+        final AbstractSpan activeSpan = ContextManager.activeSpan();
+        final Map<String, Object> context = CustomizeExpression.evaluationContext(allArguments);
+
+        final Tags tags = method.getAnnotation(Tags.class);
+        if (tags != null && tags.value().length > 0) {
+            for (final Tag tag : tags.value()) {
+                tagSpan(activeSpan, tag, context);
+            }
+        }
+
+        final Tag tag = method.getAnnotation(Tag.class);
+        if (tag != null) {
+            tagSpan(activeSpan, tag, context);
+        }
+    }
+
+    private void tagSpan(final AbstractSpan span, final Tag tag, final Map<String, Object> context) {
+        new StringTag(tag.key()).set(span, CustomizeExpression.parseExpression(tag.value(), context));
+    }
+
+    @Override
+    public Object afterMethod(
+        final EnhancedInstance objInst,
+        final Method method,
+        final Object[] allArguments,
+        final Class<?>[] argumentsTypes,
+        final Object ret) {
+        return ret;
+    }
+
+    @Override
+    public void handleMethodException(
+        final EnhancedInstance objInst,
+        final Method method,
+        final Object[] allArguments,
+        final Class<?>[] argumentsTypes,
+        final Throwable t) {
+        if (ContextManager.isActive()) {
+            ContextManager.activeSpan().errorOccurred().log(t);
+        }
+    }
+}

apm-sniffer/apm-toolkit-activation/apm-toolkit-trace-activation/src/main/java/org/apache/skywalking/apm/toolkit/activation/trace/TraceAnnotationActivation.java

@@ -65,6 +65,6 @@ public class TraceAnnotationActivation extends ClassInstanceMethodsEnhancePlugin
     }
 
     @Override protected ClassMatch enhanceClass() {
-        return MethodAnnotationMatch.byMethodAnnotationMatch(new String[] {TRACE_ANNOTATION});
+        return MethodAnnotationMatch.byMethodAnnotationMatch(TRACE_ANNOTATION);
     }
 }

apm-sniffer/apm-toolkit-activation/apm-toolkit-trace-activation/src/main/java/org/apache/skywalking/apm/toolkit/activation/trace/TraceAnnotationMethodInterceptor.java

@@ -20,7 +20,14 @@
 package org.apache.skywalking.apm.toolkit.activation.trace;
 
 import java.lang.reflect.Method;
+import java.util.Map;
+
 import org.apache.skywalking.apm.agent.core.conf.Config;
+import org.apache.skywalking.apm.agent.core.context.tag.StringTag;
+import org.apache.skywalking.apm.agent.core.context.trace.AbstractSpan;
+import org.apache.skywalking.apm.agent.core.util.CustomizeExpression;
+import org.apache.skywalking.apm.toolkit.trace.Tag;
+import org.apache.skywalking.apm.toolkit.trace.Tags;
 import org.apache.skywalking.apm.toolkit.trace.Trace;
 import org.apache.skywalking.apm.agent.core.context.ContextManager;
 import org.apache.skywalking.apm.agent.core.plugin.interceptor.enhance.EnhancedInstance;
@@ -45,7 +52,25 @@ public class TraceAnnotationMethodInterceptor implements InstanceMethodsAroundIn
             operationName = MethodUtil.generateOperationName(method);
         }
 
-        ContextManager.createLocalSpan(operationName);
+        final AbstractSpan localSpan = ContextManager.createLocalSpan(operationName);
+
+        final Map<String, Object> context = CustomizeExpression.evaluationContext(allArguments);
+
+        final Tags tags = method.getAnnotation(Tags.class);
+        if (tags != null && tags.value().length > 0) {
+            for (final Tag tag : tags.value()) {
+                tagSpan(localSpan, tag, context);
+            }
+        }
+
+        final Tag tag = method.getAnnotation(Tag.class);
+        if (tag != null) {
+            tagSpan(localSpan, tag, context);
+        }
+    }
+
+    private void tagSpan(final AbstractSpan span, final Tag tag, final Map<String, Object> context) {
+        new StringTag(tag.key()).set(span, CustomizeExpression.parseExpression(tag.value(), context));
     }
 
     @Override

apm-sniffer/apm-toolkit-activation/apm-toolkit-trace-activation/src/main/resources/skywalking-plugin.def

@@ -18,3 +18,4 @@ toolkit-trace=org.apache.skywalking.apm.toolkit.activation.trace.ActiveSpanActiv
 toolkit-trace=org.apache.skywalking.apm.toolkit.activation.trace.TraceAnnotationActivation
 toolkit-trace=org.apache.skywalking.apm.toolkit.activation.trace.TraceContextActivation
 toolkit-trace=org.apache.skywalking.apm.toolkit.activation.trace.CallableOrRunnableActivation
+toolkit-tag=org.apache.skywalking.apm.toolkit.activation.trace.TagAnnotationActivation

apm-sniffer/optional-plugins/customize-enhance-plugin/src/main/java/org/apache/skywalking/apm/plugin/customize/interceptor/BaseInterceptorMethods.java

@@ -23,7 +23,7 @@ import org.apache.skywalking.apm.agent.core.context.trace.AbstractSpan;
 import org.apache.skywalking.apm.plugin.customize.conf.CustomizeConfiguration;
 import org.apache.skywalking.apm.plugin.customize.conf.MethodConfiguration;
 import org.apache.skywalking.apm.plugin.customize.constants.Constants;
-import org.apache.skywalking.apm.plugin.customize.util.CustomizeExpression;
+import org.apache.skywalking.apm.agent.core.util.CustomizeExpression;
 
 import java.lang.reflect.Method;
 import java.util.HashMap;

apm-sniffer/optional-plugins/customize-enhance-plugin/src/test/java/org/apache/skywalking/apm/plugin/customize/util/CustomizeExpressionTest.java

@@ -18,6 +18,7 @@
 
 package org.apache.skywalking.apm.plugin.customize.util;
 
+import org.apache.skywalking.apm.agent.core.util.CustomizeExpression;
 import org.junit.Assert;
 import org.junit.Test;
 

docs/en/setup/service-agent/java-agent/Application-toolkit-trace.md

@@ -17,7 +17,10 @@ modelAndView.addObject("traceId", TraceContext.traceId());
 _Sample codes only_
 
 * Add `@Trace` to any method you want to trace. After that, you can see the span in the Stack.
-* Add custom tag in  the context of traced method .
+* Methods annotated with `@Tag` will try to tag the **current active span** with the given key (`Tag#key()`) and (`Tag#value()`),
+if there is no active span at all, this annotation takes no effect. `@Tag` can be repeated, and can be used in companion with `@Trace`, see examples below.
+The `value` of `Tag` is the same as what are supported in [Customize Enhance Trace](Customize-enhance-trace.md).
+* Add custom tag in the context of traced method, `ActiveSpan.tag("key", "val")`.
 
 * `ActiveSpan.error()` Mark the current span as error status.
 * `ActiveSpan.error(String errorMsg)` Mark the current span as error status with a message.
@@ -33,5 +36,16 @@ ActiveSpan.error("Test-Error-Reason");
 ActiveSpan.error(new RuntimeException("Test-Error-Throwable"));
 ActiveSpan.info("Test-Info-Msg");
 ActiveSpan.debug("Test-debug-Msg");
+
+/**
+ * The codes below will generate a span,
+ * and two tags, keys are `tag1` and `tag2`, values are the passed-in parameters, respectively
+ */
+@Trace
+@Tag(key = "tag1", value = "arg[0]")
+@Tag(key = "tag2", value = "arg[1]")
+public void methodYouWantToTrace(String param1, String param2) {
+    // ...
+}
 ```
 

test/plugin/scenarios/apm-toolkit-trace-scenario/config/expectedData.yaml

@@ -44,7 +44,7 @@ segmentItems:
             peerId: 0
             tags:
               - {key: key, value: value}
-          - operationName: test.org.apache.skywalking.apm.testcase.toolkit.controller.TestService.testInfo()
+          - operationName: test.org.apache.skywalking.apm.testcase.toolkit.controller.TestService.testInfo(java.lang.String)
             operationId: 0
             parentSpanId: 0
             spanId: 2
@@ -61,6 +61,8 @@ segmentItems:
               - logEvent:
                   - {key: event, value: info}
                   - {key: message, value: TestInfoMsg}
+            tags:
+              - {key: testTag, value: testInfoParam}
           - operationName: test.org.apache.skywalking.apm.testcase.toolkit.controller.TestService.testDebug()
             operationId: 0
             parentSpanId: 0
@@ -127,6 +129,22 @@ segmentItems:
                   - {key: error.kind, value: java.lang.RuntimeException}
                   - {key: message, value: Test-Exception}
                   - {key: stack, value: not null}
+          - operationName: test.org.apache.skywalking.apm.testcase.toolkit.controller.TestService.testTagAnnotation(java.lang.String,java.lang.String)
+            operationId: 0
+            parentSpanId: 0
+            spanId: 7
+            spanLayer: Unknown
+            startTime: nq 0
+            endTime: nq 0
+            componentId: 0
+            componentName: ''
+            isError: false
+            spanType: Local
+            peer: ''
+            peerId: 0
+            tags:
+              - {key: p1, value: testTagAnnotationParam1}
+              - {key: p2, value: testTagAnnotationParam2}
           - operationName: /case/tool-kit
             operationId: 0
             parentSpanId: -1

test/plugin/scenarios/apm-toolkit-trace-scenario/src/main/java/org/apache/skywalking/apm/toolkit/trace/Tag.java

@@ -0,0 +1,49 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.apache.skywalking.apm.toolkit.trace;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Tag the current active span with key {@link #key()} and value {@link #value()},
+ * if there is no active span, this annotation takes no effect.
+ *
+ * @author kezhenxu94
+ * @see Tags
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@Repeatable(Tags.class)
+public @interface Tag {
+    /**
+     * @return the key of the tag to be injected into the current active span
+     */
+    String key();
+
+    /**
+     * @return the value of the tag to be injected into the current active span,
+     * in the form of the customized enhancement rules, for more information,
+     * refer to https://github.com/apache/skywalking/blob/master/docs/en/setup/service-agent/java-agent/Customize-enhance-trace.md#how-to-configure
+     */
+    String value();
+}

test/plugin/scenarios/apm-toolkit-trace-scenario/src/main/java/org/apache/skywalking/apm/toolkit/trace/Tags.java

@@ -0,0 +1,48 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.apache.skywalking.apm.toolkit.trace;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * A wrapper annotation for {@link Tag} that allows to
+ * apply multiple tags to a single method span,
+ *
+ * <pre>
+ * &#64;Tag(key = "tag1", value = "arg[0]")
+ * &#64;Tag(key = "tag2", value = "arg[1]")
+ * public void test(String param1, String param2) {
+ *     // ...
+ * }
+ * </pre>
+ *
+ * @author kezhenxu94
+ * @see Tag
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Tags {
+    /**
+     * @see Tag
+     */
+    Tag[] value();
+}

test/plugin/scenarios/apm-toolkit-trace-scenario/src/main/java/test/org/apache/skywalking/apm/testcase/toolkit/controller/TestController.java

@@ -18,6 +18,8 @@
 
 package test.org.apache.skywalking.apm.testcase.toolkit.controller;
 
+import java.io.IOException;
+
 import org.apache.http.HttpEntity;
 import org.apache.http.client.ResponseHandler;
 import org.apache.http.client.methods.HttpGet;
@@ -28,9 +30,6 @@ import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
-import javax.annotation.Resource;
-import java.io.IOException;
-
 /**
  * @author caoyixiong
  */
@@ -46,11 +45,12 @@ public class TestController {
     @RequestMapping("/tool-kit")
     public String toolKitCase() {
         testService.testTag();
-        testService.testInfo();
+        testService.testInfo("testInfoParam");
         testService.testDebug();
         testService.testError();
         testService.testErrorMsg();
         testService.testErrorThrowable();
+        testService.testTagAnnotation("testTagAnnotationParam1", "testTagAnnotationParam2");
         testService.asyncCallable(() -> {
             visit("http://localhost:8080/apm-toolkit-trace-scenario/case/asyncVisit/callable");
             return true;
@@ -62,7 +62,7 @@ public class TestController {
                 // ignore
             }
         });
-        testService.asyncSupplier(()->{
+        testService.asyncSupplier(() -> {
             try {
                 visit("http://localhost:8080/apm-toolkit-trace-scenario/case/asyncVisit/supplier");
             } catch (IOException e) {
@@ -90,7 +90,7 @@ public class TestController {
 
     @RequestMapping("/asyncVisit/supplier")
     public String asyncVisitSupplier() {
-    	return SUCCESS;
+        return SUCCESS;
     }
 
 

test/plugin/scenarios/apm-toolkit-trace-scenario/src/main/java/test/org/apache/skywalking/apm/testcase/toolkit/controller/TestService.java

@@ -22,6 +22,8 @@ import org.apache.skywalking.apm.toolkit.trace.ActiveSpan;
 import org.apache.skywalking.apm.toolkit.trace.CallableWrapper;
 import org.apache.skywalking.apm.toolkit.trace.RunnableWrapper;
 import org.apache.skywalking.apm.toolkit.trace.SupplierWrapper;
+import org.apache.skywalking.apm.toolkit.trace.Tag;
+import org.apache.skywalking.apm.toolkit.trace.Tags;
 import org.apache.skywalking.apm.toolkit.trace.Trace;
 import org.springframework.stereotype.Component;
 
@@ -48,6 +50,13 @@ public class TestService {
         ActiveSpan.tag("key", "value");
     }
 
+    @Trace
+    @Tag(key = "p1", value = "arg[0]")
+    @Tag(key = "p2", value = "arg[1]")
+    public void testTagAnnotation(String param1, String param2) {
+        // whatever
+    }
+
     @Trace
     public void testError() {
         ActiveSpan.error();
@@ -69,7 +78,8 @@ public class TestService {
     }
 
     @Trace
-    public void testInfo() {
+    @Tag(key = "testTag", value = "arg[0]")
+    public void testInfo(final String testInfoParam) {
         ActiveSpan.info("TestInfoMsg");
     }