Module io.helidon.tracing
Package io.helidon.tracing
Interface TracerBuilder<T extends TracerBuilder<T>>
- Type Parameters:
T
- type of the builder, used so that inherited builders returned by methods are of the correct type and contain all methods, even those not inherited from this interface
- All Known Implementing Classes:
JaegerTracerBuilder
A builder for tracing
tracer
.
Each tracer implementation may use different options, though these are the common ones.
To keep service implementation abstracted from specific tracer, use config(Config)
to load configuration of the tracer, as that supports externalization of
specific configuration options (e.g. you may use api-version for Zipkin tracer
and sampler-type for Jaeger).
The following table lists common configuration options that must be honored by each integration (if supported by it).
option | description |
---|---|
service |
Name of the service sending the tracing information. This is usually visible in the trace data to distinguish actors in a conversation (e.g. when multiple microservices are connected together) |
protocol |
usually http/https, see collectorProtocol(String) |
host |
host of the collector server, defaults are implementation specific, though
often "localhost" as a docker image is expected, see collectorHost(String) |
port |
port of the collector server, defaults are implementation specific.
See collectorPort(int) |
path |
Path on the collector server used to publish/send span data, defaults are implementation
specific. See collectorPath(String) |
tags |
An object config node containing key/value pairs with tag name and string tag value for
tags shared by all spans. See addTracerTag(String, String) |
boolean-tags |
An object config node containing key/value pairs with tag name and boolean tag value for
tags shared by all spans. See addTracerTag(String, boolean) |
int-tags |
An object config node containing key/value pairs with tag name and integer tag value for
tags shared by all spans. See addTracerTag(String, Number) |
Example:
tracing: # usually must be provided, as it is used as a service identifier service: "basket-service" # host of the collector server - example for zipkin in docker environment # would use default host, port and path host: "zipkin" # example of a tracer-wide tag tags: env: "stage-1"
-
Method Summary
Modifier and TypeMethodDescriptionaddTracerTag
(String key, boolean value) Tracer level tags that get added to all reported spans.addTracerTag
(String key, Number value) Tracer level tags that get added to all reported spans.addTracerTag
(String key, String value) Tracer level tags that get added to all reported spans.collectorHost
(String host) Host to use to connect to tracing collector.collectorPath
(String path) Path on the collector host to use when sending data to tracing collector.collectorPort
(int port) Port to use to connect to tracing collector.collectorProtocol
(String protocol) Protocol to use (such ashttp
orhttps
) to connect to tracing collector.default T
collectorUri
(URI uri) Set the collector URI used for sending tracing data.Load configuration of tracer from configuration of the application.static TracerBuilder
<?> Create a new builder from configuration.static TracerBuilder
<?> Create a new builder for the service name.enabled
(boolean enabled) When enabled, tracing will be sent.registerGlobal
(boolean global) When enabled, the created instance is also registered as a global tracer.serviceName
(String name) Service name of the traced service.<B> B
Access the underlying builder by specific type.
-
Method Details
-
create
Create a new builder for the service name.- Parameters:
serviceName
- name of the service using the tracer- Returns:
- a new builder instance
-
create
Create a new builder from configuration.- Parameters:
config
- configuration node to load tracer configuration from- Returns:
- a new builder instance
-
serviceName
Service name of the traced service.- Parameters:
name
- name of the service using the tracer- Returns:
- updated builder instance
-
collectorUri
Set the collector URI used for sending tracing data.Default implementation configures
collectorProtocol(String)
,collectorHost(String)
,collectorPath(String)
andcollectorPort(int)
if configured in the uri.- Parameters:
uri
- the endpoint of the tracing collector- Returns:
- updated builder instance
-
collectorProtocol
Protocol to use (such ashttp
orhttps
) to connect to tracing collector. Default is defined by each tracing integration.- Parameters:
protocol
- protocol to use- Returns:
- updated builder instance
-
collectorPort
Port to use to connect to tracing collector. Default is defined by each tracing integration.- Parameters:
port
- port to use- Returns:
- updated builder instance
-
collectorHost
Host to use to connect to tracing collector. Default is defined by each tracing integration.- Parameters:
host
- host to use- Returns:
- updated builder instance
-
collectorPath
Path on the collector host to use when sending data to tracing collector. Default is defined by each tracing integration.- Parameters:
path
- path to use- Returns:
- updated builder instance
-
addTracerTag
Tracer level tags that get added to all reported spans.- Parameters:
key
- name of the tagvalue
- value of the tag- Returns:
- updated builder instance
-
addTracerTag
Tracer level tags that get added to all reported spans.- Parameters:
key
- name of the tagvalue
- numeric value of the tag- Returns:
- updated builder instance
-
addTracerTag
Tracer level tags that get added to all reported spans.- Parameters:
key
- name of the tagvalue
- boolean value of the tag- Returns:
- updated builder instance
-
config
Load configuration of tracer from configuration of the application. The configuration keys are specific for each tracer integration and documented in these integration projects.- Parameters:
config
- configuration node of the tracer configuration- Returns:
- updated builder instance
-
enabled
When enabled, tracing will be sent. If enabled is false, tracing should use a no-op tracer.- Parameters:
enabled
- set tofalse
to disable distributed tracing- Returns:
- updated builder instance
-
registerGlobal
When enabled, the created instance is also registered as a global tracer.- Parameters:
global
- whether to register this tracer as a global tracer once built- Returns:
- updated builder instance
-
unwrap
Access the underlying builder by specific type. This is a dangerous operation that will succeed only if the builder contains the expected type. This practically removes abstraction capabilities of this builder.- Type Parameters:
B
- type of the builder- Parameters:
builderClass
- type to access- Returns:
- instance of the builder
- Throws:
IllegalArgumentException
- in case the builder cannot provide the expected type
-