README
¶
Usage
package main
import (
"github.com/labstack/echo/v4"
"gitlab.com/lyda/echoprometheus"
)
func main() {
e := echo.New()
// Enable metrics middleware
e.Use(echoprometheus.NewMiddleware("myapp"))
e.GET("/metrics", echoprometheus.NewHandler())
e.Logger.Fatal(e.Start(":1323"))
}
How to migrate
Changing the import line from
github.com/labstack/echo-contrib/echoprometheus to
gitlab.com/lyda/echoprometheus should work just fine. The only
difference is that the url label will show empty paths for 404s
by default if you use NewMiddleware.
If you use NewMiddlewareWithConfig there will not be a url label
unless DoNotUseRequestPathFor404 is set to true or if you've created
one as an override in LabelFuncs.
Initialisation remains the same
Both versions should be initialised the same way:
e := echo.New()
e.Use(echoprometheus.NewMiddleware("myapp")) // register middleware to gather metrics from requests
e.GET("/metrics", echoprometheus.NewHandler()) // register route to serve gathered metrics in Prometheus format
Skipper still works:
To skip /metrics from counting towards any stats:
conf := echoprometheus.MiddlewareConfig{
Skipper: func(c echo.Context) bool {
return c.Path() == "/metrics"
},
}
e.Use(echoprometheus.NewMiddlewareWithConfig(conf))
LabelValueFunc will still work
These function fields can be used to define how "code", "method" or
"host" attribute in Prometheus metric lines are created.
They can also add back the url label if you want it back.
These can now be substituted by using LabelFuncs:
e.Use(echoprometheus.NewMiddlewareWithConfig(echoprometheus.MiddlewareConfig{
LabelFuncs: map[string]echoprometheus.LabelValueFunc{
"scheme": func(c echo.Context, err error) string { // additional custom label
return c.Scheme()
},
"url": func(c echo.Context, err error) string { // additional custom label
return "x_" + c.Request().URL.Path
},
"host": func(c echo.Context, err error) string { // overrides default 'host' label value
return "y_" + c.Request().Host
},
},
}))
Will produce this Prometheus line:
echo_request_duration_seconds_count{code="200",host="y_example.com",method="GET",url="y_/",scheme="http"} 1
Documentation
¶
Overview ¶
Package echoprometheus provides middleware to add Prometheus metrics.
This is a fork of the labstack echoprometheus module.
Index ¶
- func NewHandler() echo.HandlerFunc
- func NewHandlerWithConfig(config HandlerConfig) echo.HandlerFunc
- func NewMiddleware(subsystem string) echo.MiddlewareFunc
- func NewMiddlewareWithConfig(config MiddlewareConfig) echo.MiddlewareFunc
- func RunPushGatewayGatherer(ctx context.Context, config PushGatewayConfig) error
- func SafeURLLabelFunc(c echo.Context, _ error) string
- func UnsafeURLLabelFunc(c echo.Context, _ error) string
- func WriteGatheredMetrics(writer io.Writer, gatherer prometheus.Gatherer) error
- type HandlerConfig
- type LabelValueFunc
- type MiddlewareConfig
- type PushGatewayConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewHandler ¶
func NewHandler() echo.HandlerFunc
NewHandler creates new instance of Handler using Prometheus default registry.
func NewHandlerWithConfig ¶
func NewHandlerWithConfig(config HandlerConfig) echo.HandlerFunc
NewHandlerWithConfig creates new instance of Handler using given configuration.
func NewMiddleware ¶
func NewMiddleware(subsystem string) echo.MiddlewareFunc
NewMiddleware creates new instance of middleware using Prometheus default registry.
func NewMiddlewareWithConfig ¶
func NewMiddlewareWithConfig(config MiddlewareConfig) echo.MiddlewareFunc
NewMiddlewareWithConfig creates new instance of middleware using given configuration.
func RunPushGatewayGatherer ¶
func RunPushGatewayGatherer(ctx context.Context, config PushGatewayConfig) error
RunPushGatewayGatherer starts pushing collected metrics and waits for it context to complete or ErrorHandler to return error.
Example: ```
go func() {
config := echoprometheus.PushGatewayConfig{
PushGatewayURL: "https://host:9080",
PushInterval: 10 * time.Millisecond,
}
if err := echoprometheus.RunPushGatewayGatherer(context.Background(), config); !errors.Is(err, context.Canceled) {
log.Fatal(err)
}
}()
```
func SafeURLLabelFunc ¶
SafeURLLabelFunc this is the url value if conf.DoNotUseRequestPathFor404 is true. This greatly reduces the risk of cardinality issues.
func UnsafeURLLabelFunc ¶
UnsafeURLLabelFunc this used to be what the url value was if conf.DoNotUseRequestPathFor404 was false. It is now not set by default.This has a high risk of cardinality issues - especially if internet facing.
func WriteGatheredMetrics ¶
func WriteGatheredMetrics(writer io.Writer, gatherer prometheus.Gatherer) error
WriteGatheredMetrics gathers collected metrics and writes them to given writer.
Types ¶
type HandlerConfig ¶
type HandlerConfig struct {
// Gatherer sets the prometheus.Gatherer instance the middleware
// will use when generating the metric endpoint handler.
// Defaults to: prometheus.DefaultGatherer
Gatherer prometheus.Gatherer
}
HandlerConfig contains the configuration for creating HTTP handler for metrics.
type LabelValueFunc ¶
LabelValueFunc is used to generate the value for a label.
type MiddlewareConfig ¶
type MiddlewareConfig struct {
// Skipper defines a function to skip middleware.
Skipper middleware.Skipper
// Namespace is components of the fully-qualified name of the
// Metric (created by joining Namespace,Subsystem and Name
// components with "_")
// Optional
Namespace string
// Subsystem is components of the fully-qualified name of the
// Metric (created by joining Namespace,Subsystem and Name
// components with "_")
// Defaults to: "echo"
Subsystem string
// LabelFuncs allows adding custom labels in addition to default
// labels. When key has same name with default label it replaces
// default one.
LabelFuncs map[string]LabelValueFunc
// HistogramOptsFunc allows to change options for metrics of
// type histogram before metric is registered to Registerer
HistogramOptsFunc func(opts prometheus.HistogramOpts) prometheus.HistogramOpts
// CounterOptsFunc allows to change options for metrics of type
// counter before metric is registered to Registerer
CounterOptsFunc func(opts prometheus.CounterOpts) prometheus.CounterOpts
// Registerer sets the prometheus.Registerer instance the
// middleware will register these metrics with.
// Defaults to: prometheus.DefaultRegisterer
Registerer prometheus.Registerer
// BeforeNext is callback that is executed before next
// middleware/handler is called. Useful for case when you have
// own metrics that need data to be stored for AfterNext.
BeforeNext func(c echo.Context)
// AfterNext is callback that is executed after next
// middleware/handler returns. Useful for case when you have
// own metrics that need incremented/observed.
AfterNext func(c echo.Context, err error)
// If DoNotUseRequestPathFor404 is true, all 404 responses
// (due to non-matching route) will have the same `url` label
// and thus won't generate new metrics.
DoNotUseRequestPathFor404 bool
// contains filtered or unexported fields
}
MiddlewareConfig contains the configuration for creating prometheus middleware collecting several default metrics.
func (MiddlewareConfig) ToMiddleware ¶
func (conf MiddlewareConfig) ToMiddleware() (echo.MiddlewareFunc, error)
ToMiddleware converts configuration to middleware or returns an error.
type PushGatewayConfig ¶
type PushGatewayConfig struct {
// PushGatewayURL is push gateway URL in format http://domain:port
PushGatewayURL string
// PushInterval in ticker interval for pushing gathered metrics
// to the Gateway.
// Defaults to: 1 minute
PushInterval time.Duration
// Gatherer sets the prometheus.Gatherer instance the middleware
// will use when generating the metric endpoint handler.
// Defaults to: prometheus.DefaultGatherer
Gatherer prometheus.Gatherer
// ErrorHandler is function that is called when errors occur. When
// callback returns error StartPushGateway also returns.
ErrorHandler func(err error) error
// ClientTransport specifies the mechanism by which individual
// HTTP POST requests are made.
// Defaults to: http.DefaultTransport
ClientTransport http.RoundTripper
}
PushGatewayConfig contains the configuration for pushing to a Prometheus push gateway.
Source Files