Updating Trace Context headers implementation

CHANGELOG.asciidoc

@@ -19,6 +19,21 @@ endif::[]
 ////
 
 === Unreleased
+[[release-notes-1.14.0]]
+==== 1.14.0 - YYYY/MM/DD
+
+[float]
+===== Breaking changes
+
+[float]
+===== Features
+* Support for the official https://www.w3.org/TR/trace-context[W3C] `traceparent` and `tracestate` headers. +
+  The agent now accepts both the `elastic-apm-traceparent` and the official `traceparent` header.
+  By default, it sends both headers on outgoing requests,
+  unless <<config-use-elastic-traceparent-header, `use_elastic_traceparent_header`>> is set to false.
+
+[float]
+===== Bug fixes
 
 [[release-notes-1.x]]
 === Java Agent version 1.x

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

@@ -11,9 +11,9 @@
  * 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
@@ -30,7 +30,6 @@
 import co.elastic.apm.agent.impl.ElasticApmTracer;
 import co.elastic.apm.agent.impl.transaction.AbstractSpan;
 import co.elastic.apm.agent.impl.transaction.Span;
-import co.elastic.apm.agent.impl.transaction.TraceContext;
 import co.elastic.apm.agent.impl.transaction.TraceContextHolder;
 import co.elastic.apm.agent.matcher.WildcardMatcher;
 import net.bytebuddy.asm.Advice;
@@ -75,7 +74,7 @@ public static void onMethodEnter(@Advice.Origin Class<?> clazz,
         if (tracer != null) {
             final TraceContextHolder<?> parent = tracer.getActive();
             if (parent == null) {
-                span = tracer.startTransaction(TraceContext.asRoot(), null, clazz.getClassLoader())
+                span = tracer.startRootTransaction(clazz.getClassLoader())
                     .withName(signature)
                     .activate();
             } else if (parent.isSampled()) {

apm-agent-core/src/main/java/co/elastic/apm/agent/configuration/CoreConfiguration.java

@@ -497,6 +497,32 @@ public class CoreConfiguration extends ConfigurationOptionProvider {
             "NOTE: this option can only be set via system properties, environment variables or the attacher options.")
         .buildWithDefault(DEFAULT_CONFIG_FILE);
 
+    private final ConfigurationOption<Boolean> useElasticTraceparentHeader = ConfigurationOption.booleanOption()
+        .key("use_elastic_traceparent_header")
+        .tags("added[1.14.0]")
+        .configurationCategory(CORE_CATEGORY)
+        .description("To enable {apm-overview-ref-v}/distributed-tracing.html[distributed tracing], the agent\n" +
+            "adds trace context headers to outgoing requests (like HTTP requests, Kafka records, gRPC requests etc.).\n" +
+            "These headers (`traceparent` and `tracestate`) are defined in the\n" +
+            "https://www.w3.org/TR/trace-context-1/[W3C Trace Context] specification.\n" +
+            "\n" +
+            "When this setting is `true`, the agent will also add the header `elastic-apm-traceparent`\n" +
+            "for backwards compatibility with older versions of Elastic APM agents.")
+        .dynamic(true)
+        .buildWithDefault(true);
+
+    private final ConfigurationOption<Integer> tracestateHeaderSizeLimit = ConfigurationOption.integerOption()
+        .key("tracestate_header_size_limit")
+        .tags("added[1.14.0]")
+        .configurationCategory(CORE_CATEGORY)
+        .description("The agent delegates the `tracestate` header, if received, as defined in the\n" +
+            "https://www.w3.org/TR/trace-context-1/[W3C Trace Context] specification.\n" +
+            "\n" +
+            "This setting limits the size of the `tracestate` header.")
+        .dynamic(true)
+        .tags("internal")
+        .buildWithDefault(4096);
+
     public boolean isActive() {
         return active.get();
     }
@@ -617,6 +643,14 @@ public boolean isBreakdownMetricsEnabled() {
         return breakdownMetrics.get();
     }
 
+    public boolean isElasticTraceparentHeaderEnabled() {
+        return useElasticTraceparentHeader.get();
+    }
+
+    public int getTracestateSizeLimit() {
+        return tracestateHeaderSizeLimit.get();
+    }
+
     /*
      * Makes sure to not initialize ConfigurationOption, which would initialize the logger
      */

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

@@ -36,7 +36,10 @@
 import co.elastic.apm.agent.impl.sampling.Sampler;
 import co.elastic.apm.agent.impl.stacktrace.StacktraceConfiguration;
 import co.elastic.apm.agent.impl.transaction.AbstractSpan;
+import co.elastic.apm.agent.impl.transaction.BinaryHeaderGetter;
+import co.elastic.apm.agent.impl.transaction.HeaderGetter;
 import co.elastic.apm.agent.impl.transaction.Span;
+import co.elastic.apm.agent.impl.transaction.TextHeaderGetter;
 import co.elastic.apm.agent.impl.transaction.TraceContext;
 import co.elastic.apm.agent.impl.transaction.TraceContextHolder;
 import co.elastic.apm.agent.impl.transaction.Transaction;
@@ -150,60 +153,119 @@ public void onChange(ConfigurationOption<?> configurationOption, Double oldValue
         reporter.scheduleMetricReporting(metricRegistry, configurationRegistry.getConfig(ReporterConfiguration.class).getMetricsIntervalMs());
 
         // sets the assertionsEnabled flag to true if indeed enabled
+        //noinspection AssertWithSideEffects
         assert assertionsEnabled = true;
     }
 
-    public <T> Transaction startRootTransaction(@Nullable ClassLoader initiatingClassLoader) {
-        return startTransaction(TraceContext.asRoot(), null, initiatingClassLoader);
+    /**
+     * Starts a trace-root transaction
+     *
+     * @param initiatingClassLoader the class loader corresponding to the service which initiated the creation of the transaction.
+     *                              Used to determine the service name.
+     * @return a transaction which is a child of the provided parent
+     */
+    public Transaction startRootTransaction(@Nullable ClassLoader initiatingClassLoader) {
+        return startRootTransaction(sampler, -1, initiatingClassLoader);
     }
 
     /**
-     * Starts a transaction as a child of the provided parent
+     * Starts a trace-root transaction with a specified sampler and start timestamp
      *
-     * @param childContextCreator   used to make the transaction a child of the provided parent
-     * @param parent                the parent of the transaction. May be a traceparent header.
+     * @param sampler               the {@link Sampler} instance which is responsible for determining the sampling decision if this is a root transaction
+     * @param epochMicros           the start timestamp
      * @param initiatingClassLoader the class loader corresponding to the service which initiated the creation of the transaction.
-     *                              Used to determine the service name.
-     * @param <T>                   the type of the parent. {@code String} in case of a traceparent header.
+     *                              Used to determine the service name and to load application-scoped classes like the {@link org.slf4j.MDC},
+     *                              for log correlation.
      * @return a transaction which is a child of the provided parent
      */
-    public <T> Transaction startTransaction(TraceContext.ChildContextCreator<T> childContextCreator, @Nullable T parent, @Nullable ClassLoader initiatingClassLoader) {
-        return startTransaction(childContextCreator, parent, sampler, -1, initiatingClassLoader);
+    public Transaction startRootTransaction(Sampler sampler, long epochMicros, @Nullable ClassLoader initiatingClassLoader) {
+        Transaction transaction;
+        if (!coreConfiguration.isActive()) {
+            transaction = noopTransaction();
+        } else {
+            transaction = createTransaction().start(TraceContext.asRoot(), null, epochMicros, sampler, initiatingClassLoader);
+        }
+        afterTransactionStart(initiatingClassLoader, transaction);
+        return transaction;
     }
 
-    public void avoidWrappingOnThread() {
-        allowWrappingOnThread.set(Boolean.FALSE);
+    /**
+     * Starts a transaction as a child of the context headers obtained through the provided {@link HeaderGetter}
+     *
+     * @param headerCarrier         the Object from which context headers can be obtained, typically a request or a message
+     * @param textHeadersGetter     provides the trace context headers required in order to create a child transaction
+     * @param initiatingClassLoader the class loader corresponding to the service which initiated the creation of the transaction.
+     *                              Used to determine the service name.
+     * @return a transaction which is a child of the provided parent
+     */
+    public <C> Transaction startChildTransaction(@Nullable C headerCarrier, TextHeaderGetter<C> textHeadersGetter, @Nullable ClassLoader initiatingClassLoader) {
+        return startChildTransaction(headerCarrier, textHeadersGetter, sampler, -1, initiatingClassLoader);
     }
 
-    public void allowWrappingOnThread() {
-        allowWrappingOnThread.set(Boolean.TRUE);
+    /**
+     * Starts a transaction as a child of the context headers obtained through the provided {@link HeaderGetter}
+     *
+     * @param headerCarrier         the Object from which context headers can be obtained, typically a request or a message
+     * @param textHeadersGetter     provides the trace context headers required in order to create a child transaction
+     * @param sampler               the {@link Sampler} instance which is responsible for determining the sampling decision if this is a root transaction
+     * @param epochMicros           the start timestamp
+     * @param initiatingClassLoader the class loader corresponding to the service which initiated the creation of the transaction.
+     *                              Used to determine the service name and to load application-scoped classes like the {@link org.slf4j.MDC},
+     *                              for log correlation.
+     * @return a transaction which is a child of the provided parent
+     */
+    public <C> Transaction startChildTransaction(@Nullable C headerCarrier, TextHeaderGetter<C> textHeadersGetter, Sampler sampler,
+                                                 long epochMicros, @Nullable ClassLoader initiatingClassLoader) {
+        Transaction transaction;
+        if (!coreConfiguration.isActive()) {
+            transaction = noopTransaction();
+        } else {
+            transaction = createTransaction().start(TraceContext.<C>getFromTraceContextTextHeaders(), headerCarrier,
+                textHeadersGetter, epochMicros, sampler, initiatingClassLoader);
+        }
+        afterTransactionStart(initiatingClassLoader, transaction);
+        return transaction;
     }
 
-    public boolean isWrappingAllowedOnThread() {
-        return allowWrappingOnThread.get() == Boolean.TRUE;
+    /**
+     * Starts a transaction as a child of the context headers obtained through the provided {@link HeaderGetter}
+     *
+     * @param headerCarrier         the Object from which context headers can be obtained, typically a request or a message
+     * @param binaryHeadersGetter   provides the trace context headers required in order to create a child transaction
+     * @param initiatingClassLoader the class loader corresponding to the service which initiated the creation of the transaction.
+     *                              Used to determine the service name.
+     * @return a transaction which is a child of the provided parent
+     */
+    public <C> Transaction startChildTransaction(@Nullable C headerCarrier, BinaryHeaderGetter<C> binaryHeadersGetter, @Nullable ClassLoader initiatingClassLoader) {
+        return startChildTransaction(headerCarrier, binaryHeadersGetter, sampler, -1, initiatingClassLoader);
     }
 
     /**
-     * Starts a transaction as a child of the provided parent
+     * Starts a transaction as a child of the context headers obtained through the provided {@link HeaderGetter}
      *
-     * @param childContextCreator   used to make the transaction a child of the provided parent
-     * @param parent                the parent of the transaction. May be a traceparent header.
+     * @param headerCarrier         the Object from which context headers can be obtained, typically a request or a message
+     * @param binaryHeadersGetter   provides the trace context headers required in order to create a child transaction
      * @param sampler               the {@link Sampler} instance which is responsible for determining the sampling decision if this is a root transaction
      * @param epochMicros           the start timestamp
      * @param initiatingClassLoader the class loader corresponding to the service which initiated the creation of the transaction.
      *                              Used to determine the service name and to load application-scoped classes like the {@link org.slf4j.MDC},
      *                              for log correlation.
-     * @param <T>                   the type of the parent. {@code String} in case of a traceparent header.
      * @return a transaction which is a child of the provided parent
      */
-    public <T> Transaction startTransaction(TraceContext.ChildContextCreator<T> childContextCreator, @Nullable T parent, Sampler sampler,
-                                            long epochMicros, @Nullable ClassLoader initiatingClassLoader) {
+    public <C> Transaction startChildTransaction(@Nullable C headerCarrier, BinaryHeaderGetter<C> binaryHeadersGetter,
+                                                 Sampler sampler, long epochMicros, @Nullable ClassLoader initiatingClassLoader) {
         Transaction transaction;
         if (!coreConfiguration.isActive()) {
             transaction = noopTransaction();
         } else {
-            transaction = createTransaction().start(childContextCreator, parent, epochMicros, sampler, initiatingClassLoader);
+            transaction = createTransaction().start(TraceContext.<C>getFromTraceContextBinaryHeaders(), headerCarrier,
+                binaryHeadersGetter, epochMicros, sampler, initiatingClassLoader);
         }
+        afterTransactionStart(initiatingClassLoader, transaction);
+        return transaction;
+    }
+
+    private void afterTransactionStart(@Nullable ClassLoader initiatingClassLoader, Transaction transaction) {
         if (logger.isDebugEnabled()) {
             logger.debug("startTransaction {} {", transaction);
             if (logger.isTraceEnabled()) {
@@ -215,7 +277,18 @@ public <T> Transaction startTransaction(TraceContext.ChildContextCreator<T> chil
         if (serviceName != null) {
             transaction.getTraceContext().setServiceName(serviceName);
         }
-        return transaction;
+    }
+
+    public void avoidWrappingOnThread() {
+        allowWrappingOnThread.set(Boolean.FALSE);
+    }
+
+    public void allowWrappingOnThread() {
+        allowWrappingOnThread.set(Boolean.TRUE);
+    }
+
+    public boolean isWrappingAllowedOnThread() {
+        return allowWrappingOnThread.get() == Boolean.TRUE;
     }
 
     public Transaction noopTransaction() {

apm-agent-core/src/main/java/co/elastic/apm/agent/impl/context/Message.java

@@ -11,9 +11,9 @@
  * 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
@@ -37,7 +37,6 @@
 
 public class Message implements Recyclable {
 
-    @SuppressWarnings({"Convert2Diamond", "Convert2Lambda", "Anonymous2MethodRef"})
     private static final ObjectPool<StringBuilder> stringBuilderPool = QueueBasedObjectPool.of(new MpmcAtomicArrayQueue<StringBuilder>(128), false,
         new Allocator<StringBuilder>() {
             @Override

apm-agent-core/src/main/java/co/elastic/apm/agent/impl/transaction/AbstractHeaderGetter.java

@@ -0,0 +1,35 @@
+/*-
+ * #%L
+ * Elastic APM Java agent
+ * %%
+ * Copyright (C) 2018 - 2020 Elastic and contributors
+ * %%
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. 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.
+ * #L%
+ */
+package co.elastic.apm.agent.impl.transaction;
+
+public abstract class AbstractHeaderGetter<T, C> implements HeaderGetter<T, C> {
+    @Override
+    public <S> void forEach(String headerName, C carrier, S state, HeaderConsumer<T, S> consumer) {
+        T firstHeader = getFirstHeader(headerName, carrier);
+        if (firstHeader != null) {
+            consumer.accept(firstHeader, state);
+        }
+    }
+}

apm-agent-core/src/main/java/co/elastic/apm/agent/impl/transaction/BinaryHeaderGetter.java

@@ -0,0 +1,28 @@
+/*-
+ * #%L
+ * Elastic APM Java agent
+ * %%
+ * Copyright (C) 2018 - 2020 Elastic and contributors
+ * %%
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. 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.
+ * #L%
+ */
+package co.elastic.apm.agent.impl.transaction;
+
+public interface BinaryHeaderGetter<C> extends HeaderGetter<byte[], C> {
+}