README
¶
httpserver
Basic instrumented HTTP server that I found myself writing over and over again.
Documentation
Authors
- Christophe Lambin
License
This project is licensed under the MIT License - see the LICENSE.md file for details.
Documentation
¶
Overview ¶
Package httpserver provides a standard way of writing an HTTP server. It supports:
1. Creating an HTTP Server listening on a static or dynamic port 2. Running a Prometheus metrics server 3. Creating an HTTP Server with one or more HTTP handlers 4. Recording Prometheus metrics for latency (average or quantiles) & number of requests.
Example ¶
package main
import (
"github.com/clambin/go-common/httpserver"
"github.com/prometheus/client_golang/prometheus"
"net/http"
)
func main() {
metrics := httpserver.NewAvgMetrics("example")
prometheus.MustRegister(metrics)
s, err := httpserver.New(
httpserver.WithPort{Port: 8080},
httpserver.WithPrometheus{},
httpserver.WithMetrics{Metrics: metrics},
httpserver.WithHandlers{Handlers: []httpserver.Handler{{
Path: "/",
Methods: []string{http.MethodGet},
Handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
_, _ = w.Write([]byte("Hello world"))
}),
}},
},
)
if err != nil {
err = s.Run()
}
if err != nil {
panic(err)
}
}
Index ¶
- type AvgMetrics
- func (m *AvgMetrics) Collect(ch chan<- prometheus.Metric)
- func (m *AvgMetrics) Describe(ch chan<- *prometheus.Desc)
- func (m *AvgMetrics) GetRequestCountMetric(method, path string, statusCode int) prometheus.Counter
- func (m *AvgMetrics) GetRequestDurationMetric(method, path string) prometheus.Observer
- type Handler
- type Metrics
- type Option
- type SLOMetrics
- func (m *SLOMetrics) Collect(ch chan<- prometheus.Metric)
- func (m *SLOMetrics) Describe(ch chan<- *prometheus.Desc)
- func (m *SLOMetrics) GetRequestCountMetric(method, path string, statusCode int) prometheus.Counter
- func (m *SLOMetrics) GetRequestDurationMetric(method, path string) prometheus.Observer
- type Server
- type WithHandlers
- type WithMetrics
- type WithPort
- type WithPrometheus
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AvgMetrics ¶
type AvgMetrics struct {
// contains filtered or unexported fields
}
AvgMetrics uses a Summary to record request duration metrics. Use this if you are only interested in the average time to service requests.
func (*AvgMetrics) Collect ¶
func (m *AvgMetrics) Collect(ch chan<- prometheus.Metric)
func (*AvgMetrics) Describe ¶
func (m *AvgMetrics) Describe(ch chan<- *prometheus.Desc)
func (*AvgMetrics) GetRequestCountMetric ¶
func (m *AvgMetrics) GetRequestCountMetric(method, path string, statusCode int) prometheus.Counter
GetRequestCountMetric returns the Counter to record request count
func (*AvgMetrics) GetRequestDurationMetric ¶
func (m *AvgMetrics) GetRequestDurationMetric(method, path string) prometheus.Observer
GetRequestDurationMetric returns the Observer to record request duration
type Handler ¶
type Handler struct {
// Path of the endpoint (e.g. "/health"). Can be any path that's valid for gorilla/mux router's Path().
Path string
// Handler that implements the endpoint
Handler http.Handler
// Methods that the handler should support. If empty, defaults to http.MethodGet
Methods []string
}
Handler contains an endpoint to be registered in the Server's HTTP server
type Metrics ¶
type Metrics interface {
GetRequestDurationMetric(method, path string) prometheus.Observer
GetRequestCountMetric(method, path string, statusCode int) prometheus.Counter
prometheus.Collector
}
Metrics interface contains the methods httpserver's middleware expects to record performance metrics
func NewAvgMetrics ¶
NewAvgMetrics creates a new AvgMetrics.
func NewSLOMetrics ¶
NewSLOMetrics creates a new SLOMetrics, where latency is measured using a histogram with the provided list of buckets. If the list is empty, NewSLOMetrics will use prometheus.DefBuckets.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option specified configuration options for Server
type SLOMetrics ¶
type SLOMetrics struct {
// contains filtered or unexported fields
}
SLOMetrics uses a histogram to record request duration metrics. Use this to measure an SLO (e.g. 95% of all requests must be serviced below x seconds). SLOMetrics uses Prometheus' default buckets.
func (*SLOMetrics) Collect ¶
func (m *SLOMetrics) Collect(ch chan<- prometheus.Metric)
func (*SLOMetrics) Describe ¶
func (m *SLOMetrics) Describe(ch chan<- *prometheus.Desc)
func (*SLOMetrics) GetRequestCountMetric ¶
func (m *SLOMetrics) GetRequestCountMetric(method, path string, statusCode int) prometheus.Counter
GetRequestCountMetric returns the Counter to record request count
func (*SLOMetrics) GetRequestDurationMetric ¶
func (m *SLOMetrics) GetRequestDurationMetric(method, path string) prometheus.Observer
GetRequestDurationMetric returns the Observer to record request duration
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server implements a configurable HTTP Server. See the different WithXXX structs for available options.
type WithHandlers ¶
type WithHandlers struct {
Handlers []Handler
}
WithHandlers adds the specified handlers to the server
type WithMetrics ¶
type WithMetrics struct {
Metrics Metrics
}
WithMetrics will collect the specified metrics to instrument the Server's Handlers.
type WithPort ¶
type WithPort struct {
Port int
}
WithPort specifies the Server's listening port. If no port is specified, Server will listen on a random port. Use GetPort() to determine the actual listening port
type WithPrometheus ¶
type WithPrometheus struct {
Path string
}
WithPrometheus adds a Prometheus metrics endpoint to the server at the specified Path. Default path is "/metrics"
Source Files