go.opencensus.iogo.opencensus.io/plugin/ocgrpc Index | Examples | Files

package ocgrpc

import "go.opencensus.io/plugin/ocgrpc"

Package ocgrpc contains OpenCensus stats and trace integrations for gRPC.

Use ServerHandler for servers and ClientHandler for clients.

Index

Examples

Variables

var (
	ClientErrorCount, _       = stats.Int64("grpc.io/client/error_count", "RPC Errors", stats.UnitNone)
	ClientRequestBytes, _     = stats.Int64("grpc.io/client/request_bytes", "Request bytes", stats.UnitBytes)
	ClientResponseBytes, _    = stats.Int64("grpc.io/client/response_bytes", "Response bytes", stats.UnitBytes)
	ClientStartedCount, _     = stats.Int64("grpc.io/client/started_count", "Number of client RPCs (streams) started", stats.UnitNone)
	ClientFinishedCount, _    = stats.Int64("grpc.io/client/finished_count", "Number of client RPCs (streams) finished", stats.UnitNone)
	ClientRequestCount, _     = stats.Int64("grpc.io/client/request_count", "Number of client RPC request messages", stats.UnitNone)
	ClientResponseCount, _    = stats.Int64("grpc.io/client/response_count", "Number of client RPC response messages", stats.UnitNone)
	ClientRoundTripLatency, _ = stats.Float64("grpc.io/client/roundtrip_latency", "RPC roundtrip latency in msecs", stats.UnitMilliseconds)
)

The following variables are measures are recorded by ClientHandler:

var (
	ClientErrorCountView = &view.View{
		Name:        "grpc.io/client/error_count",
		Description: "RPC Errors",
		TagKeys:     []tag.Key{KeyStatus, KeyMethod},
		Measure:     ClientErrorCount,
		Aggregation: view.MeanAggregation{},
	}

	ClientRoundTripLatencyView = &view.View{
		Name:        "grpc.io/client/roundtrip_latency",
		Description: "Latency in msecs",
		TagKeys:     []tag.Key{KeyMethod},
		Measure:     ClientRoundTripLatency,
		Aggregation: DefaultMillisecondsDistribution,
	}

	ClientRequestBytesView = &view.View{
		Name:        "grpc.io/client/request_bytes",
		Description: "Request bytes",
		TagKeys:     []tag.Key{KeyMethod},
		Measure:     ClientRequestBytes,
		Aggregation: DefaultBytesDistribution,
	}

	ClientResponseBytesView = &view.View{
		Name:        "grpc.io/client/response_bytes",
		Description: "Response bytes",
		TagKeys:     []tag.Key{KeyMethod},
		Measure:     ClientResponseBytes,
		Aggregation: DefaultBytesDistribution,
	}

	ClientRequestCountView = &view.View{
		Name:        "grpc.io/client/request_count",
		Description: "Count of request messages per client RPC",
		TagKeys:     []tag.Key{KeyMethod},
		Measure:     ClientRequestCount,
		Aggregation: DefaultMessageCountDistribution,
	}

	ClientResponseCountView = &view.View{
		Name:        "grpc.io/client/response_count",
		Description: "Count of response messages per client RPC",
		TagKeys:     []tag.Key{KeyMethod},
		Measure:     ClientResponseCount,
		Aggregation: DefaultMessageCountDistribution,
	}
)

Predefined views may be subscribed to collect data for the above measures. As always, you may also define your own custom views over measures collected by this package. These are declared as a convenience only; none are subscribed by default.

var (
	ServerErrorCount, _        = stats.Int64("grpc.io/server/error_count", "RPC Errors", stats.UnitNone)
	ServerServerElapsedTime, _ = stats.Float64("grpc.io/server/server_elapsed_time", "Server elapsed time in msecs", stats.UnitMilliseconds)
	ServerRequestBytes, _      = stats.Int64("grpc.io/server/request_bytes", "Request bytes", stats.UnitBytes)
	ServerResponseBytes, _     = stats.Int64("grpc.io/server/response_bytes", "Response bytes", stats.UnitBytes)
	ServerStartedCount, _      = stats.Int64("grpc.io/server/started_count", "Number of server RPCs (streams) started", stats.UnitNone)
	ServerFinishedCount, _     = stats.Int64("grpc.io/server/finished_count", "Number of server RPCs (streams) finished", stats.UnitNone)
	ServerRequestCount, _      = stats.Int64("grpc.io/server/request_count", "Number of server RPC request messages", stats.UnitNone)
	ServerResponseCount, _     = stats.Int64("grpc.io/server/response_count", "Number of server RPC response messages", stats.UnitNone)
)

The following variables are measures are recorded by ServerHandler:

var (
	ServerErrorCountView = &view.View{
		Name:        "grpc.io/server/error_count",
		Description: "RPC Errors",
		TagKeys:     []tag.Key{KeyMethod, KeyStatus},
		Measure:     ServerErrorCount,
		Aggregation: view.CountAggregation{},
	}

	ServerServerElapsedTimeView = &view.View{
		Name:        "grpc.io/server/server_elapsed_time",
		Description: "Server elapsed time in msecs",
		TagKeys:     []tag.Key{KeyMethod},
		Measure:     ServerServerElapsedTime,
		Aggregation: DefaultMillisecondsDistribution,
	}

	ServerRequestBytesView = &view.View{
		Name:        "grpc.io/server/request_bytes",
		Description: "Request bytes",
		TagKeys:     []tag.Key{KeyMethod},
		Measure:     ServerRequestBytes,
		Aggregation: DefaultBytesDistribution,
	}

	ServerResponseBytesView = &view.View{
		Name:        "grpc.io/server/response_bytes",
		Description: "Response bytes",
		TagKeys:     []tag.Key{KeyMethod},
		Measure:     ServerResponseBytes,
		Aggregation: DefaultBytesDistribution,
	}

	ServerRequestCountView = &view.View{
		Name:        "grpc.io/server/request_count",
		Description: "Count of request messages per server RPC",
		TagKeys:     []tag.Key{KeyMethod},
		Measure:     ServerRequestCount,
		Aggregation: DefaultMessageCountDistribution,
	}

	ServerResponseCountView = &view.View{
		Name:        "grpc.io/server/response_count",
		Description: "Count of response messages per server RPC",
		TagKeys:     []tag.Key{KeyMethod},
		Measure:     ServerResponseCount,
		Aggregation: DefaultMessageCountDistribution,
	}
)

Predefined views may be subscribed to collect data for the above measures. As always, you may also define your own custom views over measures collected by this package. These are declared as a convenience only; none are subscribed by default.

var (
	DefaultBytesDistribution        = view.DistributionAggregation{0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296}
	DefaultMillisecondsDistribution = view.DistributionAggregation{0, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000}
	DefaultMessageCountDistribution = view.DistributionAggregation{0, 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536}
)

The following variables define the default hard-coded auxiliary data used by both the default GRPC client and GRPC server metrics.

var (
	KeyMethod, _ = tag.NewKey("method")           // gRPC service and method name
	KeyStatus, _ = tag.NewKey("canonical_status") // Canonical status code
)
var DefaultClientViews = []*view.View{
	ClientErrorCountView,
	ClientRoundTripLatencyView,
	ClientRequestBytesView,
	ClientResponseBytesView,
	ClientRequestCountView,
	ClientResponseCountView,
}

DefaultClientViews are the default client views provided by this package.

var DefaultServerViews = []*view.View{
	ServerErrorCountView,
	ServerServerElapsedTimeView,
	ServerRequestBytesView,
	ServerResponseBytesView,
	ServerRequestCountView,
	ServerResponseCountView,
}

DefaultServerViews are the default server views provided by this package.

Types

type ClientHandler

type ClientHandler struct {
	// NoStats may be set to disable recording OpenCensus Stats around each
	// gRPC method.
	NoStats bool

	// StartOptions allows configuring the StartOptions used to create new spans.
	StartOptions trace.StartOptions
}

ClientHandler implements a gRPC stats.Handler for recording OpenCensus stats and traces. Use with gRPC clients only.

Example

Code:play 

package main

import (
	"log"

	"go.opencensus.io/plugin/ocgrpc"
	"go.opencensus.io/stats/view"
	"google.golang.org/grpc"
)

func main() {
	// Subscribe views to collect data.
	if err := view.Subscribe(ocgrpc.DefaultClientViews...); err != nil {
		log.Fatal(err)
	}

	// Set up a connection to the server with the OpenCensus
	// stats handler to enable stats and tracing.
	conn, err := grpc.Dial("address", grpc.WithStatsHandler(&ocgrpc.ClientHandler{}))
	if err != nil {
		log.Fatalf("did not connect: %v", err)
	}
	defer conn.Close()
}

func (*ClientHandler) HandleConn

func (c *ClientHandler) HandleConn(ctx context.Context, cs stats.ConnStats)

func (*ClientHandler) HandleRPC

func (c *ClientHandler) HandleRPC(ctx context.Context, rs stats.RPCStats)

HandleRPC implements per-RPC tracing and stats instrumentation.

func (*ClientHandler) TagConn

TagConn exists to satisfy gRPC stats.Handler.

func (*ClientHandler) TagRPC

TagRPC implements per-RPC context management.

type ServerHandler

type ServerHandler struct {
	// NoStats may be set to true to disable recording OpenCensus stats for RPCs.
	NoStats bool

	// IsPublicEndpoint may be set to true to always start a new trace around
	// each RPC. Any SpanContext in the RPC metadata will be added as a linked
	// span instead of making it the parent of the span created around the
	// server RPC.
	//
	// Be aware that if you leave this false (the default) on a public-facing
	// server, callers will be able to send tracing metadata in gRPC headers
	// and trigger traces in your backend.
	IsPublicEndpoint bool

	// StartOptions to use for to spans started around RPCs handled by this server.
	//
	// These will apply even if there is tracing metadata already
	// present on the inbound RPC but the SpanContext is not sampled. This
	// ensures that each service has some opportunity to be traced. If you would
	// like to not add any additional traces for this gRPC service, set:
	//   StartOptions.Sampler = trace.ProbabilitySampler(0.0)
	StartOptions trace.StartOptions
}

ServerHandler implements gRPC stats.Handler recording OpenCensus stats and traces. Use with gRPC servers.

When installed (see Example), tracing metadata is read from inbound RPCs by default. If no tracing metadata is present, or if the tracing metadata is present but the SpanContext isn't sampled, then a new trace may be started (as determined by Sampler).

Example

Code:play 

package main

import (
	"log"

	"go.opencensus.io/plugin/ocgrpc"
	"go.opencensus.io/stats/view"
	"google.golang.org/grpc"
)

func main() {
	// Subscribe to views to collect data.
	if err := view.Subscribe(ocgrpc.DefaultServerViews...); err != nil {
		log.Fatal(err)
	}

	// Set up a new server with the OpenCensus
	// stats handler to enable stats and tracing.
	s := grpc.NewServer(grpc.StatsHandler(&ocgrpc.ServerHandler{}))
	_ = s // use s
}

func (*ServerHandler) HandleConn

func (s *ServerHandler) HandleConn(ctx context.Context, cs stats.ConnStats)

HandleConn exists to satisfy gRPC stats.Handler.

func (*ServerHandler) HandleRPC

func (s *ServerHandler) HandleRPC(ctx context.Context, rs stats.RPCStats)

HandleRPC implements per-RPC tracing and stats instrumentation.

func (*ServerHandler) TagConn

TagConn exists to satisfy gRPC stats.Handler.

func (*ServerHandler) TagRPC

TagRPC implements per-RPC context management.

Source Files

client.go client_metrics.go client_stats_handler.go doc.go server.go server_metrics.go server_stats_handler.go stats_common.go trace_common.go

Version
v0.5.0
Published
Mar 18, 2018
Platform
js/wasm
Imports
15 packages
Last checked
58 minutes ago

Tools for package owners.