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 Superinterfaces:
Builder<T,Tracer>, Supplier<Tracer>
All Known Implementing Classes:
JaegerTracerBuilder
public interface TracerBuilder<T extends TracerBuilder<T>> extends Builder<T,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

    Modifier and Type
    Method
    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.
    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
    registerGlobal(boolean global)
    When enabled, the created instance is also registered as a global tracer.
    T
    serviceName(String name)
    Service name of the traced service.
    <B> B
    unwrap(Class<B> builderClass)
    Access the underlying builder by specific type.

    Methods inherited from interface io.helidon.common.Builder

    build, get, identity, update

  • Method Details

    • 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

    • registerGlobal

      T registerGlobal(boolean global)
      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

      <B> B unwrap(Class<B> builderClass)
      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