Skip to main content

Jaeger

note

Echo community contribution

Trace requests on Echo framework with Jaeger Tracing Middleware.

Usage​

package main
import (
    "github.com/labstack/echo-contrib/jaegertracing"
    "github.com/labstack/echo/v4"
)
func main() {
    e := echo.New()
    // Enable tracing middleware
    c := jaegertracing.New(e, nil)
    defer c.Close()

    e.Logger.Fatal(e.Start(":1323"))
}

Enabling the tracing middleware creates a tracer and a root tracing span for every request.

Custom Configuration​

By default, traces are sent to localhost Jaeger agent instance. To configure an external Jaeger, start your application with environment variables.

Usage​

$ JAEGER_AGENT_HOST=192.168.1.10 JAEGER_AGENT_PORT=6831 ./myserver

The tracer can be initialized with values coming from environment variables. None of the env vars are required and all of them can be overridden via direct setting of the property on the configuration object.

PropertyDescription
JAEGER_SERVICE_NAMEThe service name
JAEGER_AGENT_HOSTThe hostname for communicating with agent via UDP
JAEGER_AGENT_PORTThe port for communicating with agent via UDP
JAEGER_ENDPOINTThe HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces
JAEGER_USERUsername to send as part of "Basic" authentication to the collector endpoint
JAEGER_PASSWORDPassword to send as part of "Basic" authentication to the collector endpoint
JAEGER_REPORTER_LOG_SPANSWhether the reporter should also log the spans
JAEGER_REPORTER_MAX_QUEUE_SIZEThe reporter's maximum queue size
JAEGER_REPORTER_FLUSH_INTERVALThe reporter's flush interval, with units, e.g. "500ms" or "2s" ([valid units][timeunits])
JAEGER_SAMPLER_TYPEThe sampler type
JAEGER_SAMPLER_PARAMThe sampler parameter (number)
JAEGER_SAMPLER_MANAGER_HOST_PORTThe HTTP endpoint when using the remote sampler, i.e. http://jaeger-agent:5778/sampling
JAEGER_SAMPLER_MAX_OPERATIONSThe maximum number of operations that the sampler will keep track of
JAEGER_SAMPLER_REFRESH_INTERVALHow often the remotely controlled sampler will poll jaeger-agent for the appropriate sampling strategy, with units, e.g. "1m" or "30s" ([valid units][timeunits])
JAEGER_TAGSA comma separated list of name = value tracer level tags, which get added to all reported spans. The value can also refer to an environment variable using the format ${envVarName:default}, where the :default is optional, and identifies a value to be used if the environment variable cannot be found
JAEGER_DISABLEDWhether the tracer is disabled or not. If true, the default opentracing.NoopTracer is used.
JAEGER_RPC_METRICSWhether to store RPC metrics

By default, the client sends traces via UDP to the agent at localhost:6831. Use JAEGER_AGENT_HOST and JAEGER_AGENT_PORT to send UDP traces to a different host:port. If JAEGER_ENDPOINT is set, the client sends traces to the endpoint via HTTP, making the JAEGER_AGENT_HOST and JAEGER_AGENT_PORT unused. If JAEGER_ENDPOINT is secured, HTTP basic authentication can be performed by setting the JAEGER_USER and JAEGER_PASSWORD environment variables.

Skipping URL(s)​

A middleware skipper can be passed to avoid tracing spans to certain URL(s).

Usage

package main
import (
	"strings"
    "github.com/labstack/echo-contrib/jaegertracing"
    "github.com/labstack/echo/v4"
)

// urlSkipper ignores metrics route on some middleware
func urlSkipper(c echo.Context) bool {
    if strings.HasPrefix(c.Path(), "/testurl") {
        return true
    }
    return false
}

func main() {
    e := echo.New()
    // Enable tracing middleware
    c := jaegertracing.New(e, urlSkipper)
    defer c.Close()

    e.Logger.Fatal(e.Start(":1323"))
}

TraceFunction​

This is a wrapper function that can be used to seamlessly add a span for the duration of the invoked function. There is no need to change function arguments.

Usage

package main
import (
    "github.com/labstack/echo-contrib/jaegertracing"
    "github.com/labstack/echo/v4"
    "net/http"
    "time"
)
func main() {
    e := echo.New()
    // Enable tracing middleware
    c := jaegertracing.New(e, nil)
    defer c.Close()
    e.GET("/", func(c echo.Context) error {
        // Wrap slowFunc on a new span to trace it's execution passing the function arguments
		jaegertracing.TraceFunction(c, slowFunc, "Test String")
        return c.String(http.StatusOK, "Hello, World!")
    })
    e.Logger.Fatal(e.Start(":1323"))
}

// A function to be wrapped. No need to change it's arguments due to tracing
func slowFunc(s string) {
	time.Sleep(200 * time.Millisecond)
	return
}

CreateChildSpan​

For more control over the Span, the function CreateChildSpan can be called giving control on data to be appended to the span like log messages, baggages and tags.

Usage

package main
import (
    "github.com/labstack/echo-contrib/jaegertracing"
    "github.com/labstack/echo/v4"
)
func main() {
    e := echo.New()
    // Enable tracing middleware
    c := jaegertracing.New(e, nil)
    defer c.Close()
    e.GET("/", func(c echo.Context) error {
        // Do something before creating the child span
        time.Sleep(40 * time.Millisecond)
        sp := jaegertracing.CreateChildSpan(c, "Child span for additional processing")
        defer sp.Finish()
        sp.LogEvent("Test log")
        sp.SetBaggageItem("Test baggage", "baggage")
        sp.SetTag("Test tag", "New Tag")
        time.Sleep(100 * time.Millisecond)
        return c.String(http.StatusOK, "Hello, World!")
    })
    e.Logger.Fatal(e.Start(":1323"))
}

References​