Allow setting manual start and end timestamps (#541)

closes #236

Author: felixbarny

CHANGELOG.md

@@ -7,6 +7,8 @@
    As of version 7.x of the stack, labels will be stored under `labels` in Elasticsearch.
    Previously, they were stored under `context.tags`.
  * Support async queries made by Elasticsearch REST client 
+ * Added `setStartTimestamp(long epochMicros)` and `end(long epochMicros)` API methods to `Span` and `Transaction`,
+   allowing to set custom start and end timestamps.
 
 ## Bug Fixes
 

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

@@ -57,6 +57,10 @@ public Span startSpan() {
         return span != null ? new SpanImpl(span) : NoopSpan.INSTANCE;
     }
 
+    public void doSetStartTimestamp(long epochMicros) {
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation$SetStartTimestampInstrumentation
+    }
+
     private Object doCreateSpan() {
         // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation$DoCreateSpanInstrumentation.doCreateSpan
         return null;
@@ -94,7 +98,12 @@ void doAddBooleanLabel(String key, Boolean value) {
 
     @Override
     public void end() {
-        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation$EndInstrumentation.end
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation$EndInstrumentation
+    }
+
+    @Override
+    public void end(long epochMicros) {
+        // co.elastic.apm.agent.plugin.api.AbstractSpanInstrumentation$EndWithTimestampInstrumentation
     }
 
     @Override

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

@@ -69,6 +69,11 @@ public void end() {
         // noop
     }
 
+    @Override
+    public void end(long epochMicros) {
+        // noop
+    }
+
     @Override
     public void captureException(Throwable throwable) {
         // co.elastic.apm.agent.plugin.api.CaptureExceptionInstrumentation
@@ -114,6 +119,11 @@ public Span startSpan() {
         return INSTANCE;
     }
 
+    @Override
+    public Span setStartTimestamp(long epochMicros) {
+        return INSTANCE;
+    }
+
     @Override
     public void injectTraceHeaders(HeaderInjector headerInjector) {
         // noop

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

@@ -82,6 +82,11 @@ public void end() {
         // noop
     }
 
+    @Override
+    public void end(long epochMicros) {
+        // noop
+    }
+
     @Override
     public void captureException(Throwable throwable) {
         // co.elastic.apm.agent.plugin.api.CaptureExceptionInstrumentation
@@ -133,6 +138,10 @@ public Span startSpan() {
         return NoopSpan.INSTANCE;
     }
 
+    @Override
+    public Transaction setStartTimestamp(long epochMicros) {
+        return this;
+    }
 
     @Override
     public void injectTraceHeaders(HeaderInjector headerInjector) {

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

@@ -145,6 +145,15 @@ public interface Span {
     @Nonnull
     Span addLabel(String key, boolean value);
 
+    /**
+     * Sets the start timestamp of this event.
+     *
+     * @param epochMicros the timestamp of when this event happened, in microseconds (µs) since epoch
+     * @return {@code this} for chaining
+     * @since 1.5.0
+     */
+    Span setStartTimestamp(long epochMicros);
+
     /**
      * NOTE: THIS METHOD IS DEPRECATED AND WILL BE REMOVED IN VERSION 2.0.
      * Instead, start a new span through {@link #startSpan()} or {@link #startSpan(String, String, String)}.
@@ -180,8 +189,8 @@ public interface Span {
      * </p>
      * <p>
      * The type, subtype and action strings are used to group similar spans together, with increasing resolution.
-     * For instance, all DB spans are given the type `db`; all spans of MySQL queries are given the subtype `mysql` and all spans 
-     * describing queries are give the action `query`.
+     * For instance, all DB spans are given the type `db`; all spans of MySQL queries are given the subtype `mysql` and all spans
+     * describing queries are given the action `query`.
      * </p>
      * <p>
      * In the above example `db` is considered the general type. Though there are no naming restrictions for the general types,
@@ -223,7 +232,7 @@ public interface Span {
      * NOTE: Spans created via this method can not be retrieved by calling {@link ElasticApm#currentSpan()}.
      * See {@link #activate()} on how to achieve that.
      * </p>
-     * 
+     *
      * @return the started span, never {@code null}
      */
     @Nonnull
@@ -236,6 +245,15 @@ public interface Span {
      */
     void end();
 
+    /**
+     * Ends the span and schedules it to be reported to the APM Server.
+     * It is illegal to call any methods on a span instance which has already ended.
+     * This also includes this method and {@link #startSpan()}.
+     *
+     * @param epochMicros the timestamp of when this event ended, in microseconds (µs) since epoch
+     */
+    void end(long epochMicros);
+
     /**
      * Captures an exception and reports it to the APM server.
      *

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

@@ -75,4 +75,10 @@ public Span addLabel(String key, boolean value) {
         return this;
     }
 
+    @Override
+    public Span setStartTimestamp(long epochMicros) {
+        doSetStartTimestamp(epochMicros);
+        return this;
+    }
+
 }

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

@@ -103,6 +103,9 @@ public interface Transaction extends Span {
      */
     Transaction setResult(String result);
 
+    @Override
+    Transaction setStartTimestamp(long epochMicros);
+
     /**
      * End tracking the transaction.
      * <p>

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

@@ -96,4 +96,10 @@ public String ensureParentId() {
         return "";
     }
 
+    @Override
+    public Transaction setStartTimestamp(long epochMicros) {
+        doSetStartTimestamp(epochMicros);
+        return this;
+    }
+
 }

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

@@ -39,7 +39,7 @@ public abstract class AbstractSpan<T extends AbstractSpan> extends TraceContextH
      * Generic designation of a transaction in the scope of a single service (eg: 'GET /users/:id')
      */
     protected final StringBuilder name = new StringBuilder();
-    protected long timestamp;
+    private long timestamp;
     /**
      * How long the transaction took to complete, in ms with 3 decimal points
      * (Required)
@@ -214,4 +214,9 @@ public <V> Callable<V> withActive(Callable<V> callable) {
             return tracer.wrapCallable(callable, traceContext);
         }
     }
+
+    public void setStartTimestamp(long epochMicros) {
+        timestamp = epochMicros;
+    }
+
 }

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

@@ -70,9 +70,9 @@ public <T> Span start(TraceContext.ChildContextCreator<T> childContextCreator, T
             traceContext.setRecorded(false);
         }
         if (epochMicros >= 0) {
-            timestamp = epochMicros;
+            setStartTimestamp(epochMicros);
         } else {
-            timestamp = getTraceContext().getClock().getEpochMicros();
+            setStartTimestamp(getTraceContext().getClock().getEpochMicros());
         }
         if (logger.isDebugEnabled()) {
             logger.debug("startSpan {} {", this);