README
¶
gin-telemetry
Gin Telemetry is a middleware to exporting traces based on the open-telemetry project
Install
To install execute the command below:
go get -u github.com/bancodobrasil/gin-telemetry
Environemnt variables
Below are the environment variables that affect the behavior of the middleware:
| Variable | Description | Default |
|---|---|---|
| TELEMETRY_EXPORTER_JAEGER_AGENT_HOST | Agent Host for the collector that spans are sent to | localhost |
| TELEMETRY_EXPORTER_JAEGER_AGENT_PORT | Agent Port URL for the collector that spans are sent to | 6831 |
| TELEMETRY_HTTPCLIENT_TLS | Custom http client for passthrough TLS enabled | true |
| TELEMETRY_DISABLED | Disable middleware to export span for collectors | false |
| TELEMETRY_ENVIRONMENT | Environment to export span for collectors | test |
Register Tracing Middleware
You must register the tracing middleware to enable export traces
Example for all routes:
import (
"github.com/gin-gonic/gin"
telemetry "github.com/bancodobrasil/gin-telemetry"
)
func main() {
// ... extra code
router := gin.Default()
router.Use(telemtry.Middleware("service_name"))
// ... extra code
}
Example for specific route:
import (
"github.com/gin-gonic/gin"
telemetry "github.com/bancodobrasil/gin-telemetry"
)
func main() {
// ... extra code
router := gin.Default()
router.GET("/user/:name", telemetry.Middleware(serviceName), handlerImpl)
// ... extra code
}
func handlerImpl(c *gin.Context) {
// handler implementation
}
Passthrough - Propagate context
Context propagation example through custom http client
import (
"net/http"
"github.com/gin-gonic/gin"
telemetry "github.com/bancodobrasil/gin-telemetry"
)
func main() {
// ... extra code
router := gin.Default()
router.GET("/user/:name", telemetry.Middleware(serviceName), handlerImpl)
// ... extra code
}
func handlerImple(c *gin.Context) {
// recover context
ctx := c.Request.Context()
// create a request with context
req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf("%s/user/%s", externalServiceURL, name), nil)
// ... extra code
// do request with httpclient telemetry ** MUST **
res, err := telemetry.HTTPClient.Do(req)
// ... extra code
}
Logrus Logging
This instrumentation records logrus log messages as events on the existing span that is passed via a context.Context.
It does not record anything if a context does not contain a span.
Example:
import (
"github.com/uptrace/opentelemetry-go-extra/otellogrus"
"github.com/sirupsen/logrus"
)
// ...extra code
// Use ctx to pass the active span.
logrus.WithContext(ctx).
WithError(errors.New("hello world")).
WithField("foo", "bar").
Error("something failed")
// ...extra code
Docker Compose Example
in the example folder we have a docker-compose for testing traceability between 3 services and a active Jaeger as an exporter.
To start docker-compose executes:
~example$ docker-compose up --build -d
The services are published with the address below:
http://localhost:7001/user/:name
http://localhost:7002/user/:name
http://localhost:7003/user/:name
The jaeger is published with the address below:
http://localhost:16686
Open the browser and execute request according to addresses above and check jaeger panel. Thx!
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var HTTPClient *http.Client = newHTTPClient()
HTTPClient ...
var ( // MiddlewareDisabled ... MiddlewareDisabled bool )
Functions ¶
func Middleware ¶
func Middleware(serviceName string, opts ...Option) gin.HandlerFunc
Middleware ...
Types ¶
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option ...
func WithPropagators ¶
func WithPropagators(propagators propagation.TextMapPropagator) Option
WithPropagators ...
type TracerProvider ¶
type TracerProvider struct {
*sdktrace.TracerProvider
// contains filtered or unexported fields
}
TracerProvider ...
Source Files