TracerBuilder (Helidon 1.0.0 API)

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 inheritec from this interface

All Superinterfaces:: Builder<Tracer>, Supplier<Tracer>

All Known Implementing Classes:: ZipkinTracerBuilder

public interface TracerBuilder<T extends TracerBuilder>
extends Builder<Tracer>

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).

Tracer Configuration Options
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

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`T`	`addTracerTag(String key, boolean value)` Tracer level tags that get added to all reported spans.
`T`	`addTracerTag(String key, Number value)` Tracer level tags that get added to all reported spans.
`T`	`addTracerTag(String key, String value)` Tracer level tags that get added to all reported spans.
`default Tracer`	`buildAndRegister()` Build and register as a global tracer.
`T`	`collectorHost(String host)` Host to use to connect to tracing collector.
`T`	`collectorPath(String path)` Path on the collector host to use when sending data to tracing collector.
`T`	`collectorPort(int port)` Port to use to connect to tracing collector.
`T`	`collectorProtocol(String protocol)` Protocol to use (such as `http` or `https`) to connect to tracing collector.
`default T`	`collectorUri(URI uri)` Set the collector URI used for sending tracing data.
`T`	`config(Config config)` Load configuration of tracer from configuration of the application.
`static TracerBuilder<?>`	`create(Config config)` Create a new builder from configuration.
`static TracerBuilder<?>`	`create(String serviceName)` Create a new builder for the service name.
`T`	`enabled(boolean enabled)` When enabled, tracing will be sent.
`T`	`serviceName(String name)` Service name of the traced service.

Methods inherited from interface io.helidon.common.Builder
build, get

- Method Detail
  - create
```
static TracerBuilder<?> create(String serviceName)
```
    Create a new builder for the service name.
    
    Parameters:
    
    serviceName - name of the service using the tracer
    
    Returns:
    
    a new builder instance
  - create
```
static TracerBuilder<?> create(Config config)
```
    Create a new builder from configuration.
    
    Parameters:
    
    config - configuration node to load tracer configuration from
    
    Returns:
    
    a new builder instance
  - serviceName
```
T serviceName(String name)
```
    Service name of the traced service.
    
    Parameters:
    
    name - name of the service using the tracer
    
    Returns:
    
    updated builder instance
  - collectorUri
```
default T collectorUri(URI uri)
```
    Set the collector URI used for sending tracing data.
    Default implementation configures collectorProtocol(String), collectorHost(String), collectorPath(String) and collectorPort(int) if configured in the uri.
    
    Parameters:
    
    uri - the endpoint of the tracing collector
    
    Returns:
    
    updated builder instance
  - collectorProtocol
```
T collectorProtocol(String protocol)
```
    Protocol to use (such as http or https) to connect to tracing collector. Default is defined by each tracing integration.
    
    Parameters:
    
    protocol - protocol to use
    
    Returns:
    
    updated builder instance
  - collectorPort
```
T collectorPort(int port)
```
    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
```
T collectorHost(String host)
```
    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
```
T collectorPath(String path)
```
    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
```
T addTracerTag(String key,
               String value)
```
    Tracer level tags that get added to all reported spans.
    
    Parameters:
    
    key - name of the tag
    
    value - value of the tag
    
    Returns:
    
    updated builder instance
  - addTracerTag
```
T addTracerTag(String key,
               Number value)
```
    Tracer level tags that get added to all reported spans.
    
    Parameters:
    
    key - name of the tag
    
    value - numeric value of the tag
    
    Returns:
    
    updated builder instance
  - addTracerTag
```
T addTracerTag(String key,
               boolean value)
```
    Tracer level tags that get added to all reported spans.
    
    Parameters:
    
    key - name of the tag
    
    value - boolean value of the tag
    
    Returns:
    
    updated builder instance
  - config
```
T config(Config 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
```
T enabled(boolean enabled)
```
    When enabled, tracing will be sent. If enabled is false, tracing should use a no-op tracer.
    
    Parameters:
    
    enabled - set to false to disable distributed tracing
    
    Returns:
    
    updated builder instance
  - buildAndRegister
```
default Tracer buildAndRegister()
```
    Build and register as a global tracer.
    
    Returns:
    
    The Tracer built and registered

Interface TracerBuilder<T extends TracerBuilder>

Method Summary

Methods inherited from interface io.helidon.common.Builder

Method Detail

create

create

serviceName

collectorUri

collectorProtocol

collectorPort

collectorHost

collectorPath

addTracerTag

addTracerTag

addTracerTag

config

enabled

buildAndRegister