perf

Documentation

Overview

Package perf exposes application performance utilities.

Index

• func NewGrpcStatsHandler() stats.Handler
• func NewMongoDBMonitor(opts ...MongoDBMonitorOption) *event.CommandMonitor
• func NewMongoDBPoolMonitor() *event.PoolMonitor
• func NewRoundTripperWithStats() http.RoundTripper
• func WrapHTTPHandlerForStats(h http.Handler) http.Handler
• type CloudOptions
• type DevelopmentExporterOptions
• type Exporter
  • func NewCloudExporter(opts CloudOptions) (Exporter, error)
  • func NewDevelopmentExporter() Exporter
  • func NewDevelopmentExporterWithOptions(options DevelopmentExporterOptions) Exporter
• type MongoDBMonitorOption
  • func WithMongoDBMonitorSampler(sampler trace.Sampler) MongoDBMonitorOption
• type OtelDevelopmentExporter
  • func NewOtelDevelopmentExporter() *OtelDevelopmentExporter
  • func NewOtelDevelopmentExporterWithOptions(options OtelDevelopmentExporterOptions) *OtelDevelopmentExporter
  • func (e *OtelDevelopmentExporter) Close()
  • func (e *OtelDevelopmentExporter) ExportMetrics(ctx context.Context, metrics []*metricdata.Metric) error
  • func (e *OtelDevelopmentExporter) ExportOTLPSpans(ctx context.Context, spans []*tracepb.Span) error
  • func (e *OtelDevelopmentExporter) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error
  • func (e *OtelDevelopmentExporter) Shutdown(ctx context.Context) error
  • func (e *OtelDevelopmentExporter) Start() error
  • func (e *OtelDevelopmentExporter) Stop()
• type OtelDevelopmentExporterOptions

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 NewMongoDBMonitor

func NewMongoDBMonitor(opts ...MongoDBMonitorOption) *event.CommandMonitor

NewMongoDBMonitor creates a new mongodb event CommandMonitor.

func NewMongoDBPoolMonitor

func NewMongoDBPoolMonitor() *event.PoolMonitor

NewMongoDBPoolMonitor creates a new mongodb pool event PoolMonitor.

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       utils.ZapCompatibleLogger
	MetricPrefix string // Optional metric prefix.
}

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

type DevelopmentExporterOptions

type DevelopmentExporterOptions struct {
	// ReportingInterval is a time interval between two successive metrics
	// export.
	ReportingInterval time.Duration

	// MetricsDisabled determines if metrics reporting is disabled or not.
	MetricsDisabled bool

	// TracesDisabled determines if trace reporting is disabled or not.
	TracesDisabled bool
}

DevelopmentExporterOptions provides options for DevelopmentExporter.

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 log exporter.

func NewDevelopmentExporterWithOptions

func NewDevelopmentExporterWithOptions(options DevelopmentExporterOptions) Exporter

NewDevelopmentExporterWithOptions creates a new log exporter with the given options.

type MongoDBMonitorOption

type MongoDBMonitorOption func(*config)

MongoDBMonitorOption represents an option that can be passed to NewMongoDBMonitor.

func WithMongoDBMonitorSampler

func WithMongoDBMonitorSampler(sampler trace.Sampler) MongoDBMonitorOption

WithMongoDBMonitorSampler set a sampler for all started spans.

type OtelDevelopmentExporter

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

OtelDevelopmentExporter exports metrics and spans to log file.

func NewOtelDevelopmentExporter

func NewOtelDevelopmentExporter() *OtelDevelopmentExporter

NewOtelDevelopmentExporter creates a new log exporter.

func NewOtelDevelopmentExporterWithOptions

func NewOtelDevelopmentExporterWithOptions(options OtelDevelopmentExporterOptions) *OtelDevelopmentExporter

NewOtelDevelopmentExporterWithOptions creates a new log exporter with the given options.

func (*OtelDevelopmentExporter) Close

func (e *OtelDevelopmentExporter) Close()

Close closes any files that were opened for logging.

func (*OtelDevelopmentExporter) ExportMetrics

func (e *OtelDevelopmentExporter) ExportMetrics(ctx context.Context, metrics []*metricdata.Metric) error

ExportMetrics exports to log.

func (*OtelDevelopmentExporter) ExportOTLPSpans

func (e *OtelDevelopmentExporter) ExportOTLPSpans(ctx context.Context, spans []*tracepb.Span) error

ExportOTLPSpans displays spans that have already been serialized in OTLP format.

func (*OtelDevelopmentExporter) ExportSpans

func (e *OtelDevelopmentExporter) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error

ExportSpans implements sdktrace.SpanExporter.

func (*OtelDevelopmentExporter) Shutdown

func (e *OtelDevelopmentExporter) Shutdown(ctx context.Context) error

Shutdown implements sdktrace.SpanExporter.

func (*OtelDevelopmentExporter) Start

func (e *OtelDevelopmentExporter) Start() error

Start starts the metric and span data exporter.

func (*OtelDevelopmentExporter) Stop

func (e *OtelDevelopmentExporter) Stop()

Stop stops the metric and span data exporter.

type OtelDevelopmentExporterOptions

type OtelDevelopmentExporterOptions struct {
	// ReportingInterval is a time interval between two successive metrics
	// export.
	ReportingInterval time.Duration

	// MetricsDisabled determines if metrics reporting is disabled or not.
	MetricsDisabled bool

	// TracesDisabled determines if trace reporting is disabled or not.
	TracesDisabled bool

	// Out sets the [io.Writer] that formatted traces will be written to. If this
	// is nil then [os.Stdout] will be used.
	Out io.Writer
}

OtelDevelopmentExporterOptions provides options for OtelDevelopmentExporter.