com.lightstep.tracer.shared

Class Options.OptionsBuilder

java.lang.Object

com.lightstep.tracer.shared.Options.OptionsBuilder

Enclosing class:

Options

public static class Options.OptionsBuilder
extends Object

Constructor Summary

Constructors

Constructor and Description
OptionsBuilder()
OptionsBuilder(Options options)

Method Summary

Modifier and Type	Method and Description
Options	build() Sets the defaults for values not provided and constructs a new Options object.
Options.OptionsBuilder	withAccessToken(String accessToken) Sets the unique identifier for this application.
Options.OptionsBuilder	withClockSkewCorrection(boolean clockCorrection)
Options.OptionsBuilder	withCollectorClient(Options.CollectorClient collectorClient) Sets the collector client explicitly.
Options.OptionsBuilder	withCollectorHost(String collectorHost) Sets the host to which the tracer will send data.
Options.OptionsBuilder	withCollectorPort(int collectorPort) Sets the port to which the tracer will send data.
Options.OptionsBuilder	withCollectorProtocol(String protocol) Sets the protocol which will be used when sending data to the tracer.
Options.OptionsBuilder	withComponentName(String name) Sets the component name attribute.
Options.OptionsBuilder	withDeadlineMillis(long deadlineMillis) Overrides the default deadlineMillis with the provided value.
Options.OptionsBuilder	withDisableMetaEventLogging(boolean disableMetaEventLogging) Disables LightStep Meta Event Reporting even if a server command requested it.
Options.OptionsBuilder	withDisableMetricsReporting(boolean disable) If true, metrics reporting will be disabled.
Options.OptionsBuilder	withDisableReportingLoop(boolean disable) If true, the background reporting loop will be disabled.
Options.OptionsBuilder	withDropSpansOnFailure(boolean dropSpansOnFailure) Instructs the Tracer to either to drop Spans for failed requests or else do a best effort to keep them in the current buffer.
Options.OptionsBuilder	withGrpcCollectorTarget(String grpcCollectorTarget) Sets the target address when using gRPC for transport.
Options.OptionsBuilder	withGrpcRoundRobin(boolean grpcRoundRobin) Instructs gRPC to round-robin between satellites instances in a pool when sending traces.
Options.OptionsBuilder	withHostname(String hostname) Sets the hostname.
Options.OptionsBuilder	withMaxBufferedSpans(int maxBufferedSpans) Sets the maximum number of finished Spans buffered locally before flushing.
Options.OptionsBuilder	withMaxReportingIntervalMillis(int maxReportingIntervalMillis) Sets the maximum interval between reports.
Options.OptionsBuilder	withMetricsUrl(String metricsUrl) Uses the specified value as the metrics collector url.
Options.OptionsBuilder	withOkHttpDns(Options.OkHttpDns okhttpDns) Sets the DNS service used to lookup IP addresses for hostnames when using the OkHttp transport.
<T> Options.OptionsBuilder	withPropagator(io.opentracing.propagation.Format<T> format, Propagator propagator) Adds a user defined Propagator to be used during Tracer.inject(io.opentracing.SpanContext, io.opentracing.propagation.Format<C>, C) and Tracer.extract(io.opentracing.propagation.Format<C>, C) for the given type.
Options.OptionsBuilder	withResetClient(boolean reset) If true, the GRPC client connection will be reset at regular intevals Used to load balance on server side
Options.OptionsBuilder	withResetSpansOnConsecutiveFailures(int resetSpansOnConsecutiveFailures) Instructs the Tracer to reset the span buffer after n-number of consecutive failures retryng unsuccesful requests.
Options.OptionsBuilder	withScopeManager(io.opentracing.ScopeManager scopeManager) Sets scope manager attribute.
Options.OptionsBuilder	withServiceVersion(String serviceVersion) Sets the service version.
Options.OptionsBuilder	withTag(String key, Object value) Sets a user-defined key-value pair that should be associated with all of the data produced by this tracer.
Options.OptionsBuilder	withVerbosity(int verbosity) Controls the amount of local output produced by the tracer.

Methods inherited from class java.lang.Object

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

Constructor Detail

OptionsBuilder

public OptionsBuilder()

OptionsBuilder

public OptionsBuilder(Options options)

Method Detail

withDropSpansOnFailure

public Options.OptionsBuilder withDropSpansOnFailure(boolean dropSpansOnFailure)

Instructs the Tracer to either to drop Spans for failed requests or else do a best effort to keep them in the current buffer. Defaults to true.

Parameters:

dropSpansOnFailure - whether the tracer should drop spans for failed requests.

withResetSpansOnConsecutiveFailures

public Options.OptionsBuilder withResetSpansOnConsecutiveFailures(int resetSpansOnConsecutiveFailures)

Instructs the Tracer to reset the span buffer after n-number of consecutive failures retryng unsuccesful requests. This is done to avoid memory/cpu pressure on excessive consecutive errors. Defaults to -1, which is interpreted as infinite.

Parameters:

resetSpansOnConsecutiveFailures - number of failed consecutuve requests before span is reset.

withPropagator

public <T> Options.OptionsBuilder withPropagator(io.opentracing.propagation.Format<T> format,
                                                 Propagator propagator)

Adds a user defined Propagator to be used during Tracer.inject(io.opentracing.SpanContext, io.opentracing.propagation.Format<C>, C) and Tracer.extract(io.opentracing.propagation.Format<C>, C) for the given type. This can be used to provide custom handling for a specified Format (such as Format.Builtin#TEXT_MAP). Propagator.inject(com.lightstep.tracer.shared.SpanContext, C) and Propagator.extract(C) are expected to fail silently in case of error during injection and extraction, respectively. Observe that a new Format should *not* be created if the data is being propagated through http headers or a text map. Instead, use the respective builtin Format and specify a custom Propagator here. In case of doubt, contact LightStep for advice.

Type Parameters:

T - Type of the carrier.

Parameters:

format - Instance of Format for which custom Propagator will be used.

propagator - Instance of Propagator to be used

withAccessToken

public Options.OptionsBuilder withAccessToken(String accessToken)

Sets the unique identifier for this application.

Parameters:

accessToken - Your specific token for LightStep access.

withServiceVersion

public Options.OptionsBuilder withServiceVersion(String serviceVersion)

Sets the service version.

withHostname

public Options.OptionsBuilder withHostname(String hostname)

Sets the hostname. If not set, will default to the InetAddress.getLocalHost().getHostName().

Parameters:

hostname - hostname

withCollectorProtocol

public Options.OptionsBuilder withCollectorProtocol(String protocol)

Sets the protocol which will be used when sending data to the tracer. Valid values are either LightStepConstants.Collector.PROTOCOL_HTTPS or LightStepConstants.Collector.PROTOCOL_HTTP.

Parameters:

protocol - Either PROTOCOL_HTTPS or PROTOCOL_HTTP.

Throws:

IllegalArgumentException - If the protocol argument is invalid.

withCollectorHost

public Options.OptionsBuilder withCollectorHost(String collectorHost)

Sets the host to which the tracer will send data. If not set, will default to the primary LightStep collector address.

Parameters:

collectorHost - The hostname for the LightStep collector.

Throws:

IllegalArgumentException - If the collectorHost argument is invalid.

withCollectorPort

public Options.OptionsBuilder withCollectorPort(int collectorPort)

Sets the port to which the tracer will send data. If not set, will default to LightStepConstants.Collector.DEFAULT_SECURE_PORT when the protocol is https and LightStepConstants.Collector.DEFAULT_PLAINTEXT_PORT when the protocol is http.

Parameters:

collectorPort - The port for the LightStep collector.

Throws:

IllegalArgumentException - If the collectorPort is invalid.

withCollectorClient

public Options.OptionsBuilder withCollectorClient(Options.CollectorClient collectorClient)

Sets the collector client explicitly. If not set, will default to the collector client which is found in the classpath.

Parameters:

collectorClient - The collector client to use

withGrpcCollectorTarget

public Options.OptionsBuilder withGrpcCollectorTarget(String grpcCollectorTarget)

Sets the target address when using gRPC for transport. Useful when used in conjunction with supplying a custom gRPC NameResolverProvider to lookup the satellites via your preferred service discovery system.

Parameters:

grpcCollectorTarget - The target URI for the LightStep collector.

Throws:

IllegalArgumentException - If the grpcCollectorTarget is invalid.

withGrpcRoundRobin

public Options.OptionsBuilder withGrpcRoundRobin(boolean grpcRoundRobin)

Instructs gRPC to round-robin between satellites instances in a pool when sending traces. If not enabled defaults to picking the first record returned by the operating system resolver.

Parameters:

grpcRoundRobin - Use round robin on a per request basis when sending requests to the satellites.

withOkHttpDns

public Options.OptionsBuilder withOkHttpDns(Options.OkHttpDns okhttpDns)

Sets the DNS service used to lookup IP addresses for hostnames when using the OkHttp transport. If not set, the default DNS service used by OkHttp will be used.

This has no effect when using gRPC as transport system.

Parameters:

okhttpDns - the Dns service object.

withScopeManager

public Options.OptionsBuilder withScopeManager(io.opentracing.ScopeManager scopeManager)

Sets scope manager attribute. If not set, will default to the ThreadLocalScopeManager

Parameters:

scopeManager - The scopeManager for the LightStep tracer.

Throws:

IllegalArgumentException - If the scopeManager is null.

withComponentName

public Options.OptionsBuilder withComponentName(String name)

Sets the component name attribute. If not set, will default to the Java runtime command.

Parameters:

name - The name of the component being traced.

withTag

public Options.OptionsBuilder withTag(String key,
                                      Object value)

Sets a user-defined key-value pair that should be associated with all of the data produced by this tracer.

withMaxReportingIntervalMillis

public Options.OptionsBuilder withMaxReportingIntervalMillis(int maxReportingIntervalMillis)

Sets the maximum interval between reports.

Parameters:

maxReportingIntervalMillis - The maximum interval of time that will pass between reports.

withMaxBufferedSpans

public Options.OptionsBuilder withMaxBufferedSpans(int maxBufferedSpans)

Sets the maximum number of finished Spans buffered locally before flushing. This is a protective mechanism which bounds the memory usage of the LightStep library.

Parameters:

maxBufferedSpans - The maximum number of Spans buffered locally.

withVerbosity

public Options.OptionsBuilder withVerbosity(int verbosity)

Controls the amount of local output produced by the tracer. It does not affect which spans are sent to the collector. It is useful for diagnosing problems in the tracer itself. The default value is 1. 0 - never produce local output 1 - only the first error encountered will be echoed locally 2 - all errors are echoed locally 3 - all errors, warnings, and info statements are echoed locally 4 - all internal log statements, including debugging details

withDisableReportingLoop

public Options.OptionsBuilder withDisableReportingLoop(boolean disable)

If true, the background reporting loop will be disabled. Reports will only occur on explicit calls to Flush(); If not set, will default to DEFAULT_REPORTING_INTERVAL_MILLIS.

withResetClient

public Options.OptionsBuilder withResetClient(boolean reset)

If true, the GRPC client connection will be reset at regular intevals Used to load balance on server side

withDeadlineMillis

public Options.OptionsBuilder withDeadlineMillis(long deadlineMillis)

Overrides the default deadlineMillis with the provided value.

withMetricsUrl

public Options.OptionsBuilder withMetricsUrl(String metricsUrl)

Uses the specified value as the metrics collector url.

withDisableMetricsReporting

public Options.OptionsBuilder withDisableMetricsReporting(boolean disable)

If true, metrics reporting will be disabled. Default is false.

withDisableMetaEventLogging

public Options.OptionsBuilder withDisableMetaEventLogging(boolean disableMetaEventLogging)

Disables LightStep Meta Event Reporting even if a server command requested it.

Parameters:

disableMetaEventLogging -

withClockSkewCorrection

public Options.OptionsBuilder withClockSkewCorrection(boolean clockCorrection)

build

public Options build()
              throws MalformedURLException

Sets the defaults for values not provided and constructs a new Options object.

Returns:

Options object configured with the built values.

Throws:

MalformedURLException - If the combination of collector protocol, host, and port are not valid