Index
Traces Package
This package provides functionalities for handling traces and metrics on behalf of OpenTelemetry libs in the Frávega systems.
Installation
go get github.com/bernnabe/buscapet-toolkit/observability
or declare the import of any package of this module in your code and then run the command
go mod tidy
Pre requisites
This package depends on SetRequestID middleware managed by buscapet-toolkit/framework/echo/middleware
You have to set following environment variables in your api container:
- SERVICE_NAME: {your service name eg: golang-tookit}
- SERVICE_VERSION: {your service version eg: 0.0.1}
- ENRIVIRONMENT: {your environment eg: local}
Middleware configuration
In your routing configuration you have to add the middleware to root api definition, for exmaple:
Generally, we have a file named route.go where we configure our endpoints with their handlers and middlewares like that:
import "github.com/bernnabe/buscapet-toolkit/framework/gin/middleware"
...
func registerApiRoutes(server *gin.Engine, handlers *dependencies.HandlerContainer) {
groupAPI := server.Group("/api").Use(middleware.SetRequestID, middleware.RequestTracer)
...
You have to set first middleware.SetRequestID and then middleware.RequestTracer. Is a must!
Tracing a Request
Usage example:
import traces "github.com/bernnabe/buscapet-toolkit/observability"
...
func (handler *CreateUser) Handle(c *gin.Context) {
ctx, span := traces.Start(c.Request.Context(), "CreateUser.Handle")
defer span.End()
...
}
Tracing a Request Setting Custom Attributes
Usage example:
import traces "github.com/bernnabe/buscapet-toolkit/observability"
...
func (handler *CreateUser) Handle(c *gin.Context) {
ctx, span := traces.Start(c.Request.Context(), "CreateUser.Handle")
defer span.End()
span.SetAttributes([]traces.KeyValue{{Key: "environment", Value: "local"}})
...
}
Metrics Package
The metrics package allows you to collect various types of metrics and register observers. To use the package, import it in your code:
import (
"context"
"github.com/bernnabe/buscapet-toolkit/observability/metrics"
"github.com/bernnabe/buscapet-toolkit/observability"
...
)
Counting Metrics
To count an integer metric, use CountInt:
func SomeFunction(ctx context.Context) {
err := metrics.CountInt(ctx, "requests_count", 1, observability.KeyValue{Key: "status", Value: "success"})
if err != nil {
// Handle error
}
}
To count a floating-point metric, use CountFloat:
func SomeFunction(ctx context.Context) {
err := metrics.CountFloat(ctx, "response_time", 15.5, observability.KeyValue{Key: "endpoint", Value: "/api/v1/get"})
if err != nil {
// Handle error
}
}
Up/Down Counting Metrics
Up/Down counting metrics allow you to track increments and decrements separately. To use them, use the UpDownCountInt and UpDownCountFloat functions in a similar way to the counting metrics.
Histogram Metrics
To track histogram metrics, use the HistogramInt and HistogramFloat functions:
func SomeFunction(ctx context.Context) {
err := metrics.HistogramInt(ctx, "request_duration", 50, observability.KeyValue{Key: "endpoint", Value: "/api/v1/post"})
if err != nil {
// Handle error
}
}
Register Observers
The package provides methods to register observer functions for different types of gauges and counters:
type observable struct {
...
}
func NewObservableRepository(ctx context.Context) providers.ObservableMetric {
obsOffset := observable{}
obsOffset.registerObservableOffsets(ctx)
return &obsOffset
}
...
func (r *observable) registerObservable(ctx context.Context) {
callback := func(_ context.Context, obs observers.Int64Observer) error {
...
obs.Observe(offset.(int64), observability.StringKeyValue("key", key.(string)), observability.Int64KeyValue("value", value.(int64)))
...
return nil
}
toolkitMetrics.RegisterIntObservableGauge(ctx, "offset", callback)
}