Class Tracing.Builder
- java.lang.Object
-
- brave.Tracing.Builder
-
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description Tracing.Builder
addFinishedSpanHandler(FinishedSpanHandler handler)
Deprecated.Since 5.12 add a span handler that implementsSpanHandler.end(TraceContext, MutableSpan, SpanHandler.Cause)
withSpanHandler.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, useZipkinSpanHandler.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 likeSpan.start()
.Tracing.Builder
currentTraceContext(CurrentTraceContext currentTraceContext)
Responsible for implementingTracer.startScopedSpan(String)
,Tracer.currentSpanCustomizer()
,Tracer.currentSpan()
andTracer.withSpanInScope(Span)
.Tracing.Builder
endpoint(zipkin2.Endpoint endpoint)
Deprecated.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, useaddSpanHandler(SpanHandler)
with aZipkinSpanHandler
Tracing.Builder
supportsJoin(boolean supportsJoin)
True means the tracing system supports sharing a span ID between aSpan.Kind.CLIENT
andSpan.Kind.SERVER
span.Tracing.Builder
traceId128Bit(boolean traceId128Bit)
When true, new root spans will have 128-bit trace IDs.Tracing.Builder
trackOrphans()
When true, aSpanHandler
is added that logs the caller which orphaned a span to the category "brave.Tracer" atLevel.FINE
.
-
-
-
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()
-
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.Sets theEndpoint of the local service
being traced.
-
spanReporter
@Deprecated public Tracing.Builder spanReporter(zipkin2.reporter.Reporter<zipkin2.Span> spanReporter)
Deprecated.Since 5.12, useaddSpanHandler(SpanHandler)
with aZipkinSpanHandler
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 likeSpan.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. SeeTracing.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 implementingTracer.startScopedSpan(String)
,Tracer.currentSpanCustomizer()
,Tracer.currentSpan()
andTracer.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 toB3Propagation.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 aSpan.Kind.CLIENT
andSpan.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, useZipkinSpanHandler.Builder.errorTag(Tag)
-
addFinishedSpanHandler
public Tracing.Builder addFinishedSpanHandler(FinishedSpanHandler handler)
Deprecated.Since 5.12 add a span handler that implementsSpanHandler.end(TraceContext, MutableSpan, SpanHandler.Cause)
withSpanHandler.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 ifSpanHandler.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 affectsSamplingFlags.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 abaggage 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, useZipkinSpanHandler.Builder.alwaysReportSpans(boolean)
- Since:
- 5.8
-
trackOrphans
public Tracing.Builder trackOrphans()
When true, aSpanHandler
is added that logs the caller which orphaned a span to the category "brave.Tracer" atLevel.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 atLevel.FINE
. Do not do this in production as tracking orphaned data incurs higher overhead.- Since:
- 5.9
-
build
public Tracing build()
-
-