zipkin2.storage

Class StorageComponent.Builder

java.lang.Object

zipkin2.storage.StorageComponent.Builder

Direct Known Subclasses:

InMemoryStorage.Builder

Enclosing class:

StorageComponent

public abstract static class StorageComponent.Builder
extends Object

Constructor Summary

Constructors

Constructor and Description
Builder()

Method Summary

Modifier and Type	Method and Description
StorageComponent.Builder	autocompleteCardinality(int autocompleteCardinality) How many autocomplete key/value pairs to suppress at a time.
StorageComponent.Builder	autocompleteKeys(List<String> keys) Autocomplete is used by the UI to suggest getValues for site-specific tags, such as environment names.
StorageComponent.Builder	autocompleteTtl(int autocompleteTtl) How long in milliseconds to suppress calls to write the same autocomplete key/value pair.
abstract StorageComponent	build()
abstract StorageComponent.Builder	searchEnabled(boolean searchEnabled) False is an attempt to disable indexing, leaving only SpanStore.getTrace(String) supported.
abstract StorageComponent.Builder	strictTraceId(boolean strictTraceId) Zipkin supports 64 and 128-bit trace identifiers, typically serialized as 16 or 32 character hex strings.

Methods inherited from class java.lang.Object

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

Constructor Detail

Builder

public Builder()

Method Detail

strictTraceId

public abstract StorageComponent.Builder strictTraceId(boolean strictTraceId)

Zipkin supports 64 and 128-bit trace identifiers, typically serialized as 16 or 32 character hex strings. When false, this setting only considers the low 64-bits (right-most 16 characters) of a trace ID when grouping or retrieving traces. This should be set to false while some applications issue 128-bit trace IDs and while other truncate them to 64-bit. If 128-bit trace IDs are not in use, this setting is not required.

Details

Zipkin historically had 64-bit trace IDs, but it now supports 128- bit trace IDs via 32-character hex representation. While instrumentation update to propagate 128-bit IDs, it can be ambiguous whether a 64-bit trace ID was sent intentionally, or as an accident of truncation. This setting allows Zipkin to be usable until application instrumentation are upgraded to support 128-bit trace IDs.

Here are a few trace IDs the help explain this setting.

   
Trace ID A: 463ac35c9f6413ad48485a3953bb6124
   
Trace ID B: 48485a3953bb6124
   
Trace ID C: 463ac35c9f6413adf1a48a8cff464e0e
   
Trace ID D: 463ac35c9f6413ad
 

In the above example, Trace ID A and Trace ID B might mean they are in the same trace, since the lower-64 bits of the IDs are the same. This could happen if a server A created the trace and propagated it to server B which ran an older tracing library. Server B could have truncated the trace ID to lower-64 bits. When strictTraceId == false, spans matching either trace ID A or B would be returned in the same trace when searching by ID A or B. Spans with trace ID C or D wouldn't be when searching by ID A or B because trace IDs C and D don't share lower 64-bits (right-most 16 characters) with trace IDs A or B.

It is also possible that all servers are capable of handling 128-bit trace identifiers, but are configured to only send 64-bit ones. In this case, if strictTraceId == false trace ID A and B would clash and be put into the same trace, causing confusion. Moreover, there is overhead associated with indexing spans both by 64 and 128-bit trace IDs. When a site has finished upgrading to 128-bit trace IDs, they should enable this setting.

See https://github.com/openzipkin/b3-propagation/issues/6 for the status of known open source libraries on 128-bit trace identifiers.

searchEnabled

public abstract StorageComponent.Builder searchEnabled(boolean searchEnabled)

False is an attempt to disable indexing, leaving only SpanStore.getTrace(String) supported. For example, query requests will be disabled. The use case is typically to support 100% sampled data, or when traces are searched using alternative means such as a logging index.

Refer to implementation docs for the impact of this parameter. Operations that use indexes should return empty as opposed to throwing an exception.

autocompleteKeys

public StorageComponent.Builder autocompleteKeys(List<String> keys)

Autocomplete is used by the UI to suggest getValues for site-specific tags, such as environment names. The getKeys here would appear in span tags. Good choices for autocomplete are limited in cardinality for the same reasons as service and span names. For example, "http.url" would be a bad choice for autocomplete, not just because it isn't site-specific (such as environment would be), but also as there are unlimited getValues due to factors such as unique ids in the path.

Parameters:

keys - controls the span values stored for auto-complete.

autocompleteTtl

public StorageComponent.Builder autocompleteTtl(int autocompleteTtl)

How long in milliseconds to suppress calls to write the same autocomplete key/value pair.

autocompleteCardinality

public StorageComponent.Builder autocompleteCardinality(int autocompleteCardinality)

How many autocomplete key/value pairs to suppress at a time.

build

public abstract StorageComponent build()