Module io.helidon.tracing
Package io.helidon.tracing

Interface TracerBuilder<T extends TracerBuilder>

  • 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<Tracer>, Supplier<Tracer>
    All Known Implementing Classes:
    JaegerTracerBuilder, 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 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

      • 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