This package provides tracing to Go applications for the collection of distributed tracing and performance metrics in Epsagon.

📘

Open source repository

This is an open-source project which can be found at our GitHub repository.

Usage

Tagging Traces

You can add custom tags to your traces, for easier filtering and aggregations.

Add the following call inside your code:

epsagon.Label("key", "value")
epsagon.Label("user_id", user_id)

You can also use it to ship custom metrics:

epsagon.Label("key", "metric")
epsagon.Label("items_in_cart", items_in_cart)

Valid types are string, bool, int and float.
Custom labels are not trimmed with the trace events in case the trace is too big.

Custom Errors

You can set a trace as an error (although handled correctly) to get an alert or just follow it on the dashboard.
Add the following call inside your code:

epsagon.TypeError("My custom error", "Custom Error Type")
# Or manually add an error
epsagon.TypeError(errors.New("My custom error"), "Custom Error Type")

You can also set a tracer as an error with a default error type:

epsagon.Error("My custom error")
# Or manually add an error
epsagon.Error(errors.New("My custom error"))

Ignored Keys

You can set keys that will be masked in the sent trace from the events metadata to hide selected information:

    config.IgnoredKeys = []string{"password"}
    client := http.Client{Transport: epsagonhttp.NewTracingTransport(ctx)}
    // This password will be masked in the sent trace:
    decodedJSON, err := json.Marshal(map[string]string{"password": "abcde", "animal": "lion"})
    resp, err := client.Post("http://example.com/upload", "application/json", bytes.NewReader(decodedJSON))

Valid types are string and error.

Installation

To install Epsagon, simply run:

go get github.com/epsagon/epsagon-go/epsagon

Or using dep:

dep ensure -add github.com/epsagon/epsagon-go/epsagon

Frameworks

The following frameworks are supported by Epsagon:

http

Wrapping http handlers with Epsagon:

import (
    "github.com/epsagon/epsagon-go/epsagon"
    epsagonhttp "github.com/epsagon/epsagon-go/wrappers/net/http"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/ping", epsagonhttp.WrapHandleFunc(
        epsagon.NewTracerConfig("test-http-mux", ""),
        func(w http.ResponseWriter, req *http.Request) {
            io.WriteString(w, "pong\n")
        }),
        "my-handler-name",
    )

    http.ListenAndServe(":8080", mux)
}

The third and fourth arguments to epsagonhttp.WrapHandleFunc are optional and set the resource name and the hostname. If the resource name is not set then the wrapped funcdtion name is used and the hostname is taken from the request URL if omitted.

mux.HandleFunc("/ping", epsagonhttp.WrapHandleFunc(
        epsagon.NewTracerConfig("test-http-mux", ""),
        func(w http.ResponseWriter, req *http.Request) {
            io.WriteString(w, "pong\n")
        }),
        "my-handler-name",
        "test.hostname.com",
    )

To wrap nested libraries you can get the epsagon context from the request context:

client := http.Client{
    Transport: epsagonhttp.NewTracingTransport(req.Context())}
resp, err := client.Get("http://example.com")

gin

You can easily instrument gin applications with Epsagon:

import (
    "github.com/epsagon/epsagon-go/epsagon"
    epsagongin "github.com/epsagon/epsagon-go/wrappers/gin"
    "github.com/gin-gonic/gin"
)

func main() {
    r := epsagongin.GinRouterWrapper{
        IRouter:  gin.Default(),
        Hostname: "my_site",
        Config:   epsagon.NewTracerConfig(
        "test-gin-application", "",
        ),
    }

    r.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{
            "message": "pong",
        })
    })
    r.IRouter.(*gin.Engine).Run()
}

If you want to instument other integrated libraries inside the gin handler you can get the Epsagon context from the gin.Context to do that:

client := http.Client{
    Transport: epsagonhttp.NewTracingTransport(epsagongin.EpsagonContext(c))}
resp, err := client.Get("http://example.com")

Integrations

Epsagon provides out-of-the-box instrumentation (tracing) for many popular frameworks and libraries.

net/http

Wrap HTTP/S clients to trace requests

import (
  httpEpsagon "github.com/epsagon/epsagon-go/wrappers/net/http"
  "net/http"
)

func Foo () {
  client := httpEpsagon.Wrap(http.Client{})
  resp, err := client.Get(<URL>)
}

aws-sdk-go

aws-sdk-go is wrapped through a Session object

import (
  awsEpsagon "github.com/epsagon/epsagon-go/wrappers/aws/aws-sdk-go/aws"
)

func Foo () {
  sessMust := session.Must(session.newSession())
  sess := awsEpsagon.WrapSession(sessMust)
  svcSQS := sqs.New(sess)
}

aws-sdk-go-v2

aws-sdk-go-v2 is wrapped through a Service object

import (
  "github.com/aws/aws-sdk-go-v2/service/dynamodb"
  "github.com/epsagon/epsagon-go/epsagon"
)

func Foo () {
  dynamoClient := dynamodb.New(config)
  svc := epsagon.WrapAwsV2Service(dynamoClient)
}

Configuration

Advanced options can be configured as a parameter to the Config struct to the WrapLambdaHandler or as environment variables.