Megrez

public final class PendingSpans extends ReferenceQueue<TraceContext> {
  // Even though we only put by RealKey, we allow get and remove by LookupKey
  final ConcurrentMap<Object, PendingSpan> delegate = new ConcurrentHashMap<>(64);
<SNIP>
  public PendingSpan getOrCreate(TraceContext context, boolean start) {
    if (context == null) throw new NullPointerException("context == null");
    // 每次在创建MutableSpan的时候都会去检查OrphanedSpans
    reportOrphanedSpans();

<SNIP 省略创建MutableSpan和Clock的逻辑，留着以后分析> 

    // 把context封装成WeakRef的实现RealKey并放到ConcurrentHashMap中
    PendingSpan previousSpan = delegate.putIfAbsent(new RealKey(context, this), newSpan);
    if (previousSpan != null) return previousSpan; // lost race
    // 是否需要追踪OrphanSpan的创建用于诊断问题
    // 如果需要，则会跟踪响应的线程和堆栈(Throwable.fillInStackTrace())
    if (trackOrphans) {
      newSpan.caller =
        new Throwable("Thread " + Thread.currentThread().getName() + " allocated span here");
    }
    return newSpan;
  }
<SNIP>
}

public final class PendingSpans extends ReferenceQueue<TraceContext> {
  // Even though we only put by RealKey, we allow get and remove by LookupKey
  final ConcurrentMap<Object, PendingSpan> delegate = new ConcurrentHashMap<>(64);
<SNIP>
  /** Reports spans orphaned by garbage collection. */
  void reportOrphanedSpans() {
    RealKey contextKey;
    // This is called on critical path of unrelated traced operations. If we have orphaned spans, be
    // careful to not penalize the performance of the caller. It is better to cache time when
    // flushing a span than hurt performance of unrelated operations by calling
    // currentTimeMicroseconds N times
    long flushTime = 0L;
    boolean noop = orphanedSpanHandler == FinishedSpanHandler.NOOP || this.noop.get();
    // 从ReferenceQueue中提取被回收的TraceContext
    while ((contextKey = (RealKey) poll()) != null) {
      // delegate里面保存的是TraceContext到PendingSpan的映射
      PendingSpan value = delegate.remove(contextKey);
      if (noop || value == null) continue;
      if (flushTime == 0L) flushTime = clock.currentTimeMicroseconds();

      boolean isEmpty = value.state.isEmpty();
      Throwable caller = value.caller;

      // 从回收的TraceContext信息恢复TraceContext对象
      TraceContext context = InternalPropagation.instance.newTraceContext(
        contextKey.flags,
        contextKey.traceIdHigh, contextKey.traceId,
        contextKey.localRootId, 0L, contextKey.spanId,
        Collections.emptyList()
      );

      if (caller != null) {
        String message = isEmpty
          ? "Span " + context + " was allocated but never used"
          : "Span " + context + " neither finished nor flushed before GC";
        Platform.get().log(message, caller);
      }
      if (isEmpty) continue;

      // 在MutableSpan中标记一个"brave.flush"事件
      value.state.annotate(flushTime, "brave.flush");
      // 调用相应的Handler来处理OrphanedSpan
      orphanedSpanHandler.handle(context, value.state);
    }
  }
<SNIP>
}

package brave.internal.recorder;
public class PendingSpansTest {
  <SNIP>
  /**
   * This is the key feature. Spans orphaned via GC are reported to zipkin on the next action.
   *
   * <p>This is a customized version of https://github.com/raphw/weak-lock-free/blob/master/src/test/java/com/blogspot/mydailyjava/weaklockfree/WeakConcurrentMapTest.java
   */
  @Test
  public void reportOrphanedSpans_afterGC() {
    // 构建context1
    TraceContext context1 = context.toBuilder().traceId(1).spanId(1).build();
    // 利用Context1创建一个PendingSpan
    PendingSpan span = pendingSpans.getOrCreate(context1, false);
    span.state.name("foo");
    // 移除对span的引用，那么在gc触发的时候span及其关联的Context1就会被回收
    span = null;
    // 类似得，构建context2,context3,context4
    TraceContext context2 = context.toBuilder().traceId(2).spanId(2).build();
    pendingSpans.getOrCreate(context2, false);
    TraceContext context3 = context.toBuilder().traceId(3).spanId(3).build();
    pendingSpans.getOrCreate(context3, false);
    TraceContext context4 = context.toBuilder().traceId(4).spanId(4).build();
    pendingSpans.getOrCreate(context4, false);
    // ensure sampled local spans are not reported when orphaned unless they are also sampled remote
    // context5是一个比较特殊的TraceContext，因为它不需要remote采样，仅设置了local采样，此类Span不会被Reporter收集
    TraceContext context5 =
      context.toBuilder().spanId(5).sampledLocal(true).sampled(false).build();
    pendingSpans.getOrCreate(context5, false);

    int initialClockVal = clock.get();

    // By clearing strong references in this test, we are left with the weak ones in the map
    // 移除context1, 2, 5的强引用，确保这几个对象会被gc
    context1 = context2 = context5 = null;
    // 模拟GC的过程，其实是调用了System.gc()
    GarbageCollectors.blockOnGC();

    // After GC, we expect that the weak references of context1 and context2 to be cleared
    // 在GC发生以后，由于Key是一个WeakReference，context1, 2, 5都会被回收，从而Key变成null
    assertThat(pendingSpans.delegate.keySet()).extracting(o -> ((Reference) o).get())
      .containsExactlyInAnyOrder(null, null, context3, context4, null);

    // Key为null的都会从ConcurrentHashMap中删除
    pendingSpans.reportOrphanedSpans();

    // After reporting, we expect no the weak references of null
    // 此时ConcurrentHashMap仅包含未被回收的context3,4
    assertThat(pendingSpans.delegate.keySet()).extracting(o -> ((Reference) o).get())
      .containsExactlyInAnyOrder(context3, context4);

    // We also expect only the sampled span containing data to have been reported
    assertThat(spans).hasSize(1);
    assertThat(spans.get(0).id()).isEqualTo("0000000000000001");
    assertThat(spans.get(0).name()).isEqualTo("foo"); // data was flushed
    assertThat(spans.get(0).annotations())
      .containsExactly(Annotation.create((initialClockVal + 1) * 1000, "brave.flush"));
  }

  <SNIP>
}