OpenTelemetry Gin Monitoring [otelgin]

OpenTelemetry Gin instrumentation allows developers to monitor and diagnose issues with their Gin applications, providing valuable insights into application behavior in production.

What is Gin?

Gin is a high-performance web framework for building web applications and APIs in Go. It features an HTTP router that is up to 40x faster than other Go routers, making it one of the most popular choices for Go web development.

Gin's key features include:

• Fast HTTP router using radix tree for efficient routing
• Middleware support with a chain of handlers
• JSON validation and rendering
• Error management and recovery from panics
• Grouping routes for better organization

Gin's simplicity and performance make it a popular choice for building web applications and RESTful APIs in Go.

What is OpenTelemetry?

OpenTelemetry is an open-source observability framework that aims to standardize and simplify the collection, processing, and export of telemetry data from applications and systems.

OpenTelemetry supports multiple programming languages and platforms, making it suitable for a wide range of applications and environments.

OpenTelemetry enables developers to instrument their code and collect telemetry data, which can then be exported to various OpenTelemetry backends or observability platforms for analysis and visualization. The OpenTelemetry architecture provides a modular, vendor-neutral approach to observability.

Gin instrumentation

OpenTelemetry Gin instrumentation (otelgin) provides automatic tracing and metrics collection for your Gin applications. It captures HTTP request details, timing information, and error states without requiring manual instrumentation.

To install otelgin instrumentation:

go get go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin

• Example
• Reference

Usage

You can instrument Gin router by installing OpenTelemetry middleware:

import (
    "github.com/gin-gonic/gin"
    "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
)

func main() {
    router := gin.Default()
    router.Use(otelgin.Middleware("my-service"))

    router.GET("/users/:id", getUser)
    router.Run(":8080")
}

Once instrumented, otelgin automatically creates spans for each incoming HTTP request, capturing method, route, status code, and timing information.

Middleware options

The otelgin middleware supports several configuration options:

Filtering health checks

Use the WithFilter option to exclude certain endpoints from tracing:

import (
    "net/http"

    "github.com/gin-gonic/gin"
    "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
)

router := gin.Default()
router.Use(otelgin.Middleware("my-service",
    otelgin.WithFilter(func(r *http.Request) bool {
        // Return true to trace, false to skip
        return r.URL.Path != "/health" && r.URL.Path != "/ready"
    }),
))

You can also use WithGinFilter for access to Gin context:

router.Use(otelgin.Middleware("my-service",
    otelgin.WithGinFilter(func(c *gin.Context) bool {
        return c.FullPath() != "/health"
    }),
))

Custom tracer and meter providers

For more control over telemetry collection, you can specify custom providers:

import (
    "github.com/gin-gonic/gin"
    "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
    "go.opentelemetry.io/otel"
)

router := gin.Default()
router.Use(otelgin.Middleware("my-service",
    otelgin.WithTracerProvider(otel.GetTracerProvider()),
    otelgin.WithMeterProvider(otel.GetMeterProvider()),
))

Custom span names

Customize how span names are generated:

import (
    "github.com/gin-gonic/gin"
    "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
)

router := gin.Default()
router.Use(otelgin.Middleware("my-service",
    otelgin.WithSpanNameFormatter(func(c *gin.Context) string {
        return c.Request.Method + " " + c.FullPath()
    }),
))

Adding custom attributes

Extract custom attributes from requests to enhance your metrics:

import (
    "net/http"

    "github.com/gin-gonic/gin"
    "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
    "go.opentelemetry.io/otel/attribute"
)

router := gin.Default()
router.Use(otelgin.Middleware("my-service",
    otelgin.WithMetricAttributeFn(func(r *http.Request) []attribute.KeyValue {
        return []attribute.KeyValue{
            attribute.String("http.client_ip", r.RemoteAddr),
            attribute.String("http.user_agent", r.UserAgent()),
        }
    }),
))

Instrumenting template rendering

To instrument template rendering, use the otelgin.HTML helper instead of c.HTML:

import (
    "net/http"

    "github.com/gin-gonic/gin"
    "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
)

func exampleHandler(c *gin.Context) {
    otelgin.HTML(c, http.StatusOK, "index.tmpl", gin.H{
        "title": "Hello World",
    })
}

This creates a child span for the template rendering operation, helping you identify slow templates.

HTTP metrics

The otelgin middleware automatically collects the following HTTP server metrics:

These metrics follow the OpenTelemetry semantic conventions for HTTP and include attributes like method, route, and status code.

What is Uptrace?

Uptrace is an OpenTelemetry APM that supports distributed tracing, metrics, and logs. You can use it to monitor applications and troubleshoot issues.

Uptrace comes with an intuitive query builder, rich dashboards, alerting rules with notifications, and integrations for most languages and frameworks.

Uptrace can process billions of spans and metrics on a single server and allows you to monitor your applications at 10x lower cost.

In just a few minutes, you can try Uptrace by visiting the cloud demo (no login required) or running it locally with Docker. The source code is available on GitHub.

What's next?

With OpenTelemetry Gin instrumentation in place, you can monitor request latency, track error rates, and trace requests across your distributed systems.

Next steps to enhance your observability:

• Add database instrumentation with GORM
• Create custom spans using the OpenTelemetry Go Tracing API
• Explore other Go frameworks like Echo or Beego
• Set up the OpenTelemetry Collector for production deployments