connect_go_prometheus

README

connect-go-prometheus

Prometheus monitoring for connect-go.

Interceptors

This library defines interceptors to observe both client-side and server-side calls.

Install

go get -u github.com/easyCZ/connect-go-prometheus

Usage

import (
    "github.com/easyCZ/connect-go-prometheus"
)

// Construct the interceptor. The same intereceptor is used for both client-side and server-side.
interceptor := connect_go_prometheus.NewInterceptor()

// Use the interceptor when constructing a new connect-go handler
_, _ := your_connect_package.NewServiceHandler(handler, connect.WithInterceptors(interceptor))

// Or with a client
client := your_connect_package.NewServiceClient(http.DefaultClient, serverURL, connect.WithInterceptors(interceptor))

For configuration, and more advanced use cases see Configuration

Metrics

Metrics exposed use the following labels:

• type - one of unary, client_stream, server_stream or bidi
• service - name of the service, for example myservice.greet.v1
• method - name of the method, for example SayHello
• code - the resulting outcome of the RPC. The codes match connect-go Error Codes with the addition of ok for succesful RPCs.

Server-side metrics

• Counter connect_server_started_total with (type, service, method) labels
• Counter connect_server_handled_total with (type, service, method, code) labels
• (optionally) Histogram connect_server_handled_seconds with (type, service, method, code) labels

Client-side metrics

• Counter connect_client_started_total with (type, service, method) labels
• Counter connect_client_handled_total with (type, service, method, code) labels
• (optionally) Histogram connect_client_handled_seconds with (type, service, method, code) labels

Configuration

Customizing client/server metrics reported

import (
    "github.com/easyCZ/connect-go-prometheus"
    prom "github.com/prometheus/client_golang/prometheus"
)

options := []connect_go_prometheus.MetricOption{
    connect_go_prometheus.WithHistogram(true),
    connect_go_prometheus.WithNamespace("namespace"),
    connect_go_prometheus.WithSubsystem("subsystem"),
    connect_go_prometheus.WithConstLabels(prom.Labels{"component": "foo"}),
    connect_go_prometheus.WithHistogramBuckets([]float64{1, 5}),
}

// Construct client metrics
clientMetrics := connect_go_prometheus.NewClientMetrics(options...)

// Construct server metrics
serverMetrics := connect_go_prometheus.NewServerMetrics(options...)

// When you construct either client/server metrics with options, you must also register the metrics with your Prometheus Registry
prom.MustRegister(clientMetrics, serverMetrics)

// Construct the interceptor with our configured metrics
interceptor := connect_go_prometheus.NewInterceptor(
    connect_go_prometheus.WithClientMetrics(clientMetrics),
    connect_go_prometheus.WithServerMetrics(serverMetrics),
)

Registering metrics against a Registry

You may want to register metrics against a Prometheus Registry. You can do this with the following:

import (
    "github.com/easyCZ/connect-go-prometheus"
    prom "github.com/prometheus/client_golang/prometheus"
)

clientMetrics := connect_go_prometheus.NewClientMetrics()
serverMetrics := connect_go_prometheus.NewServerMetrics()

registry := prom.NewRegistry()
registry.MustRegister(clientMetrics, serverMetrics)

interceptor := connect_go_prometheus.NewInterceptor(
    connect_go_prometheus.WithClientMetrics(clientMetrics),
    connect_go_prometheus.WithServerMetrics(serverMetrics),
)

Disabling client/server metrics reporting

To disable reporting of either client or server metrics, pass nil as an option.

import (
    "github.com/easyCZ/connect-go-prometheus"
)

// Disable client-side metrics
interceptor := connect_go_prometheus.NewInterceptor(
    connect_go_prometheus.WithClientMetrics(nil),
)

// Disable server-side metrics
interceptor := connect_go_prometheus.NewInterceptor(
    connect_go_prometheus.WithServerMetrics(nil),
)

Documentation

Index

• Variables
• type Interceptor
  • func NewInterceptor(opts ...InterecptorOption) *Interceptor
  • func (i *Interceptor) WrapStreamingClient(connect.StreamingClientFunc) connect.StreamingClientFunc
  • func (i *Interceptor) WrapStreamingHandler(connect.StreamingHandlerFunc) connect.StreamingHandlerFunc
  • func (i *Interceptor) WrapUnary(next connect.UnaryFunc) connect.UnaryFunc
• type InterecptorOption
  • func WithClientMetrics(m *Metrics) InterecptorOption
  • func WithServerMetrics(m *Metrics) InterecptorOption
• type Metrics
  • func NewClientMetrics(opts ...MetricsOption) *Metrics
  • func NewServerMetrics(opts ...MetricsOption) *Metrics
  • func (m *Metrics) Collect(c chan<- prom.Metric)
  • func (m *Metrics) Describe(c chan<- *prom.Desc)
  • func (m *Metrics) ReportHandled(callType, service, method, code string)
  • func (m *Metrics) ReportHandledSeconds(callType, service, method, code string, val float64)
  • func (m *Metrics) ReportStarted(callType, service, method string)
• type MetricsOption
  • func WithConstLabels(labels prom.Labels) MetricsOption
  • func WithHistogram(enabled bool) MetricsOption
  • func WithHistogramBuckets(buckets []float64) MetricsOption
  • func WithNamespace(namespace string) MetricsOption
  • func WithSubsystem(subsystem string) MetricsOption

Variables

var (
	DefaultClientMetrics = NewClientMetrics()
	DefaultServerMetrics = NewServerMetrics()
)

Types

type Interceptor

type Interceptor struct {
	// contains filtered or unexported fields
}

func NewInterceptor

func NewInterceptor(opts ...InterecptorOption) *Interceptor

func (*Interceptor) WrapStreamingClient

func (i *Interceptor) WrapStreamingClient(connect.StreamingClientFunc) connect.StreamingClientFunc

func (*Interceptor) WrapStreamingHandler

func (i *Interceptor) WrapStreamingHandler(connect.StreamingHandlerFunc) connect.StreamingHandlerFunc

func (*Interceptor) WrapUnary

func (i *Interceptor) WrapUnary(next connect.UnaryFunc) connect.UnaryFunc

type InterecptorOption

type InterecptorOption func(*interceptorOptions)

func WithClientMetrics

func WithClientMetrics(m *Metrics) InterecptorOption

func WithServerMetrics

func WithServerMetrics(m *Metrics) InterecptorOption

type Metrics

type Metrics struct {
	// contains filtered or unexported fields
}

func NewClientMetrics

func NewClientMetrics(opts ...MetricsOption) *Metrics

func NewServerMetrics

func NewServerMetrics(opts ...MetricsOption) *Metrics

NewServerMetrics creates new Connect metrics for server-side handling.

func (*Metrics) Collect

func (m *Metrics) Collect(c chan<- prom.Metric)

Collect implements collect as required by prom.Collector

func (*Metrics) Describe

func (m *Metrics) Describe(c chan<- *prom.Desc)

Describe implements Describe as required by prom.Collector

func (*Metrics) ReportHandled

func (m *Metrics) ReportHandled(callType, service, method, code string)

func (*Metrics) ReportHandledSeconds

func (m *Metrics) ReportHandledSeconds(callType, service, method, code string, val float64)

func (*Metrics) ReportStarted

func (m *Metrics) ReportStarted(callType, service, method string)

type MetricsOption

type MetricsOption func(opts *metricsOptions)

func WithConstLabels

func WithConstLabels(labels prom.Labels) MetricsOption

func WithHistogram

func WithHistogram(enabled bool) MetricsOption

func WithHistogramBuckets

func WithHistogramBuckets(buckets []float64) MetricsOption

func WithNamespace

func WithNamespace(namespace string) MetricsOption

func WithSubsystem

func WithSubsystem(subsystem string) MetricsOption