Module brave

Package brave.internal.handler

Class ZipkinFinishedSpanHandler

java.lang.Object

brave.handler.FinishedSpanHandler

brave.internal.handler.ZipkinFinishedSpanHandler

public final class ZipkinFinishedSpanHandler
extends FinishedSpanHandler

logs exceptions instead of raising an error, as the supplied reporter could have bugs

Field Summary

Fields inherited from class brave.handler.FinishedSpanHandler

NOOP

Constructor Summary

Constructors

Constructor	Description
ZipkinFinishedSpanHandler(zipkin2.reporter.Reporter<zipkin2.Span> spanReporter, ErrorParser errorParser, java.lang.String serviceName, java.lang.String ip, int port, boolean alwaysReportSpans)

Method Summary

Modifier and Type	Method	Description
boolean	handle(TraceContext context, MutableSpan span)	This is the last in the chain of finished span handlers.
boolean	supportsOrphans()	Normally, FinishedSpanHandler.handle(TraceContext, MutableSpan) is only called upon explicit termination of a span: Span.finish(), Span.finish(long) or Span.flush().
java.lang.String	toString()

Methods inherited from class brave.handler.FinishedSpanHandler

alwaysSampleLocal

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ZipkinFinishedSpanHandler

public ZipkinFinishedSpanHandler(zipkin2.reporter.Reporter<zipkin2.Span> spanReporter,
                                 ErrorParser errorParser,
                                 java.lang.String serviceName,
                                 java.lang.String ip,
                                 int port,
                                 boolean alwaysReportSpans)

Method Detail

handle

public boolean handle(TraceContext context,
                      MutableSpan span)

This is the last in the chain of finished span handlers. A predecessor may have set FinishedSpanHandler.alwaysSampleLocal(), so we have to double-check here that the span was sampled to Zipkin. Otherwise, we could accidentally send 100% data.

Specified by:

handle in class FinishedSpanHandler

Parameters:

context - the trace context which is SamplingFlags.sampled() or SamplingFlags.sampledLocal(). This includes identifiers and potentially extra propagated data such as extended sampling configuration.

span - a mutable object including all data recorded with span apis. Modifications are visible to later handlers, including Zipkin.

Returns:

true retains the span, and should almost always be used. false drops the span, making it invisible to later handlers such as Zipkin.

See Also:

If you are scrubbing personal information, consider supporting orphans.

supportsOrphans

public boolean supportsOrphans()

Description copied from class: FinishedSpanHandler

Normally, FinishedSpanHandler.handle(TraceContext, MutableSpan) is only called upon explicit termination of a span: Span.finish(), Span.finish(long) or Span.flush(). When this method returns true, the callback will also receive data orphaned due to spans being never terminated or data added after termination. It is important to understand this, especially if your handler is performing work like redaction. This sort of work needs to happen on all data, not just the success paths.

What is an orphaned span?

Brave adds an annotation "brave.flush" when data remains associated with a span when it is garbage collected. This is almost always a bug. For example, calling Span.tag(String, String) after calling Span.finish(), or calling Tracer.nextSpan() yet never using the result. To track down bugs like this, set the logger PendingSpans to FINE level.

Why handle orphaned spans?

Use cases for handling orphans include redaction, trimming the "brave.flush" annotation, logging a different way than default, or incrementing bug counters. For example, you could use the same credit card cleaner here as you do on the success path.

What shouldn't handle orphaned spans?

As this is related to bugs, no assumptions can be made about span count etc. For example, one span context can result in many calls to this handler, unrelated to the actual operation performed. Handlers that redact or clean data work for normal spans and orphans. However, aggregation handlers, such as dependency linkers or success/fail counters, can create problems if used against orphaned spans.

Implementation

By default, this method returns false, suggesting the implementation is not designed to also process orphans. Return true to indicate otherwise. Whichever choice should be constant. In other words do not sometimes return false and other times true, as the value is only read once.

Considerations for implementing handle

When this method returns true, the handle method is both invoked for normal spans and also orphaned ones. The following apply when handling orphans:

The TraceContext parameter contains minimal information, including lookup ids (traceId, spanId and localRootId) and sampling status. "extra" will be empty.

The MutableSpan parameter includes the annotation "brave.flush", and whatever state was orphaned (ex a tag).

Overrides:

supportsOrphans in class FinishedSpanHandler

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object