Package brave

Class Tracing.Builder

  • Enclosing class:
    Tracing
    public static final class Tracing.Builder
extends Object

    • Method Detail

      • spanHandlers

        public Set<SpanHandler> spanHandlers()
        Returns an immutable copy of the current span handlers. This allows those who can't create the builder to reconfigure or re-order them.
        Since:
        5.12
        See Also:
        clearSpanHandlers()

      • localServiceName

        public Tracing.Builder localServiceName​(String localServiceName)
        Label of the remote node in the service graph, such as "favstar". Avoid names with variables or unique identifiers embedded. Defaults to "unknown".

        This is a primary label for trace lookup and aggregation, so it should be intuitive and consistent. Many use a name from service discovery.

        See Also:
        localIp(String)

      • localPort

        public Tracing.Builder localPort​(int localPort)
        The primary listen port associated with this service. No default.
        Since:
        5.2
        See Also:
        localIp(String)

      • spanReporter

        @Deprecated
public Tracing.Builder spanReporter​(zipkin2.reporter.Reporter<zipkin2.Span> spanReporter)
        Deprecated.
        Since 5.12, use addSpanHandler(SpanHandler) with a ZipkinSpanHandler

        Since 5.12, this is deprecated for using ZipkinSpanHandler in the io.zipkin.reporter2:zipkin-reporter-brave library.

        For example, here's how to batch send spans via HTTP to a Zipkin-compatible endpoint: 

        
 // Configure a reporter, which controls how often spans are sent
 //   (this dependency is io.zipkin.reporter2:zipkin-sender-okhttp3)
 sender = OkHttpSender.create("http://127.0.0.1:9411/api/v2/spans");
 //   (this dependency is io.zipkin.reporter2:zipkin-reporter-brave)
 zipkinSpanHandler = AsyncZipkinSpanHandler.create(sender); // don't forget to close!

 // Create a tracing component with the service name you want to see in Zipkin.
 tracing = Tracing.newBuilder()
                  .localServiceName("my-service")
                  .addSpanHandler(zipkinSpanHandler)
                  .build();
        See Also:
        addSpanHandler(SpanHandler)

      • clock

        public Tracing.Builder clock​(Clock clock)
        Assigns microsecond-resolution timestamp source for operations like Span.start(). Defaults to JRE-specific platform time.

        Note: timestamps are read once per trace, then ticks thereafter. This ensures there's no clock skew problems inside a single trace. See Tracing.clock(TraceContext)

      • sampler

        public Tracing.Builder sampler​(Sampler sampler)
        Sampler is responsible for deciding if a particular trace should be "sampled", i.e. whether the overhead of tracing will occur and/or if a trace will be reported to Zipkin.
        See Also:
        for temporary overrides

      • traceId128Bit

        public Tracing.Builder traceId128Bit​(boolean traceId128Bit)
        When true, new root spans will have 128-bit trace IDs. Defaults to false (64-bit)

      • errorParser

        @Deprecated
public Tracing.Builder errorParser​(ErrorParser errorParser)
        Deprecated.
        This is only used in Zipkin reporting. Since 5.12, use ZipkinSpanHandler.Builder.errorTag(Tag)

      • addSpanHandler

        public Tracing.Builder addSpanHandler​(SpanHandler spanHandler)
        Inputs receive {code (context, span)} pairs for every locally sampled span. The span is mutable for customization or redaction purposes. Span handlers execute in order: If any handler returns {code false}, the next will not see the span.
        Parameters:
        spanHandler - skipped if SpanHandler.NOOP or already added
        Since:
        5.12

      • alwaysSampleLocal

        public Tracing.Builder alwaysSampleLocal()
        When true, all spans become real spans even if they aren't sampled remotely. This allows span handlers (such as metrics) to consider attributes that are not always visible before-the-fact, such as http paths. Defaults to false and affects SamplingFlags.sampledLocal().

        Advanced example: Secondary Sampling

        Besides metrics, another primary use case is to implement a sampling overlay, such as boosting the sample rate for a subset of the network depending on the value of a baggage field. A handler like this will report when either the trace is normally sampled, or secondarily sampled via a custom header. This assumes your backend can properly process the partial traces implied when using conditional sampling. For example, if your sampling condition is not consistent on a call tree, the resulting data could appear broken.
        Since:
        5.12
        See Also:
        addSpanHandler(SpanHandler), SamplingFlags.sampledLocal()

      • alwaysReportSpans

        public Tracing.Builder alwaysReportSpans()
        Deprecated.
        Since 5.12, use ZipkinSpanHandler.Builder.alwaysReportSpans(boolean)
        Since:
        5.8

      • trackOrphans

        public Tracing.Builder trackOrphans()
        When true, a SpanHandler is added that logs the caller which orphaned a span to the category "brave.Tracer" at Level.FINE. Defaults to false.

        If you see data with the annotation "brave.flush", you may have an instrumentation bug. To see which code was involved, set this and ensure the logger Tracing is at Level.FINE. Do not do this in production as tracking orphaned data incurs higher overhead.

        Since:
        5.9