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:
Framework | Supported Version |
---|---|
AWS Lambda | All |
Generic Function | All |
HTTP | All |
Gin | All |
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.
Library | Supported Version |
---|---|
net/http | Fully 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.
Parameter | Environment Variable | Type | Default | Description |
---|---|---|---|---|
Token | EPSAGON_TOKEN | String | - | Epsagon account token |
ApplicationName | - | String | - | Application name that will be set for traces |
MetadataOnly | EPSAGON_METADATA | Boolean | true | Whether to send only the metadata (True ) or also the payloads (False ) |
CollectorURL | EPSAGON_COLLECTOR_URL | String | - | The address of the trace collector to send trace to |
Debug | EPSAGON_DEBUG | Boolean | False | Enable debug prints for troubleshooting |
SendTimeout | EPSAGON_SEND_TIMEOUT_SEC | String | 1s | The timeout duration to send the traces to the trace collector |
Updated 2 months ago