ginprom

README

ginprom

Gin Prometheus metrics exporter inspired by github.com/zsais/go-gin-prometheus

Install

Simply run: go get -u github.com/Depado/ginprom

Differences with go-gin-prometheus

• No support for Prometheus' Push Gateway
• Options on constructor
• Adds a path label to get the matched route
• Ability to ignore routes

Usage

package main

import (
	"github.com/Depado/ginprom"
	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()
	p := ginprom.New(
		ginprom.Engine(r),
		ginprom.Subsystem("gin"),
		ginprom.Path("/metrics"),
	)
	r.Use(p.Instrument())

	r.GET("/hello/:id", func(c *gin.Context) {})
	r.GET("/world/:id", func(c *gin.Context) {})
	r.Run("127.0.0.1:8080")
}

Options

Custom gauges

Add custom gauges to add own values to the metrics

r := gin.New()
p := ginprom.New(
	ginprom.Engine(r),
)
p.AddCustomGauge("custom", "Some help text to provide", []string{"label"})
r.Use(p.Instrument())

Save p and use the following functions:

• IncrementGaugeValue
• DecrementGaugeValue
• SetGaugeValue

Path

Override the default path (/metrics) on which the metrics can be accessed:

r := gin.New()
p := ginprom.New(
	ginprom.Engine(r),
	ginprom.Path("/custom/metrics"),
)
r.Use(p.Instrument())

Namespace

Override the default namespace (gin):

r := gin.New()
p := ginprom.New(
	ginprom.Engine(r),
	ginprom.Namespace("custom_ns"),
)
r.Use(p.Instrument())

Subsystem

Override the default (gonic) subsystem:

r := gin.New()
p := ginprom.New(
	ginprom.Engine(r),
	ginprom.Subsystem("your_subsystem"),
)
r.Use(p.Instrument())

Engine

The preferred way to pass the router to ginprom:

r := gin.New()
p := ginprom.New(
	ginprom.Engine(r),
)
r.Use(p.Instrument())

The alternative being to call the Use method after initialization:

p := ginprom.New()
// ...
r := gin.New()
p.Use(r)
r.Use(p.Instrument())

Ignore

Ignore allows to completely ignore some routes. Even though you can apply the middleware to the only groups you're interested in, it is sometimes useful to have routes not instrumented.

r := gin.New()
p := ginprom.New(
	ginprom.Engine(r),
	ginprom.Ignore("/api/no/no/no", "/api/super/secret/route")
)
r.Use(p.Instrument())

Note that most of the time this can be solved by gin groups:

r := gin.New()
p := ginprom.New(ginprom.Engine(r))

// Add the routes that do not need instrumentation
g := r.Group("/api/")
g.Use(p.Instrument())
{
	// Instrumented routes
}

Token

Specify a secret token which Prometheus will use to access the endpoint. If the token is invalid, the endpoint will return an error.

r := gin.New()
p := ginprom.New(
	ginprom.Engine(r),
	ginprom.Token("supersecrettoken")
)
r.Use(p.Instrument())

Troubleshooting

The instrumentation doesn't seem to work

Make sure you have set the gin.Engine in the ginprom middleware, either when initializing it using ginprom.New(ginprom.Engine(r)) or using the Use function after the initialization like this :

p := ginprom.New(
	ginprom.Namespace("gin"),
	ginprom.Subsystem("gonic"),
	ginprom.Path("/metrics"),
)
p.Use(r)
r.Use(p.Instrument())

By design, if the middleware was to panic, it would do so when a route is called. That's why it just silently fails when no engine has been set.

Documentation

Overview

Package ginprom is a library to instrument a gin server and expose a /metrics endpoint for Prometheus to scrape, keeping a low cardinality by preserving the path parameters name in the prometheus label

Index

• func Engine(e *gin.Engine) func(*Prometheus)
• func Ignore(paths ...string) func(*Prometheus)
• func Namespace(ns string) func(*Prometheus)
• func Path(path string) func(*Prometheus)
• func Subsystem(sub string) func(*Prometheus)
• func Token(token string) func(*Prometheus)
• type Prometheus
  • func New(options ...func(*Prometheus)) *Prometheus
  • func (p *Prometheus) AddCustomGauge(name, help string, labels []string)
  • func (p *Prometheus) DecrementGaugeValue(name string, labelValues []string) error
  • func (p *Prometheus) IncrementGaugeValue(name string, labelValues []string) error
  • func (p *Prometheus) Instrument() gin.HandlerFunc
  • func (p *Prometheus) SetGaugeValue(name string, labelValues []string, value float64) error
  • func (p *Prometheus) Use(e *gin.Engine)

Examples

• Path
• Token

Functions

func Engine

func Engine(e *gin.Engine) func(*Prometheus)

Engine is an option allowing to set the gin engine when intializing with New. Example : r := gin.Default() p := ginprom.New(Engine(r))

func Ignore

func Ignore(paths ...string) func(*Prometheus)

Ignore is used to disable instrumentation on some routes

func Namespace

func Namespace(ns string) func(*Prometheus)

Namespace is an option allowing to set the namespace when intitializing with New

func Path

func Path(path string) func(*Prometheus)

Path is an option allowing to set the metrics path when intializing with New

Example

Set the path (endpoint) where the metrics will be served

r := gin.New()
p := New(Engine(r), Path("/metrics"))
r.Use(p.Instrument())

func Subsystem

func Subsystem(sub string) func(*Prometheus)

Subsystem is an option allowing to set the subsystem when intitializing with New

func Token

func Token(token string) func(*Prometheus)

Token is an option allowing to set the bearer token in prometheus with New. Example : ginprom.New(ginprom.Token("your_custom_token"))

Example

Set a secret token that is required to access the endpoint

r := gin.New()
p := New(Engine(r), Token("supersecrettoken"))
r.Use(p.Instrument())

Types

type Prometheus

type Prometheus struct {
	MetricsPath string
	Namespace   string
	Subsystem   string
	Token       string
	Ignored     pmapb
	Engine      *gin.Engine
	PathMap     pmap
	// contains filtered or unexported fields
}

Prometheus contains the metrics gathered by the instance and its path

func New

func New(options ...func(*Prometheus)) *Prometheus

New will initialize a new Prometheus instance with the given options. If no options are passed, sane defaults are used. If a router is passed using the Engine() option, this instance will automatically bind to it.

func (*Prometheus) AddCustomGauge

func (p *Prometheus) AddCustomGauge(name, help string, labels []string)

AddCustomGauge adds a custom gauge and registers it

func (*Prometheus) DecrementGaugeValue

func (p *Prometheus) DecrementGaugeValue(name string, labelValues []string) error

DecrementGaugeValue decrements a custom gauge

func (*Prometheus) IncrementGaugeValue

func (p *Prometheus) IncrementGaugeValue(name string, labelValues []string) error

IncrementGaugeValue increments a custom gauge

func (*Prometheus) Instrument

func (p *Prometheus) Instrument() gin.HandlerFunc

Instrument is a gin middleware that can be used to generate metrics for a single handler

func (*Prometheus) SetGaugeValue

func (p *Prometheus) SetGaugeValue(name string, labelValues []string, value float64) error

SetGaugeValue set gauge to value

func (*Prometheus) Use

func (p *Prometheus) Use(e *gin.Engine)

Use is a method that should be used if the engine is set after middleware initialization