Epsagon Documentation

Welcome to the Epsagon Documentation. You'll find comprehensive guides and documentation to help you start working with our product as quickly as possible. Let's jump right in!

Get Started

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:

FrameworkSupported Version
AWS LambdaAll
Generic FunctionAll
HTTPAll
GinAll

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.

LibrarySupported Version
net/httpFully supported
aws-sdk-go>=1.10.0
aws-sdk-go-v2>=0.23.0

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.

ParameterEnvironment VariableTypeDefaultDescription
TokenEPSAGON_TOKENString-Epsagon account token
ApplicationName-String-Application name that will be set for traces
MetadataOnlyEPSAGON_METADATABooleantrueWhether to send only the metadata (True) or also the payloads (False)
CollectorURLEPSAGON_COLLECTOR_URLString-The address of the trace collector to send trace to
DebugEPSAGON_DEBUGBooleanFalseEnable debug prints for troubleshooting
SendTimeoutEPSAGON_SEND_TIMEOUT_SECString1sThe timeout duration to send the traces to the trace collector

Updated 2 months ago


Go


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.