metrics

README

metrics: Auto Metrics

Overview

Package metrics provides a convenient way to add Prometheus metrics to Goa services. The following example shows how to use the package. It implements an illustrative main function for a fictional service svc implemented in the package github.com/repo/services/svc. The service is assumed to expose both HTTP and gRPC endpoints.

package main

import (
        "context"

        "goa.design/clue/metrics"
        "goa.design/clue/log"
        goahttp "goa.design/goa/v3/http"

        "github.com/repo/services/svc"
        httpsvrgen "github.com/repo/services/svc/gen/http/svc/server"
        grpcsvrgen "github.com/repo/services/svc/gen/grpc/svc/server"
        svcgen "github.com/repo/services/svc/gen/svc"
)

func main() {
        // Initialize the log context
        ctx := log.With(log.Context(context.Background()), "svc", svcgen.ServiceName)
        // Create the service (user code)
        svc := svc.New(ctx)
        // Wrap the service with Goa endpoints
        endpoints := svcgen.NewEndpoints(svc)

        // Create HTTP server
        mux := goahttp.NewMuxer()
        httpsvr := httpsvrgen.New(endpoints, mux, goahttp.RequestDecoder, goahttp.ResponseEncoder, nil, nil)
        httpsvrgen.Mount(mux, httpsvr)

        // ** Initialize context for metrics **
        ctx = metrics.Context(ctx, svcgen.ServiceName)

        // ** metrics HTTP endpoints **
        handler := metrics.HTTP(ctx)(mux)

        // Create gRPC server
        grpcsvr := grpcsvrgen.New(endpoints, nil)

        // ** metrics gRPC endpoints **
        unaryInterceptor := metrics.UnaryServerInterceptor(ctx)
        streamInterceptor := metrics.StreamServerInterceptor(ctx)
        pbsvr := grpc.NewServer(grpc.UnaryInterceptor(unaryInterceptor), grpc.StreamInterceptor(streamInterceptor))

        // ** Mount the /metrics handler used by Prometheus to scrape metrics **
        mux.Handle("GET", "/metrics", metrics.Handler(ctx).ServeHTTP)

        // .... Start the servers ....
}

The metrics functions used to instrument the service are:

• HTTP: creates a middleware that meters an HTTP handler.
• UnaryServerInterceptor: creates an interceptor that meters gRPC unary server methods.
• StreamServerInterceptor: creates an interceptor that meters gRPC stream server methods.
• Handler: creates a HTTP handler that exposes Prometheus metrics.

HTTP Metrics

The middleware returned by the HTTP function creates the following metrics:

• http_server_duration: Histogram of HTTP request durations in milliseconds.
• http_server_active_requests: Gauge of active HTTP requests.
• http_server_request_size: Histogram of HTTP request sizes in bytes.
• http_server_response_size: Histogram of HTTP response sizes in bytes.

All the metrics have the following labels:

• goa_service: The service name as specified in the Goa design.
• http_verb: The HTTP verb (GET, POST etc.).
• http_host: The value of the HTTP host header.
• http_path: The HTTP path.

All the metrics but http_server_active_requests also have the following additional labels:

• http_status_code: The HTTP status code.

GRPC Metrics

The UnaryInterceptor and StreamInterceptor functions create the following metrics:

• rpc_server_duration: Histogram of unary request durations in milliseconds.
• rpc_server_active_requests: Gauge of active unary and stream requests.
• rpc_server_request_size: Histogram of message sizes in bytes, per message for streaming RPCs.
• rpc_server_response_size: Histogram of response sizes in bytes, per message for streaming RPCs.
• rpc_server_stream_message_size: Histogram of message sizes in bytes, per message for streaming RPCs.
• rpc_server_stream_response_size: Histogram of response sizes in bytes, per message for streaming RPCs.

All the metrics have the following labels:

• goa_service: The service name as specified in the Goa design.
• net_peer.addr: The peer address.
• rpc_method: Full name of RPC method.

All the metrics but rpc_server_active_requests, rpc_server_stream_message_size and rpc_rpc_server_stream_response_size also have the following additional labels:

• rpc_status_code: The response status code.

Configuration

Histogram Buckets

The histogram buckets can be specified using the WithDurationBuckets, WithRequestSizeBuckets and WithResponseSizeBuckets options of the Context function:

ctx = metrics.Context(ctx, svc.ServiceName,
        metrics.WithDurationBuckets([]float64{.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10}),
        metrics.WithRequestSizeBuckets([]float64{1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024}),
        metrics.WithResponseSizeBuckets([]float64{1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024}))

The default bucket upper boundaries are:

• 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, +Inf for request duration.
• 10, 100, 500, 1000, 5000, 10000, 50000, 100000, 1000000, 10000000, +Inf for request and response size.

Prometheus Registry

By default metrics uses the global Prometheus registry to create the metrics and serve them. A user configured registerer can be specified when creating the metrics via WithRegisterer:

ctx = metrics.Context(ctx, svc.ServiceName, metrics.WithRegisterer(registerer))(mux)

A user configured gatherer (used to collect the metrics) and registerer (used to register metrics for the /metrics endpoint) can be specified when creating the metrics handler via WithGatherer and WithHandlerRegisterer respectively:

handler = metrics.Handler(ctx, metrics.WithGatherer(gatherer), metrics.WithHandlerRegisterer(registerer))

Documentation

Index

• Variables
• func Context(ctx context.Context, svc string, opts ...Option) context.Context
• func HTTP(ctx context.Context) func(http.Handler) http.Handler
• func Handler(ctx context.Context, opts ...handlerOption) http.Handler
• func StreamServerInterceptor(ctx context.Context) grpc.StreamServerInterceptor
• func UnaryServerInterceptor(ctx context.Context) grpc.UnaryServerInterceptor
• func WithGatherer(gatherer prometheus.Gatherer) handlerOption
• func WithHandlerRegisterer(registerer prometheus.Registerer) handlerOption
• type Option
  • func WithDurationBuckets(buckets []float64) Option
  • func WithRegisterer(registerer prometheus.Registerer) Option
  • func WithRequestSizeBuckets(buckets []float64) Option
  • func WithResponseSizeBuckets(buckets []float64) Option
  • func WithRouteResolver(resolver RouteResolver) Option
• type RouteResolver

Variables

var (
	DefaultDurationBuckets     = []float64{10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000}
	DefaultRequestSizeBuckets  = []float64{10, 100, 500, 1000, 5000, 10000, 50000, 100000, 1000000, 10000000}
	DefaultResponseSizeBuckets = []float64{10, 100, 500, 1000, 5000, 10000, 50000, 100000, 1000000, 10000000}
)

Functions

func Context

func Context(ctx context.Context, svc string, opts ...Option) context.Context

Context initializes the given context for the HTTP, UnaryInterceptor and StreamInterceptor functions.

func HTTP

func HTTP(ctx context.Context) func(http.Handler) http.Handler

HTTP returns a middlware that metricss requests. The context must have been initialized with Context. HTTP collects the following metrics:

• `http.server.duration`: Histogram of request durations in milliseconds.
• `http.server.active_requests`: UpDownCounter of active requests.
• `http.server.request.size`: Histogram of request sizes in bytes.
• `http.server.response.size`: Histogram of response sizes in bytes.

All the metrics have the following labels:

• `http.verb`: The HTTP verb (`GET`, `POST` etc.).
• `http.host`: The value of the HTTP host header.
• `http.path`: The HTTP path.
• `http.status_code`: The HTTP status code.

Errors collecting or serving metrics are logged to the logger in the context if any.

func Handler

func Handler(ctx context.Context, opts ...handlerOption) http.Handler

Handler returns a HTTP handler that collect metrics and serves them using the Prometheus export formats. It uses the context logger configured via micro/log if any to log errors. By default Handler uses the default prometheus registry to gather metrics and to register its own metrics. Use options WithGatherer and WithHandlerRegisterer to override the default values.

func StreamServerInterceptor

func StreamServerInterceptor(ctx context.Context) grpc.StreamServerInterceptor

StreamServerInterceptor creates a gRPC stream server interceptor that metricss the requests. The context must have been initialized with Context. The returned interceptor adds the following metrics:

• `grpc.server.active_requests`: UpDownCounter of active requests.
• `grpc.server.request.size`: Histogram of request sizes in bytes.
• `grpc.server.response.size`: Histogram of response sizes in bytes.

All the metrics have the following labels:

• `goa.method`: The method name as specified in the Goa design.
• `goa.service`: The service name as specified in the Goa design.
• `net.peer.name`: The peer name.
• `rpc.system`: A stream identifying the remoting system (e.g. `grpc`).
• `rpc.service`: Name of RPC service.
• `rpc.method`: Name of RPC method.
• `rpc.status_code`: The response status code.

Errors collecting or serving metrics are logged to the logger in the context if any.

func UnaryServerInterceptor

func UnaryServerInterceptor(ctx context.Context) grpc.UnaryServerInterceptor

UnaryServerInterceptor creates a gRPC unary server interceptor that metricss the requests. The context must have been initialized with metrics.Context. The returned interceptor adds the following metrics:

• `grpc.server.duration`: Histogram of request durations in milliseconds.
• `grpc.server.active_requests`: UpDownCounter of active requests.
• `grpc.server.request.size`: Histogram of request sizes in bytes.
• `grpc.server.response.size`: Histogram of response sizes in bytes.

All the metrics have the following labels:

• `goa.method`: The method name as specified in the Goa design.
• `goa.service`: The service name as specified in the Goa design.
• `net.peer.name`: The peer name.
• `rpc.system`: A stream identifying the remoting system (e.g. `grpc`).
• `rpc.service`: Name of RPC service.
• `rpc.method`: Name of RPC method.
• `rpc.status_code`: The response status code.

Errors collecting or serving metrics are logged to the logger in the context if any.

func WithGatherer

func WithGatherer(gatherer prometheus.Gatherer) handlerOption

WithGatherer returns an option that sets the prometheus gatherer used to collect the metrics.

func WithHandlerRegisterer

func WithHandlerRegisterer(registerer prometheus.Registerer) handlerOption

WithHandlerRegisterer returns an option that sets the prometheus registerer.

Types

type Option

type Option func(*options)

Option is a function that configures the metricsation.

func WithDurationBuckets

func WithDurationBuckets(buckets []float64) Option

WithDurationBuckets returns an option that sets the duration buckets for the request duration histogram.

func WithRegisterer

func WithRegisterer(registerer prometheus.Registerer) Option

WithRegisterer returns an option that sets the prometheus registerer.

func WithRequestSizeBuckets

func WithRequestSizeBuckets(buckets []float64) Option

WithRequestSizeBuckets returns an option that sets the request size buckets for the request size histogram.

func WithResponseSizeBuckets

func WithResponseSizeBuckets(buckets []float64) Option

WithResponseSizeBuckets returns an option that sets the response size buckets for the response size histogram.

func WithRouteResolver

func WithRouteResolver(resolver RouteResolver) Option

WithRouteResolver returns an option that sets the route resolver used to label metrics. The default uses the request path.

type RouteResolver

type RouteResolver func(r *http.Request) string

RouteResolver is a function that resolves the route of a request used to label metrics. Using a route resolver makes it possible to label all routes matching a pattern with the same label. As an example services using the github.com/dimfled/httptreemux muxer can use httptreemux.ContexRoute(r.Context()).