Class 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)
Similar tospanReporter(Reporter)
except it can read the trace context and create more efficient or completely different data structures.Tracing.Builder
alwaysReportSpans()
When true, all spanssampled locally
are reported to thespan reporter
, even if they aren't sampled remotely.Tracing
build()
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)
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)
Lower-case 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.Tracing.Builder
spanReporter(zipkin2.reporter.Reporter<zipkin2.Span> spanReporter)
Controls how spans are reported.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, this logs the caller which orphaned a span to the category "brave.Tracer" atLevel.FINE
.
-
Method Details
-
localServiceName
Lower-case 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
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
The primary listen port associated with this service. No default.- Since:
- 5.2
- See Also:
localIp(String)
-
endpoint
Deprecated.Sets theEndpoint of the local service
being traced. -
spanReporter
Controls how spans are reported. Defaults to logging, but often anAsyncReporter
which batches spans before sending to Zipkin. TheAsyncReporter
includes aSender
, which is a driver for transports like http, kafka and scribe.For example, here's how to batch send spans via http:
spanReporter = AsyncReporter.create(URLConnectionSender.create("http://localhost:9411/api/v2/spans")); tracingBuilder.spanReporter(spanReporter);
See https://github.com/apache/incubator-zipkin-reporter-java
-
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
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
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
Controls how trace contexts are injected or extracted from remote requests, such as from http headers. Defaults toB3Propagation.FACTORY
-
traceId128Bit
When true, new root spans will have 128-bit trace IDs. Defaults to false (64-bit) -
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
-
addFinishedSpanHandler
Similar tospanReporter(Reporter)
except it can read the trace context and create more efficient or completely different data structures. Importantly, the input is mutable for customization purposes.These handlers execute before the
span reporter
, which means any mutations occur prior to Zipkin.Advanced notes
This is named firehose as it can receive data even when spans are not sampled remotely. For example,
FinishedSpanHandler.alwaysSampleLocal()
will generate data for all traced requests while not affecting headers. This setting is often used for metrics aggregation.Your handler can also be a custom span transport. When this is the case, set the
span reporter
toReporter.NOOP
to avoid redundant conversion overhead.- Parameters:
handler
- skipped ifFinishedSpanHandler.NOOP
or already added- See Also:
alwaysReportSpans()
,SamplingFlags.sampledLocal()
-
alwaysReportSpans
When true, all spanssampled locally
are reported to thespan reporter
, even if they aren't sampled remotely. Defaults to false.The 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 an
extra field
. This means that data will report when either the trace is normally sampled, or secondarily sampled via a custom header.This is simpler than
addFinishedSpanHandler(FinishedSpanHandler)
, because you don't have to duplicate transport mechanics already implemented in thespan reporter
. However, 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.8
- See Also:
addFinishedSpanHandler(FinishedSpanHandler)
,SamplingFlags.sampledLocal()
-
trackOrphans
When true, this 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
- See Also:
FinishedSpanHandler.supportsOrphans()
-
build
-