Class TraceContextOrSamplingFlags
public final class TraceContextOrSamplingFlags extends Object
Tracer.nextSpan(TraceContextOrSamplingFlags)
.
Users should not create instances of this, rather use TraceContext.Extractor
provided
by a Propagation
implementation such as Propagation.B3_STRING
.
Those implementing Propagation
should use the following advice:
- If you have the trace and span ID, use
create(TraceContext)
- If you have only a trace ID, use
create(TraceIdContext)
- Otherwise, use
create(SamplingFlags)
If your propagation implementation needs additional state, append it via TraceContextOrSamplingFlags.Builder.addExtra(Object)
.
This started as a port of com.github.kristofa.brave.TraceData
, which served the same
purpose.
- Since:
- 4.0
- See Also:
TraceContext.Extractor
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
TraceContextOrSamplingFlags.Builder
-
Field Summary
Fields Modifier and Type Field Description static TraceContextOrSamplingFlags
DEBUG
static TraceContextOrSamplingFlags
EMPTY
static TraceContextOrSamplingFlags
NOT_SAMPLED
static TraceContextOrSamplingFlags
SAMPLED
-
Method Summary
-
Field Details
-
Method Details
-
create
Used to implementTraceContext.Extractor.extract(Object)
for a format that can extract a completeTraceContext
, including a trace ID and span ID.- Since:
- 4.3
- See Also:
context()
,newBuilder(TraceContext)
,TraceContext.Extractor.extract(Object)
-
create
Used to implementTraceContext.Extractor.extract(Object)
when the format allows extracting a trace ID without a span ID- Since:
- 4.9
- See Also:
traceIdContext()
,newBuilder(TraceIdContext)
,TraceContext.Extractor.extract(Object)
-
create
Used to implementTraceContext.Extractor.extract(Object)
when the format allows extracting only sampling flags.- Since:
- 4.3
- See Also:
samplingFlags()
,newBuilder(TraceIdContext)
,TraceContext.Extractor.extract(Object)
-
newBuilder
Use when implementingTraceContext.Extractor.extract(Object)
requiresTraceContextOrSamplingFlags.Builder.sampledLocal()
orTraceContextOrSamplingFlags.Builder.addExtra(Object)
. Otherwise, usecreate(TraceContext)
as it is more efficient.- Since:
- 5.12
- See Also:
create(TraceContext)
,TraceContext.Extractor.extract(Object)
-
newBuilder
Use when implementingTraceContext.Extractor.extract(Object)
requiresTraceContextOrSamplingFlags.Builder.sampledLocal()
orTraceContextOrSamplingFlags.Builder.addExtra(Object)
. Otherwise, usecreate(TraceIdContext)
as it is more efficient.- Since:
- 5.12
- See Also:
create(TraceIdContext)
,TraceContext.Extractor.extract(Object)
-
newBuilder
Use when implementingTraceContext.Extractor.extract(Object)
requiresTraceContextOrSamplingFlags.Builder.sampledLocal()
orTraceContextOrSamplingFlags.Builder.addExtra(Object)
. Otherwise, usecreate(SamplingFlags)
as it is more efficient.- Since:
- 5.12
- See Also:
create(SamplingFlags)
,TraceContext.Extractor.extract(Object)
-
newBuilder
Deprecated. -
sampled
ReturnsSamplingFlags.sampled()
, regardless of subtype. -
sampledLocal
public final boolean sampledLocal()ReturnsSamplingFlags.sampledLocal()
, regardless of subtype. -
sampled
Deprecated.do not use object variant.. only set when you have a sampling decision -
sampled
This is used to apply aSamplerFunction
decision with least overhead. Ex.Boolean sampled = extracted.sampled(); // only recreate the context if the messaging sampler made a decision if (sampled == null && (sampled = sampler.trySample(request)) != null) { extracted = extracted.sampled(sampled.booleanValue()); }
- Parameters:
sampled
- decision to apply- Returns:
this
unlesssampled()
differs from the input.- Since:
- 5.2
-
context
Returns non-null
when both a trace ID and span ID wereextracted
from a request.For example, given the header "b3: 80f198ee56343ba864fe8b2a57d3eff7-e457b5a2e4d86bd1-1",
B3Propagation
extracts the following:TraceContext.traceIdString()
: "80f198ee56343ba864fe8b2a57d3eff7"TraceContext.spanIdString()
: "e457b5a2e4d86bd1"SamplingFlags.sampled()
:true
- Returns:
- the trace context when
traceIdContext()
()} andsamplingFlags()
are notnull
- Since:
- 4.0
- See Also:
create(TraceContext)
,newBuilder(TraceContext)
-
traceIdContext
Returns non-null
when a trace ID wasextracted
from a request, but a span ID was not.For example, given the header "x-amzn-trace-id: Root=1-5759e988-bd862e3fe1be46a994272793", AWSPropagation extracts the following:
TraceIdContext.traceIdString()
: "15759e988bd862e3fe1be46a994272793"SamplingFlags.sampled()
:null
- Returns:
- the trace ID context when
context()
andsamplingFlags()
are notnull
- Since:
- 4.9
- See Also:
create(TraceIdContext)
,newBuilder(TraceIdContext)
-
samplingFlags
Returns non-null
when a trace ID was notextracted
from a request.For example, given the header "b3: 1",
B3Propagation
extractsSAMPLED
.- Returns:
- sampling flags when
context()
andtraceIdContext()
are notnull
- Since:
- 4.9
- See Also:
create(SamplingFlags)
,newBuilder(SamplingFlags)
-
extra
Returns a list of additional state extracted from the request. Will be non-empty whencontext()
isnull
.- Since:
- 4.9
- See Also:
TraceContext.extra()
-
toBuilder
- Since:
- 4.9
-
toString
-
create
@Deprecated public static TraceContextOrSamplingFlags create(@Nullable Boolean sampled, boolean debug)Deprecated.Since 5.12, use constants defined on this type as needed. -
equals
-
hashCode
public int hashCode()
-