Prometheus

Prometheus - 图1note

Echo community contribution

Prometheus middleware generates metrics for HTTP requests.

There are 2 versions of Prometheus middleware:

Migration guide from old to newer middleware can found here.

Usage

  • Add needed module go get -u github.com/labstack/echo-contrib

  • Add Prometheus middleware and metrics serving route

    1. e := echo.New()
    2. e.Use(echoprometheus.NewMiddleware("myapp")) // adds middleware to gather metrics
    3. e.GET("/metrics", echoprometheus.NewHandler()) // adds route to serve gathered metrics

Examples

Serve metric from the same server as where metrics is gathered

  1. package main
  3. import (
  4.     "errors"
  5.     "github.com/labstack/echo-contrib/echoprometheus"
  6.     "github.com/labstack/echo/v4"
  7.     "log"
  8.     "net/http"
  9. )
  11. func main() {
  12.     e := echo.New()
  13.     e.Use(echoprometheus.NewMiddleware("myapp")) // adds middleware to gather metrics
  14.     e.GET("/metrics", echoprometheus.NewHandler()) // adds route to serve gathered metrics
  16.     e.GET("/hello", func(c echo.Context) error {
  17.         return c.String(http.StatusOK, "hello")
  18.     })
  20.     if err := e.Start(":8080"); err != nil && !errors.Is(err, http.ErrServerClosed) {
  21.         log.Fatal(err)
  22.     }
  23. }

Serve metrics on a separate port

  1. func main() {
  2.     app := echo.New() // this Echo instance will serve route on port 8080
  3.     app.Use(echoprometheus.NewMiddleware("myapp")) // adds middleware to gather metrics
  5.     go func() {
  6.         metrics := echo.New() // this Echo will run on separate port 8081
  7.         metrics.GET("/metrics", echoprometheus.NewHandler()) // adds route to serve gathered metrics
  8.         if err := metrics.Start(":8081"); err != nil && !errors.Is(err, http.ErrServerClosed) {
  9.             log.Fatal(err)
  10.         }
  11.     }()
  13.     app.GET("/hello", func(c echo.Context) error {
  14.         return c.String(http.StatusOK, "hello")
  15.     })
  17.     if err := app.Start(":8080"); err != nil && !errors.Is(err, http.ErrServerClosed) {
  18.         log.Fatal(err)
  19.     }
  20. }

Sample output (for first example)

  1. curl http://localhost:8080/metrics
  3. # HELP echo_request_duration_seconds The HTTP request latencies in seconds.
  4. # TYPE echo_request_duration_seconds summary
  5. echo_request_duration_seconds_sum 0.41086482
  6. echo_request_duration_seconds_count 1
  7. # HELP echo_request_size_bytes The HTTP request sizes in bytes.
  8. # TYPE echo_request_size_bytes summary
  9. echo_request_size_bytes_sum 56
  10. echo_request_size_bytes_count 1
  11. # HELP echo_requests_total How many HTTP requests processed, partitioned by status code and HTTP method.
  12. # TYPE echo_requests_total counter
  13. echo_requests_total{code="200",host="localhost:8080",method="GET",url="/"} 1
  14. # HELP echo_response_size_bytes The HTTP response sizes in bytes.
  15. # TYPE echo_response_size_bytes summary
  16. echo_response_size_bytes_sum 61
  17. echo_response_size_bytes_count 1
  18. ...

Custom Configuration

Serving custom Prometheus Metrics

Usage

Using custom metrics with Prometheus default registry:

  1. package main
  3. import (
  4.     "errors"
  5.     "github.com/labstack/echo-contrib/echoprometheus"
  6.     "github.com/labstack/echo/v4"
  7.     "github.com/prometheus/client_golang/prometheus"
  8.     "log"
  9.     "net/http"
  10. )
  12. func main() {
  13.     e := echo.New()
  15.     customCounter := prometheus.NewCounter( // create new counter metric. This is replacement for `prometheus.Metric` struct
  16.         prometheus.CounterOpts{
  17.             Name: "custom_requests_total",
  18.             Help: "How many HTTP requests processed, partitioned by status code and HTTP method.",
  19.         },
  20.     )
  21.     if err := prometheus.Register(customCounter); err != nil { // register your new counter metric with default metrics registry
  22.         log.Fatal(err)
  23.     }
  25.     e.Use(echoprometheus.NewMiddlewareWithConfig(echoprometheus.MiddlewareConfig{
  26.         AfterNext: func(c echo.Context, err error) {
  27.             customCounter.Inc() // use our custom metric in middleware. after every request increment the counter
  28.         },
  29.     }))
  30.     e.GET("/metrics", echoprometheus.NewHandler()) // register route for getting gathered metrics
  32.     if err := e.Start(":8080"); err != nil && !errors.Is(err, http.ErrServerClosed) {
  33.         log.Fatal(err)
  34.     }
  35. }

or create your own registry and register custom metrics with that:

  1. package main
  3. import (
  4.     "errors"
  5.     "github.com/labstack/echo-contrib/echoprometheus"
  6.     "github.com/labstack/echo/v4"
  7.     "github.com/prometheus/client_golang/prometheus"
  8.     "log"
  9.     "net/http"
  10. )
  12. func main() {
  13.     e := echo.New()
  15.     customRegistry := prometheus.NewRegistry() // create custom registry for your custom metrics
  16.     customCounter := prometheus.NewCounter(    // create new counter metric. This is replacement for `prometheus.Metric` struct
  17.         prometheus.CounterOpts{
  18.             Name: "custom_requests_total",
  19.             Help: "How many HTTP requests processed, partitioned by status code and HTTP method.",
  20.         },
  21.     )
  22.     if err := customRegistry.Register(customCounter); err != nil { // register your new counter metric with metrics registry
  23.         log.Fatal(err)
  24.     }
  26.     e.Use(echoprometheus.NewMiddlewareWithConfig(echoprometheus.MiddlewareConfig{
  27.         AfterNext: func(c echo.Context, err error) {
  28.             customCounter.Inc() // use our custom metric in middleware. after every request increment the counter
  29.         },
  30.         Registerer: customRegistry, // use our custom registry instead of default Prometheus registry
  31.     }))
  32.     e.GET("/metrics", echoprometheus.NewHandlerWithConfig(echoprometheus.HandlerConfig{Gatherer: customRegistry})) // register route for getting gathered metrics data from our custom Registry
  34.     if err := e.Start(":8080"); err != nil && !errors.Is(err, http.ErrServerClosed) {
  35.         log.Fatal(err)
  36.     }
  37. }

Skipping URL(s)

Usage

A middleware skipper can be passed to avoid generating metrics to certain URL(s)

  1. package main
  3. import (
  4.     "errors"
  5.     "github.com/labstack/echo-contrib/echoprometheus"
  6.     "github.com/labstack/echo/v4"
  7.     "log"
  8.     "net/http"
  9.     "strings"
  10. )
  12. func main() {
  13.     e := echo.New()
  15.     mwConfig := echoprometheus.MiddlewareConfig{
  16.         Skipper: func(c echo.Context) bool {
  17.             return strings.HasPrefix(c.Path(), "/testurl")
  18.         }, // does not gather metrics metrics on routes starting with `/testurl`
  19.     }
  20.     e.Use(echoprometheus.NewMiddlewareWithConfig(mwConfig)) // adds middleware to gather metrics
  22.     e.GET("/metrics", echoprometheus.NewHandler()) // adds route to serve gathered metrics
  24.     e.GET("/", func(c echo.Context) error {
  25.         return c.String(http.StatusOK, "Hello, World!")
  26.     })
  28.     if err := e.Start(":8080"); err != nil && !errors.Is(err, http.ErrServerClosed) {
  29.         log.Fatal(err)
  30.     }
  31. }

Complex Scenarios

Example: modify default echoprometheus metrics definitions

  1. package main
  3. import (
  4.     "errors"
  5.     "github.com/labstack/echo-contrib/echoprometheus"
  6.     "github.com/labstack/echo/v4"
  7.     "github.com/prometheus/client_golang/prometheus"
  8.     "log"
  9.     "net/http"
  10. )
  12. func main() {
  13.     e := echo.New()
  15.     e.Use(echoprometheus.NewMiddlewareWithConfig(echoprometheus.MiddlewareConfig{
  16.         // labels of default metrics can be modified or added with `LabelFuncs` function
  17.         LabelFuncs: map[string]echoprometheus.LabelValueFunc{
  18.             "scheme": func(c echo.Context, err error) string { // additional custom label
  19.                 return c.Scheme()
  20.             },
  21.             "host": func(c echo.Context, err error) string { // overrides default 'host' label value
  22.                 return "y_" + c.Request().Host
  23.             },
  24.         },
  25.         // The `echoprometheus` middleware registers the following metrics by default:
  26.         // - Histogram: request_duration_seconds
  27.         // - Histogram: response_size_bytes
  28.         // - Histogram: request_size_bytes
  29.         // - Counter: requests_total
  30.         // which can be modified with `HistogramOptsFunc` and `CounterOptsFunc` functions
  31.         HistogramOptsFunc: func(opts prometheus.HistogramOpts) prometheus.HistogramOpts {
  32.             if opts.Name == "request_duration_seconds" {
  33.                 opts.Buckets = []float64{1000.0, 10_000.0, 100_000.0, 1_000_000.0} // 1KB ,10KB, 100KB, 1MB
  34.             }
  35.             return opts
  36.         },
  37.         CounterOptsFunc: func(opts prometheus.CounterOpts) prometheus.CounterOpts {
  38.             if opts.Name == "requests_total" {
  39.                 opts.ConstLabels = prometheus.Labels{"my_const": "123"}
  40.             }
  41.             return opts
  42.         },
  43.     })) // adds middleware to gather metrics
  45.     e.GET("/metrics", echoprometheus.NewHandler()) // adds route to serve gathered metrics
  47.     e.GET("/hello", func(c echo.Context) error {
  48.         return c.String(http.StatusOK, "hello")
  49.     })
  51.     if err := e.Start(":8080"); err != nil && !errors.Is(err, http.ErrServerClosed) {
  52.         log.Fatal(err)
  53.     }
  54. }