Add annotations to create transactions and spans (#281)

closes #212

Author: felixbarny

CHANGELOG.md

@@ -1,9 +1,11 @@
-# 0.9.0
+# next
 
 ## Breaking changes
  * Remove intake v1 support. This version requires an APM Server which supports the intake api v2.
 
 ## Features
+* Adds `@CaptureTransaction` and `@CaptureSpan` annotations which let you declaratively add custom transactions and spans.
+  Note that it is required to configure the `application_packages` for this to work.
 
 ## Bug Fixes
 

apm-agent-api/src/main/java/co/elastic/apm/api/CaptureSpan.java

@@ -0,0 +1,53 @@
+/*-
+ * #%L
+ * Elastic APM Java agent
+ * %%
+ * Copyright (C) 2018 Elastic and contributors
+ * %%
+ * Licensed 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.
+ * #L%
+ */
+package co.elastic.apm.api;
+
+/**
+ * Annotating a method with {@code @}{@link CaptureSpan} creates a {@link Span} as the child of the currently active span or transaction
+ * ({@link ElasticApm#currentSpan()}).
+ * <p>
+ * When there is no current span,
+ * no span will be created.
+ * </p>
+ * <p>
+ * Note: it is required to configure the {@code application_packages}, otherwise this annotation will be ignored.
+ * </p>
+ */
+public @interface CaptureSpan {
+
+    /**
+     * The name of the {@link Span}.
+     * Defaults to the {@code ClassName#methodName}
+     */
+    String value() default "";
+
+    /**
+     * Sets the type of span.
+     * <p>
+     * The type is a hierarchical string used to group similar spans together.
+     * For instance, all spans of MySQL queries are given the type `db.mysql.query`.
+     * </p>
+     * <p>
+     * In the above example `db` is considered the type prefix. Though there are no naming restrictions for this prefix,
+     * the following are standardized across all Elastic APM agents: `app`, `db`, `cache`, `template`, and `ext`.
+     * </p>
+     */
+    String type() default "app";
+}

apm-agent-api/src/main/java/co/elastic/apm/api/CaptureTransaction.java

@@ -0,0 +1,43 @@
+/*-
+ * #%L
+ * Elastic APM Java agent
+ * %%
+ * Copyright (C) 2018 Elastic and contributors
+ * %%
+ * Licensed 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.
+ * #L%
+ */
+package co.elastic.apm.api;
+
+/**
+ * Annotating a method with {@code @}{@link CaptureTransaction} creates a {@link Transaction} for that method.
+ * <p>
+ * Note that this only works when there is no active transaction on the same thread.
+ * </p>
+ * <p>
+ * Note: it is required to configure the {@code application_packages}, otherwise this annotation will be ignored.
+ * </p>
+ */
+public @interface CaptureTransaction {
+
+    /**
+     * The name of the {@link Transaction}.
+     * Defaults to the {@code ClassName#methodName}
+     */
+    String value() default "";
+
+    /**
+     * The type of the transaction.
+     */
+    String type() default Transaction.TYPE_REQUEST;
+}

apm-agent-core/src/main/java/co/elastic/apm/bci/ElasticApmAgent.java

@@ -19,6 +19,7 @@
  */
 package co.elastic.apm.bci;
 
+import co.elastic.apm.bci.bytebuddy.AnnotationValueOffsetMappingFactory;
 import co.elastic.apm.bci.bytebuddy.ErrorLoggingListener;
 import co.elastic.apm.bci.bytebuddy.MatcherTimer;
 import co.elastic.apm.bci.bytebuddy.SimpleMethodSignatureOffsetMappingFactory;
@@ -176,7 +177,8 @@ public boolean matches(TypeDescription typeDescription, ClassLoader classLoader,
             })
             .transform(new AgentBuilder.Transformer.ForAdvice(Advice
                 .withCustomMapping()
-                .bind(new SimpleMethodSignatureOffsetMappingFactory()))
+                .bind(new SimpleMethodSignatureOffsetMappingFactory())
+                .bind(new AnnotationValueOffsetMappingFactory()))
                 .advice(new ElementMatcher<MethodDescription>() {
                     @Override
                     public boolean matches(MethodDescription target) {

apm-agent-core/src/main/java/co/elastic/apm/bci/bytebuddy/AnnotationValueOffsetMappingFactory.java

@@ -0,0 +1,78 @@
+/*-
+ * #%L
+ * Elastic APM Java agent
+ * %%
+ * Copyright (C) 2018 Elastic and contributors
+ * %%
+ * Licensed 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.
+ * #L%
+ */
+package co.elastic.apm.bci.bytebuddy;
+
+import net.bytebuddy.asm.Advice;
+import net.bytebuddy.description.annotation.AnnotationDescription;
+import net.bytebuddy.description.method.MethodDescription;
+import net.bytebuddy.description.method.ParameterDescription;
+import net.bytebuddy.description.type.TypeDescription;
+import net.bytebuddy.implementation.bytecode.assign.Assigner;
+
+import javax.annotation.Nullable;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import static net.bytebuddy.matcher.ElementMatchers.named;
+
+public class AnnotationValueOffsetMappingFactory implements Advice.OffsetMapping.Factory<AnnotationValueOffsetMappingFactory.AnnotationValueExtractor> {
+
+    @Override
+    public Class<AnnotationValueExtractor> getAnnotationType() {
+        return AnnotationValueExtractor.class;
+    }
+
+    @Override
+    public Advice.OffsetMapping make(final ParameterDescription.InDefinedShape target,
+                                     final AnnotationDescription.Loadable<AnnotationValueExtractor> annotation,
+                                     final AdviceType adviceType) {
+        return new Advice.OffsetMapping() {
+            @Override
+            public Target resolve(TypeDescription instrumentedType, MethodDescription instrumentedMethod, Assigner assigner, Advice.ArgumentHandler argumentHandler, Sort sort) {
+                return Target.ForStackManipulation.of(getAnnotationValue(instrumentedMethod, annotation.loadSilent()));
+            }
+        };
+    }
+
+    @Nullable
+    private Object getAnnotationValue(MethodDescription instrumentedMethod, AnnotationValueExtractor annotationValueExtractor) {
+        for (TypeDescription typeDescription : instrumentedMethod.getDeclaredAnnotations().asTypeList()) {
+            if (named(annotationValueExtractor.annotationClassName()).matches(typeDescription)) {
+                for (MethodDescription.InDefinedShape annotationMethod : typeDescription.getDeclaredMethods()) {
+                    if (annotationMethod.getName().equals(annotationValueExtractor.method())) {
+                        return instrumentedMethod.getDeclaredAnnotations().ofType(typeDescription).getValue(annotationMethod).resolve();
+                    }
+                }
+            }
+        }
+        return null;
+    }
+
+    @Retention(RetentionPolicy.RUNTIME)
+    @Target(ElementType.PARAMETER)
+    public @interface AnnotationValueExtractor {
+        String annotationClassName();
+
+        String method();
+    }
+
+}

apm-agent-core/src/main/java/co/elastic/apm/bci/bytebuddy/SimpleMethodSignatureOffsetMappingFactory.java

@@ -26,6 +26,8 @@
 import net.bytebuddy.description.type.TypeDescription;
 import net.bytebuddy.implementation.bytecode.assign.Assigner;
 
+import javax.annotation.Nullable;
+import java.lang.annotation.Annotation;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ -52,7 +54,8 @@ public Advice.OffsetMapping make(ParameterDescription.InDefinedShape target,
             public Target resolve(TypeDescription instrumentedType, MethodDescription instrumentedMethod, Assigner assigner,
                                   Advice.ArgumentHandler argumentHandler, Sort sort) {
                 final String className = instrumentedMethod.getDeclaringType().getTypeName();
-                final String simpleClassName = className.substring(className.lastIndexOf('.') + 1);
+                String simpleClassName = className.substring(className.lastIndexOf('$') + 1);
+                simpleClassName = simpleClassName.substring(simpleClassName.lastIndexOf('.') + 1);
                 final String signature = String.format("%s#%s", simpleClassName, instrumentedMethod.getName());
                 return Target.ForStackManipulation.of(signature);
             }
@@ -69,4 +72,5 @@ public Target resolve(TypeDescription instrumentedType, MethodDescription instru
     public @interface SimpleMethodSignature {
     }
 
+
 }

apm-agent-core/src/main/java/co/elastic/apm/impl/stacktrace/StacktraceConfiguration.java

@@ -35,7 +35,10 @@ public class StacktraceConfiguration extends ConfigurationOptionProvider {
         .key(APPLICATION_PACKAGES)
         .configurationCategory(STACKTRACE_CATEGORY)
         .description("Used to determine whether a stack trace frame is an 'in-app frame' or a 'library frame'.\n" +
-            "Setting this option can also improve the startup time.")
+            "Setting this option can also improve the startup time.\n" +
+            "\n" +
+            "In order to be able to use the API annotations @CaptureTransaction and @CaptureSpan,\n" +
+            "it is required to set these options.")
         .dynamic(true)
         .buildWithDefault(Collections.<String>emptyList());
 

apm-agent-core/src/test/java/co/elastic/apm/AbstractInstrumentationTest.java

@@ -24,14 +24,18 @@
 import co.elastic.apm.impl.ElasticApmTracer;
 import co.elastic.apm.impl.ElasticApmTracerBuilder;
 import net.bytebuddy.agent.ByteBuddyAgent;
+import org.junit.After;
 import org.junit.AfterClass;
 import org.junit.Before;
 import org.junit.BeforeClass;
 import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.BeforeEach;
 import org.stagemonitor.configuration.ConfigurationRegistry;
 
+import static org.assertj.core.api.Assertions.assertThat;
+
 public abstract class AbstractInstrumentationTest {
     protected static ElasticApmTracer tracer;
     protected static MockReporter reporter;
@@ -77,4 +81,10 @@ public static ConfigurationRegistry getConfig() {
     public final void resetReporter() {
         reset();
     }
+
+    @After
+    @AfterEach
+    public final void cleanUp() {
+        assertThat(tracer.getActive()).isNull();
+    }
 }

apm-agent-core/src/test/resources/elasticapm.properties

@@ -2,3 +2,4 @@ log_level=DEBUG
 log_file=System.out
 # incubating instrumentations should be active in tests
 disable_instrumentations=
+application_packages=co.elastic.apm

apm-agent-plugins/apm-api-plugin/src/main/java/co/elastic/apm/plugin/api/ApiInstrumentation.java

@@ -0,0 +1,39 @@
+/*-
+ * #%L
+ * Elastic APM Java agent
+ * %%
+ * Copyright (C) 2018 Elastic and contributors
+ * %%
+ * Licensed 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.
+ * #L%
+ */
+package co.elastic.apm.plugin.api;
+
+import co.elastic.apm.bci.ElasticApmInstrumentation;
+
+import java.util.Collection;
+import java.util.Collections;
+
+import static co.elastic.apm.plugin.api.ElasticApmApiInstrumentation.PUBLIC_API_INSTRUMENTATION_GROUP;
+
+public abstract class ApiInstrumentation extends ElasticApmInstrumentation {
+    @Override
+    public boolean includeWhenInstrumentationIsDisabled() {
+        return true;
+    }
+
+    @Override
+    public Collection<String> getInstrumentationGroupNames() {
+        return Collections.singleton(PUBLIC_API_INSTRUMENTATION_GROUP);
+    }
+}