Gin Integration
Instrument Go Gin applications with one middleware registration. Route-level spans, GORM query tracing, outbound HTTP client instrumentation, and Go runtime metrics — zero overhead.
How It Works
Install the Go Module
Run go get github.com/tigerops/tigerops-go/gin. The module is a thin wrapper around the OpenTelemetry Go SDK that adds a Gin-compatible middleware factory and GORM plugin. Go 1.21+ is required.
Register the Middleware
Call tigeropsgin.Middleware() and add it to your Gin engine with router.Use(). Place it before other middleware to ensure all handlers are covered. The middleware auto-reads W3C traceparent headers from incoming requests.
Set Environment Variables
Set TIGEROPS_API_KEY, TIGEROPS_SERVICE_NAME, and TIGEROPS_ENVIRONMENT. The TigerOps SDK reads these at startup via os.Getenv. A functional options pattern (tigerops.WithAPIKey, tigerops.WithServiceName) is also available for programmatic config.
Route Spans & Go Runtime Metrics
TigerOps begins capturing Gin route spans with handler name and path params, GORM query spans, outbound HTTP client traces, goroutine counts, heap allocation rates, and GC pause durations within seconds of startup.
What You Get Out of the Box
Gin Middleware Request Tracing
The TigerOps Gin middleware creates a root span for every request with HTTP method, matched route pattern (not raw URL), response status, and latency. Path parameters and query params are recorded as span attributes without capturing sensitive values.
Route Group & Handler Spans
Each Gin handler in a route group creates a child span with the fully qualified handler function name. Route group prefixes appear in the route attribute. Handler panic recovery is instrumented to capture the panic value and stack trace.
GORM Query Tracing
Register the TigerOps GORM plugin with db.Use(tigerops.GORMPlugin()). Every GORM operation creates a child span with normalized SQL, table name, rows affected, and execution time. Preload and Association queries appear as sibling spans.
Outbound HTTP Client Tracing
Wrap your http.Client transport with tigerops.NewHTTPTransport() to auto-instrument all outbound HTTP calls. Spans include target host, method, response status, and DNS plus TLS timing. W3C traceparent headers are injected automatically.
Go Runtime Metrics
TigerOps continuously exports Go runtime metrics: goroutine count, heap in-use and idle bytes, GC cycle frequency, GC pause duration p50/p99, CGo call count, and scheduler runqueue latency. All metrics are tagged with service name and version.
Context Propagation & Baggage
The Gin middleware stores the active span in gin.Context so handler functions can retrieve it with tigerops.SpanFromGin(c). OpenTelemetry baggage items from incoming W3C headers are available via tigerops.BaggageFromGin(c) for custom routing logic.
Install & Initialize
One go get and one router.Use() call. Full Gin observability.
# Install the TigerOps Gin module
go get github.com/tigerops/tigerops-go/gin
# Set environment variables
export TIGEROPS_API_KEY="your-api-key"
export TIGEROPS_SERVICE_NAME="my-gin-app"
export TIGEROPS_ENVIRONMENT="production"
// main.go
package main
import (
"github.com/gin-gonic/gin"
tigerops "github.com/tigerops/tigerops-go"
tigeropsgin "github.com/tigerops/tigerops-go/gin"
tigerormgorm "github.com/tigerops/tigerops-go/gorm"
"gorm.io/gorm"
)
func main() {
// Initialize TigerOps
tp := tigerops.Init(
tigerops.WithServiceName("my-gin-app"),
tigerops.WithEnvironment("production"),
)
defer tp.Shutdown(context.Background())
// Setup GORM with TigerOps plugin
db, _ := gorm.Open(postgres.Open(dsn))
db.Use(tigerormgorm.Plugin())
// Setup Gin with TigerOps middleware
r := gin.New()
r.Use(tigeropsgin.Middleware())
r.Use(gin.Recovery())
v1 := r.Group("/api/v1")
v1.GET("/orders/:id", func(c *gin.Context) {
ctx := c.Request.Context()
span := tigerops.SpanFromGin(c)
span.SetAttributes(attribute.String("order.id", c.Param("id")))
var order Order
db.WithContext(ctx).First(&order, c.Param("id"))
c.JSON(200, order)
})
r.Run(":8080")
}Common Questions
Which Gin and Go versions are supported?
Gin 1.9.x and later are supported. Go 1.21 and later are supported. The TigerOps Go module uses the standard library net/http transport under the hood, so it is compatible with all Gin-compatible Go versions including the latest toolchain releases.
How does TigerOps handle Gin router groups and versioned APIs?
Route group prefixes are automatically included in the span route attribute. A handler registered as v1.GET("/orders/:id", handler) will produce a span with route: /api/v1/orders/:id. This prevents high-cardinality span names from raw URLs with dynamic segments.
Can I use TigerOps with Gin running in GIN_MODE=release?
Yes. TigerOps middleware operates independently of the Gin mode setting. In release mode, Gin suppresses debug log output but TigerOps telemetry export to OTLP endpoints is unaffected. All span data is sent regardless of the Gin run mode.
Does TigerOps work with Gin deployed behind an AWS ALB or Nginx?
Yes. TigerOps reads the X-Forwarded-For header for real client IP and extracts W3C traceparent from upstream proxies. Configure your ALB or Nginx to forward the traceparent header to preserve distributed trace context from your load balancer or CDN.
What is the latency overhead of the TigerOps Gin middleware?
The middleware adds under 10 microseconds of overhead per request at 100% sampling. Span export is asynchronous using a non-blocking ring buffer. At 10% sampling the overhead drops below 1 microsecond. The middleware never blocks request processing.
Full Gin Observability in One Go Module
Route spans, GORM traces, Go runtime metrics, and outbound HTTP instrumentation — no code changes required.