diff --git a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/ContextManager.java b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/ContextManager.java
index 892a195b55b1d9581b380f722794ba9468d9b4a3..d97490dc2de7322c5b6ff9501a80ed379e015b16 100644
--- a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/ContextManager.java
+++ b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/ContextManager.java
@@ -119,7 +119,9 @@ public class ContextManager implements TracingContextListener, BootService, Igno
if (carrier == null) {
throw new IllegalArgumentException("ContextCarrier can't be null.");
}
- get().extract(carrier);
+ if (carrier.isValid()) {
+ get().extract(carrier);
+ }
}
public ContextSnapshot capture() {
@@ -130,7 +132,9 @@ public class ContextManager implements TracingContextListener, BootService, Igno
if (snapshot == null) {
throw new IllegalArgumentException("ContextSnapshot can't be null.");
}
- get().continued(snapshot);
+ if (snapshot.isValid()) {
+ get().continued(snapshot);
+ }
}
public static AbstractSpan activeSpan() {
diff --git a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/ContextSnapshot.java b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/ContextSnapshot.java
index 63ac88c96ec14dd5545e2b6cfbc7656a76278dd0..755a2275d8b0b0662ee96592fd381fd8ecbc1c36 100644
--- a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/ContextSnapshot.java
+++ b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/ContextSnapshot.java
@@ -4,13 +4,20 @@ import java.util.List;
import org.skywalking.apm.agent.core.context.ids.DistributedTraceId;
/**
- * The ContextSnapshot
is a snapshot for current context.
+ * The ContextSnapshot
is a snapshot for current context. The snapshot carries the info for building
+ * reference between two segments in two thread, but have a causal relationship.
*
* @author wusheng
*/
public class ContextSnapshot {
+ /**
+ * trace segment id of the parent trace segment.
+ */
private String traceSegmentId;
+ /**
+ * span id of the parent span, in parent trace segment.
+ */
private int spanId = -1;
/**
@@ -36,4 +43,11 @@ public class ContextSnapshot {
public int getSpanId() {
return spanId;
}
+
+ public boolean isValid() {
+ return traceSegmentId != null
+ && spanId > -1
+ && distributedTraceIds != null
+ && distributedTraceIds.size() > 0;
+ }
}
diff --git a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/IgnoredTracerContext.java b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/IgnoredTracerContext.java
index baa1ddcd9b55c81a1886125cde5bb7621d1dc1e7..4ad37e361a73b6403b534d0d5acf8cfddcca94c2 100644
--- a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/IgnoredTracerContext.java
+++ b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/IgnoredTracerContext.java
@@ -7,8 +7,9 @@ import org.skywalking.apm.agent.core.context.trace.NoopSpan;
/**
* The IgnoredTracerContext
represent a context should be ignored.
- * So it just maintains the stack with integer depth.
- * All operations through this IgnoredTracerContext
will be ignored, with low gc cost.
+ * So it just maintains the stack with an integer depth field.
+ *
+ * All operations through this will be ignored, and keep the memory and gc cost as low as possible.
*
* @author wusheng
*/
diff --git a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/TracingContext.java b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/TracingContext.java
index f84244a5f1d462a25afb0cbd21017a7e3224db43..15e41c2a85bac32762880cc396d3414012400153 100644
--- a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/TracingContext.java
+++ b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/TracingContext.java
@@ -112,12 +112,24 @@ public class TracingContext implements AbstractTracerContext {
carrier.setDistributedTraceIds(this.segment.getRelatedGlobalTraces());
}
+ /**
+ * Extract the carrier to build the reference for the pre segment.
+ *
+ * @param carrier carried the context from a cross-process segment.
+ * @see {@link AbstractTracerContext#extract(ContextCarrier)}
+ */
@Override
public void extract(ContextCarrier carrier) {
this.segment.ref(new TraceSegmentRef(carrier));
this.segment.relatedGlobalTraces(carrier.getDistributedTraceIds());
}
+ /**
+ * Capture the snapshot of current context.
+ *
+ * @return the snapshot of context for cross-thread propagation
+ * @see {@link AbstractTracerContext#capture()}
+ */
@Override
public ContextSnapshot capture() {
return new ContextSnapshot(segment.getTraceSegmentId(),
@@ -126,17 +138,33 @@ public class TracingContext implements AbstractTracerContext {
);
}
+ /**
+ * Continue the context from the given snapshot of parent thread.
+ *
+ * @param snapshot from {@link #capture()} in the parent thread.
+ * @see {@link AbstractTracerContext#continued(ContextSnapshot)}
+ */
@Override
public void continued(ContextSnapshot snapshot) {
this.segment.ref(new TraceSegmentRef(snapshot));
this.segment.relatedGlobalTraces(snapshot.getDistributedTraceIds());
}
+ /**
+ * @return the first global trace id.
+ */
@Override
public String getGlobalTraceId() {
return segment.getRelatedGlobalTraces().get(0).get();
}
+ /**
+ * Create an entry span
+ *
+ * @param operationName most likely a service name
+ * @return span instance.
+ * @see {@link EntrySpan}
+ */
@Override
public AbstractSpan createEntrySpan(final String operationName) {
AbstractTracingSpan entrySpan;
@@ -174,6 +202,13 @@ public class TracingContext implements AbstractTracerContext {
}
}
+ /**
+ * Create a local span
+ *
+ * @param operationName most likely a local method signature, or business name.
+ * @return the span represents a local logic block.
+ * @see {@link LocalSpan}
+ */
@Override
public AbstractSpan createLocalSpan(final String operationName) {
AbstractTracingSpan parentSpan = peek();
@@ -195,6 +230,14 @@ public class TracingContext implements AbstractTracerContext {
return push(span);
}
+ /**
+ * Create an exit span
+ *
+ * @param operationName most likely a service name of remote
+ * @param remotePeer the network id(ip:port, hostname:port or ip1:port1,ip2,port, etc.)
+ * @return the span represent an exit point of this segment.
+ * @see {@link ExitSpan}
+ */
@Override
public AbstractSpan createExitSpan(final String operationName, final String remotePeer) {
AbstractTracingSpan exitSpan;
@@ -236,6 +279,9 @@ public class TracingContext implements AbstractTracerContext {
return exitSpan;
}
+ /**
+ * @return the active span of current context, the top element of {@link #activeSpanStack}
+ */
@Override
public AbstractTracingSpan activeSpan() {
AbstractTracingSpan span = peek();
@@ -245,6 +291,12 @@ public class TracingContext implements AbstractTracerContext {
return span;
}
+ /**
+ * Stop the given span, if and only if this one is the top element of {@link #activeSpanStack}.
+ * Because the tracing core must make sure the span must match in a stack module, like any program did.
+ *
+ * @param span to finish
+ */
@Override
public void stopSpan(AbstractSpan span) {
AbstractTracingSpan lastSpan = peek();
@@ -281,6 +333,10 @@ public class TracingContext implements AbstractTracerContext {
TracingContext.ListenerManager.notifyFinish(finishedSegment);
}
+ /**
+ * The ListenerManager
represents an event notify for every registered listener, which are notified
+ * when the TracingContext finished, and {@link #segment} is ready for further process.
+ */
public static class ListenerManager {
private static List LISTENERS = new LinkedList();
diff --git a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/EntrySpan.java b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/EntrySpan.java
index aae12a8a30a0f1bc0a2a650500fbddf51f0948fd..24ca06291419e07c7b6fae69dbdf0d74a3778bd3 100644
--- a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/EntrySpan.java
+++ b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/EntrySpan.java
@@ -6,11 +6,14 @@ import org.skywalking.apm.network.trace.component.Component;
/**
* The EntrySpan
represents a service provider point, such as Tomcat server entrance.
*
- * It is a start point of {@link TraceSegment}, even in a complex application, there maybe have multi entry point,
+ * It is a start point of {@link TraceSegment}, even in a complex application, there maybe have multi-layer entry point,
* the EntrySpan
only represents the first one.
*
* But with the last EntrySpan
's tags and logs, which have more details about a service provider.
*
+ * Such as: Tomcat Embed -> Dubbox
+ * The EntrySpan
represents the Dubbox span.
+ *
* @author wusheng
*/
public class EntrySpan extends AbstractTracingSpan {
diff --git a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/ExitSpan.java b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/ExitSpan.java
index 95fee05a9a06398468a755de37aae451e252567e..524aeceeb643201e0b8a4af08112d52aa06b01e4 100644
--- a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/ExitSpan.java
+++ b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/ExitSpan.java
@@ -5,13 +5,16 @@ import org.skywalking.apm.network.proto.SpanObject;
import org.skywalking.apm.network.trace.component.Component;
/**
- * The ExitSpan
represents a service consumer point, such as Feign, Okhttp discovery for a Http service.
+ * The ExitSpan
represents a service consumer point, such as Feign, Okhttp client for a Http service.
*
* It is an exit point or a leaf span(our old name) of trace tree.
- * In a single rpc call, because of a combination of discovery libs, there maybe contain multi exit point.
+ * In a single rpc call, because of a combination of discovery libs, there maybe contain multi-layer exit point:
*
* The ExitSpan
only presents the first one.
*
+ * Such as: Dubbox -> Apache Httpcomponent -> ....(Remote)
+ * The ExitSpan
represents the Dubbox span, and ignore the httpcomponent span's info.
+ *
* @author wusheng
*/
public class ExitSpan extends AbstractTracingSpan {
diff --git a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/NoopSpan.java b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/NoopSpan.java
index b4138390c5acc5d7656e13450563c4bf39470cc1..7274064a4902bf0cc546433de997f8be191c3315 100644
--- a/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/NoopSpan.java
+++ b/apm-sniffer/apm-agent-core/src/main/java/org/skywalking/apm/agent/core/context/trace/NoopSpan.java
@@ -5,7 +5,8 @@ import org.skywalking.apm.network.trace.component.Component;
/**
* The NoopSpan
represents a span implementation without any actual operation.
- * This span implementation is for {@link IgnoredTracerContext}.
+ * This span implementation is for {@link IgnoredTracerContext},
+ * for keeping the memory and gc cost as low as possible.
*
* @author wusheng
*/
@@ -13,7 +14,6 @@ public class NoopSpan implements AbstractSpan {
public NoopSpan() {
}
-
@Override
public AbstractSpan log(Throwable t) {
return this;
@@ -23,7 +23,7 @@ public class NoopSpan implements AbstractSpan {
return null;
}
- public void finish(){
+ public void finish() {
}