///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

///////////////////////////////////////////////////////////////////////////////

= Jaeger Tracing
:description: Helidon Tracing Support
:keywords: helidon, tracing, jaeger

Helidon is integrated with the Jaeger tracer.

The Jaeger builder is loaded through `ServiceLoader` and configured. You could
also use the Jaeger builder directly, though this would create a source-code dependency
on the Jaeger tracer.


== Prerequisites
To use Jaeger as a tracer,
    add the following dependency to your project:

[source,xml]
----
<dependency>
    <groupId>io.helidon.tracing</groupId>
    <artifactId>helidon-tracing-jaeger</artifactId>
</dependency>
----

== Configuring Jaeger

The Jaeger tracer supports the following configuration options:

|===
|Key            |Default value      |Builder method     |Description

|service        |N/A                |serviceName        |Name of the service, to distinguish traces crossing service boundaries;
                                                            Jaeger is using lower-case only, name will be automatically lower-cased
|protocol       |http               |collectorProtocol  |Protocol of the Jaeger trace collector (`udp`, `http` or `https`), to switch
                                                            to agent mode, use `udp`
|host           |localhost          |collectorHost      |Host of the Jaeger trace collector (IP Address, hostname, or FQDN)
|port           |14268              |collectorPort      |Port of the Jaeger trace collector
|path           |/api/traces        |collectorPath      |Path of the Jaeger trace collector
|token          |N/A                |token              |Authentication token to use (token authentication)
|username       |N/A                |username           |User to authenticate (basic authentication)
|password       |N/A                |password           |Password of the user to authenticate (basic authentication)
|propagation    |library default    |addPropagation     |Propagation type (`jaeger` or `b3`)
|log-spans      |library default    |logSpans           |Whether to log spans (boolean)
|max-queue-size |library default    |maxQueueSize       |Maximal queue size of the reporter (int)
|flush-interval-ms|library default  |flushInterval      |Reporter flush interval in milliseconds
|sampler-type   |library default    |samplerType        |Sampler type (`probabilistic`, `ratelimiting`, `remote`)
|sampler-param  |library default    |samplerParam       |Numeric parameter specifying details for the sampler type
|sampler-manager|library default    |samplerManager     |Host and port of the sampler manager for `remote` type
|enabled        |true               |enabled            |If set to false, tracing would be disabled
|tags           |N/A                |addTracerTag(String, String) |`String` tags to add to each span
|boolean-tags   |N/A                |addTracerTag(String, boolean)|`boolean` tags to add to each span
|int-tags       |N/A                |addTracerTag(String, int)    |`int` tags to add to each span
|===

The following is an example of a Jaeger configuration, specified in the YAML format.
[source,yaml]
----
tracing:
    service: "helidon-full-http"
    protocol: "https"     # JAEGER_ENDPOINT (if not udp, http is expected and endpoint is filled)
    host: "192.168.1.3"   # JAEGER_ENDPOINT
    port: 14240           # JAEGER_ENDPOINT
    path: "/api/traces/mine"   # JAEGER_ENDPOINT
    token: "token"        # JAEGER_AUTH_TOKEN
    # Either token or username/password
    #username:  "user"     # JAEGER_USER
    #password: "pass"      # JAEGER_PASSWORD
    propagation: "jaeger" # JAEGER_PROPAGATION either "jaeger" or "b3"
    log-spans: false      # JAEGER_REPORTER_LOG_SPANS
    max-queue-size: 42    # JAEGER_REPORTER_MAX_QUEUE_SIZE
    flush-interval-ms: 10001 # JAEGER_REPORTER_FLUSH_INTERVAL
    sampler-type: "remote"# JAEGER_SAMPLER_TYPE (https://www.jaegertracing.io/docs/latest/sampling/#client-sampling-configuration)
    sampler-param: 0.5    # JAEGER_SAMPLER_PARAM (number)
    sampler-manager: "localhost:47877" # JAEGER_SAMPLER_MANAGER_HOST_PORT
    tags:
      tag1: "tag1-value"  # JAEGER_TAGS
      tag2: "tag2-value"  # JAEGER_TAGS
    boolean-tags:
      tag3: true          # JAEGER_TAGS
      tag4: false         # JAEGER_TAGS
    int-tags:
      tag5: 145           # JAEGER_TAGS
      tag6: 741           # JAEGER_TAGS
----

