ginprom

README

Gin Prometheus Metrics Middleware

This repository provides a Gin middleware to collect Prometheus metrics for your Gin-based applications. The middleware captures HTTP request data, including response time, request counts, and more, and exposes them in a format that Prometheus can scrape.

Features

• Collects HTTP request count by method, status, and endpoint
• Tracks response time (latency) for each endpoint
• Collects request size and response size
• Provides a /metrics endpoint for Prometheus to scrape
• Easy integration with existing Gin applications

Installation

Install the middleware using go get:

go get github.com/logocomune/gin-prometheus

Usage

Here’s how to integrate the middleware into your Gin application:

package main

import (
	"github.com/gin-gonic/gin"
	"github.com/logocomune/gin-prometheus"
)

func main() {
	r := gin.Default()

	r.Use(ginprom.Middleware())

	r.GET("/metrics", gin.WrapH(ginprom.GetMetricHandler()))

	r.GET("/", func(c *gin.Context) {
		c.String(200, "Hello World")
	})
	r.GET("/test/:id", func(c *gin.Context) {
		c.String(200, "Hello World")
	})
	r.GET("/ping", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "pong",
		})
	})
	r.Run() // listen and serve on 0.0.0.0:8080
}

Middleware Options

The Middleware function allows you to customize the behavior of the middleware by passing configuration options:

metricsMiddleware := ginprometheus.Middleware(
ginprometheus.WithRecordRequests(false),
)

Metrics Collected

The middleware collects the following metrics:

1. HTTP Request Count

   • Metric name: http_requests_total
   • Labels: method, status, path`

2. HTTP Request Duration

   • Metric name: http_request_duration_seconds
   • Labels: method, status, path

3. Request Size

   • Metric name: http_request_size_bytes
   • Labels: method, status, path

4. Response Size

   • Metric name: http_response_size_bytes
   • Labels:method, status, path

Contributing

Contributions are welcome! Please open an issue or submit a pull request if you’d like to improve this middleware.

License

This project is licensed under the MIT License.

Documentation

Index

• func GetMetricHandler(opt ...HandlerOption) http.Handler
• func Middleware(options ...Option) gin.HandlerFunc
• type HandlerOption
  • func WithBasicAuth(username, password string) HandlerOption
• type Option
  • func WithAggregateStatusCode(aggregate bool) Option
  • func WithFilterPath(filter func(string, string) bool) Option
  • func WithFilterRoutes(routes []string) Option
  • func WithGroupedStatus(grouped bool) Option
  • func WithPathAggregator(aggregator func(string, string, int) string) Option
  • func WithRecordDuration(record bool) Option
  • func WithRecordRequestSize(record bool) Option
  • func WithRecordRequests(record bool) Option
  • func WithRecordResponseSize(record bool) Option

Functions

func GetMetricHandler

func GetMetricHandler(opt ...HandlerOption) http.Handler

GetMetricHandler returns an HTTP handler for exposing Prometheus metrics collected by the prometheus/promhttp package.

func Middleware

func Middleware(options ...Option) gin.HandlerFunc

Middleware returns a Gin middleware handler function for collecting and exporting Prometheus metrics. It supports optional configuration through variadic Option parameters.

Types

type HandlerOption

type HandlerOption func(*handlerConfig)

Option defines a function type used to modify the configuration of a service during initialization.

func WithBasicAuth

func WithBasicAuth(username, password string) HandlerOption

type Option

type Option func(*config)

Option defines a function type used to modify the configuration of a service during initialization.

func WithAggregateStatusCode

func WithAggregateStatusCode(aggregate bool) Option

WithAggregateStatusCode sets whether to aggregate request status codes in the configuration.

func WithFilterPath

func WithFilterPath(filter func(string, string) bool) Option

WithFilterPath sets a filter function to determine which paths should be included or excluded from certain operations.

func WithFilterRoutes

func WithFilterRoutes(routes []string) Option

WithFilterRoutes creates an Option to configure a filter that allows tracking only specified routes in the service.

func WithGroupedStatus

func WithGroupedStatus(grouped bool) Option

WithGroupedStatus configures whether status codes should be grouped when collecting metrics.

func WithPathAggregator

func WithPathAggregator(aggregator func(string, string, int) string) Option

WithPathAggregator sets a custom path aggregator function to aggregate paths based on the provided arguments.

func WithRecordDuration

func WithRecordDuration(record bool) Option

WithRecordDuration sets whether to record the duration of operations in the configuration.

func WithRecordRequestSize

func WithRecordRequestSize(record bool) Option

WithRecordRequestSize enables or disables recording of request sizes in the configuration.

func WithRecordRequests

func WithRecordRequests(record bool) Option

WithRecordRequests configures whether to enable or disable recording of requests in the configuration.

func WithRecordResponseSize

func WithRecordResponseSize(record bool) Option

WithRecordResponseSize sets whether the response size should be recorded in the configuration.