perf

Documentation

Overview

Package perf exposes application performance utilities.

Index

• func NewGrpcStatsHandler() stats.Handler
• func NewRoundTripperWithStats() http.RoundTripper
• func WrapHTTPHandlerForStats(h http.Handler) http.Handler
• type CloudOptions
• type Exporter
  • func NewCloudExporter(opts CloudOptions) (Exporter, error)
  • func NewDevelopmentExporter() Exporter

Examples

• NewGrpcStatsHandler
• NewRoundTripperWithStats
• WrapHTTPHandlerForStats

Functions

func NewGrpcStatsHandler

func NewGrpcStatsHandler() stats.Handler

NewGrpcStatsHandler creates a new stats handler writing to opencensus.

Example:

grpcServer, err := rpc.NewServer(logger, rpc.WithStatsHandler(perf.NewGrpcStatsHandler()))

See further documentation here: https://opencensus.io/guides/grpc/go/

Example

ExampleNewGrpcStatsHandler shows how to create a new gRPC server with intrumentation for metrics/spans.

logger := golog.NewDevelopmentLogger("perf-example")

// Create a new perf.Exporter that collects metrics/spans and exports them to the correct backend.
// For development we log to console but in production use `perf.NewCloudExporter()` to send them
// to GCP Cloud Monitoring (Stackdriver).
exporter := NewDevelopmentExporter()

// Create a gRPC server that is instrumented with metrics/spans collection.
serverOpts := []rpc.ServerOption{
	rpc.WithDebug(),
	// Add the stats handler to the gRPC server. Will capture rpc request counts, latency, bytes received.
	// See further documentation here: https://opencensus.io/guides/grpc/go/
	rpc.WithStatsHandler(NewGrpcStatsHandler()),
}
grpcServer, err := rpc.NewServer(logger, serverOpts...)
if err != nil {
	logger.Panic("failed to start grpc server")
}

// Start the exporting of metrics and spans.
exporter.Start()
// Don't forget to stop the collection once finished. Stop() will flush any pending metrics/spans.
defer exporter.Stop()

grpcServer.Stop()

func NewRoundTripperWithStats

func NewRoundTripperWithStats() http.RoundTripper

NewRoundTripperWithStats creates a new RoundTripper with stats collecting writing to opencensus.

Example:

client := &http.Client{Transport: perf.NewRoundTripperWithStats()},

Example

ExampleNewRoundTripperWithStats shows how to instrument a new HTTP client with metrics.

logger := golog.NewDevelopmentLogger("perf-example")
client := &http.Client{
	// Instrument the HTTP client with a new RoundTripper Transport that records the metrics/spans
	Transport: NewRoundTripperWithStats(),
}

res, err := client.Get("http://localhost:1234")
if err != nil {
	logger.Panic("failed to start grpc server")
}
defer res.Body.Close()

func WrapHTTPHandlerForStats

func WrapHTTPHandlerForStats(h http.Handler) http.Handler

WrapHTTPHandlerForStats wraps a http handler with stats collection writing to opencensus.

Example:

httpHandler := goji.NewMux()
hanlderWithStats = perf.WrapHTTPHandlerForStats(httpHandler)

Example

ExampleWrapHTTPHandlerForStats shows how to create a new HTTP server with intrumentation for metrics/spans.

ctx := context.Background()

// Create a new perf.Exporter that collects metrics/spans and exports them to the correct backend.
// For development we log to console but in production use `perf.NewCloudExporter()` to send them
// to GCP Cloud Monitoring (Stackdriver).
exporter := NewDevelopmentExporter()

// Create a HTTP server that is instrumented with metrics/spans collection.
httpServerExitDone := &sync.WaitGroup{}
mux := goji.NewMux()
mux.HandleFunc(pat.Get("/hello/:name"), func(w http.ResponseWriter, r *http.Request) {
	name := pat.Param(r, "name")
	fmt.Fprintf(w, "Hello, %s!", name)
})
srv := &http.Server{
	Addr: "localhost:0",
	// To instrument the HTTP server wrap the handler with `perf.WrapHTTPHandlerForStats()`.
	Handler: WrapHTTPHandlerForStats(mux),
}
go func() {
	defer httpServerExitDone.Done() // let main know we are done cleaning up

	// always returns error. ErrServerClosed on graceful close
	if err := srv.ListenAndServe(); err != http.ErrServerClosed {
		// unexpected error. port in use?
		log.Fatalf("ListenAndServe(): %v", err)
	}
}()

if err := srv.Shutdown(ctx); err != nil {
	panic(err) // failure/timeout shutting down the server gracefully
}
// wait for goroutine started in startHttpServer() to stop
httpServerExitDone.Wait()

// Start the exporting of metrics and spans.
exporter.Start()
// Don't forget to stop the collection once finished. Stop() will flush any pending metrics/spans.
defer exporter.Stop()

Types

type CloudOptions

type CloudOptions struct {
	Context      context.Context
	Logger       golog.Logger
	MetricPrefix string // Optional metric prefix.
}

CloudOptions are options for the production cloud exporter to Stackdriver (Cloud Monitoring).

type Exporter

type Exporter interface {
	// Start will start the exporting of metrics and return any errors if failed to start.
	Start() error
	// Stop will stop all exporting and flush remaining metrics.
	Stop()
}

Exporter wrapper around Trace and Metric exporter for OpenCensus.

func NewCloudExporter

func NewCloudExporter(opts CloudOptions) (Exporter, error)

NewCloudExporter creates a new Stackdriver (Cloud Monitoring) OpenCensus exporter with all options setup views registered..

func NewDevelopmentExporter

func NewDevelopmentExporter() Exporter

NewDevelopmentExporter creates a new exporter that outputs the console.