Package brave

Class Tracing.Builder

java.lang.Object

brave.Tracing.Builder

Enclosing class:

Tracing

public static final class Tracing.Builder
extends Object

Method Summary

Modifier and Type	Method	Description
Tracing.Builder	addFinishedSpanHandler(FinishedSpanHandler handler)	Deprecated. Since 5.12 add a span handler that implements SpanHandler.end(TraceContext, MutableSpan, SpanHandler.Cause) with SpanHandler.Cause.FINISHED
Tracing.Builder	addSpanHandler(SpanHandler spanHandler)	Inputs receive {code (context, span)} pairs for every locally sampled span.
Tracing.Builder	alwaysReportSpans()	Deprecated. Since 5.12, use ZipkinSpanHandler.Builder.alwaysReportSpans(boolean)
Tracing.Builder	alwaysSampleLocal()	When true, all spans become real spans even if they aren't sampled remotely.
Tracing	build()
Tracing.Builder	clearSpanHandlers()	Clears all span handlers.
Tracing.Builder	clock(Clock clock)	Assigns microsecond-resolution timestamp source for operations like Span.start().
Tracing.Builder	currentTraceContext(CurrentTraceContext currentTraceContext)	Responsible for implementing Tracer.startScopedSpan(String), Tracer.currentSpanCustomizer(), Tracer.currentSpan() and Tracer.withSpanInScope(Span).
Tracing.Builder	endpoint(zipkin2.Endpoint endpoint)	Deprecated. Use localServiceName(String) localIp(String) and localPort(int).
Tracing.Builder	errorParser(ErrorParser errorParser)	Deprecated. This is only used in Zipkin reporting.
Tracing.Builder	localIp(String localIp)	The text representation of the primary IP address associated with this service.
Tracing.Builder	localPort(int localPort)	The primary listen port associated with this service.
Tracing.Builder	localServiceName(String localServiceName)	Label of the remote node in the service graph, such as "favstar".
Tracing.Builder	propagationFactory(Propagation.Factory propagationFactory)	Controls how trace contexts are injected or extracted from remote requests, such as from http headers.
Tracing.Builder	sampler(Sampler sampler)	Sampler is responsible for deciding if a particular trace should be "sampled", i.e.
Set<SpanHandler>	spanHandlers()	Returns an immutable copy of the current span handlers.
Tracing.Builder	spanReporter(zipkin2.reporter.Reporter<zipkin2.Span> spanReporter)	Deprecated. Since 5.12, use addSpanHandler(SpanHandler) with a ZipkinSpanHandler
Tracing.Builder	supportsJoin(boolean supportsJoin)	True means the tracing system supports sharing a span ID between a Span.Kind.CLIENT and Span.Kind.SERVER span.
Tracing.Builder	traceId128Bit(boolean traceId128Bit)	When true, new root spans will have 128-bit trace IDs.
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.

Methods inherited from class java.lang.Object

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

Method Details

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()

clearSpanHandlers

public Tracing.Builder clearSpanHandlers()

Clears all span handlers. This allows those who can't create the builder to reconfigure or re-order them.

Since:

5.12

See Also:

spanHandlers(), TracingCustomizer

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)

localIp

public Tracing.Builder localIp(String localIp)

The text representation of the primary IP address associated with this service. Ex. 192.168.99.100 or 2001:db8::c001. Defaults to a link local IP.

Since:

5.2

See Also:

localServiceName(String), localPort(int)

localPort

public Tracing.Builder localPort(int localPort)

The primary listen port associated with this service. No default.

Since:

5.2

See Also:

localIp(String)

endpoint

@Deprecated public Tracing.Builder endpoint(zipkin2.Endpoint endpoint)

Deprecated.

Use localServiceName(String) localIp(String) and localPort(int). Will be removed in Brave v6.

Sets the Endpoint of the local service being traced.

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

currentTraceContext

public Tracing.Builder currentTraceContext(CurrentTraceContext currentTraceContext)

Responsible for implementing Tracer.startScopedSpan(String), Tracer.currentSpanCustomizer(), Tracer.currentSpan() and Tracer.withSpanInScope(Span).

By default a simple thread-local is used. Override to support other mechanisms or to synchronize with other mechanisms such as SLF4J's MDC.

propagationFactory

public Tracing.Builder propagationFactory(Propagation.Factory propagationFactory)

Controls how trace contexts are injected or extracted from remote requests, such as from http headers. Defaults to B3Propagation.FACTORY

traceId128Bit

public Tracing.Builder traceId128Bit(boolean traceId128Bit)

When true, new root spans will have 128-bit trace IDs. Defaults to false (64-bit)

supportsJoin

public Tracing.Builder supportsJoin(boolean supportsJoin)

True means the tracing system supports sharing a span ID between a Span.Kind.CLIENT and Span.Kind.SERVER span. Defaults to true.

Set this to false when the tracing system requires the opposite. For example, if ultimately spans are sent to Amazon X-Ray or Google Stackdriver Trace, you should set this to false.

This is implicitly set to false when Propagation.Factory.supportsJoin() is false, as in that case, sharing IDs isn't possible anyway.

See Also:

Propagation.Factory.supportsJoin()

errorParser

@Deprecated public Tracing.Builder errorParser(ErrorParser errorParser)

Deprecated.

This is only used in Zipkin reporting. Since 5.12, use ZipkinSpanHandler.Builder.errorTag(Tag)

addFinishedSpanHandler

public Tracing.Builder addFinishedSpanHandler(FinishedSpanHandler handler)

Deprecated.

Since 5.12 add a span handler that implements SpanHandler.end(TraceContext, MutableSpan, SpanHandler.Cause) with SpanHandler.Cause.FINISHED

Since:

5.4

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

build

public Tracing build()