package ocgrpc

Import Path
	go.opencensus.io/plugin/ocgrpc (on go.dev)

Dependency Relation
	imports 16 packages, and imported by 2 packages

Involved Source Files

	      client.go
	      client_metrics.go
	      client_stats_handler.go
	   d➜ doc.go
		Package ocgrpc contains OpenCensus stats and trace
		integrations for gRPC.

		Use ServerHandler for servers and ClientHandler for clients.

	      server.go
	      server_metrics.go
	      server_stats_handler.go
	      stats_common.go
	      trace_common.go
Code Examples

	ClientHandler
		package main
		
		import (
			"go.opencensus.io/plugin/ocgrpc"
			"go.opencensus.io/stats/view"
			"google.golang.org/grpc"
			"log"
		)
		
		func main() {
			// Register views to collect data.
			if err := view.Register(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()
		}


	ServerHandler
		package main
		
		import (
			"go.opencensus.io/plugin/ocgrpc"
			"go.opencensus.io/stats/view"
			"google.golang.org/grpc"
			"log"
		)
		
		func main() {
			// Register views to collect data.
			if err := view.Register(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
		}


Package-Level Type Names (total 4, in which 2 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type ClientHandler (struct)
		ClientHandler implements a gRPC stats.Handler for recording OpenCensus stats and
		traces. Use with gRPC clients only.

		Fields (only one, which is exported)
			StartOptions trace.StartOptions
				StartOptions allows configuring the StartOptions used to create new spans.

				StartOptions.SpanKind will always be set to trace.SpanKindClient
				for spans started by this handler.

		Methods (total 6, in which 4 are exported)
			(*T) HandleConn(ctx context.Context, cs stats.ConnStats)
				HandleConn exists to satisfy gRPC stats.Handler.

			(*T) HandleRPC(ctx context.Context, rs stats.RPCStats)
				HandleRPC implements per-RPC tracing and stats instrumentation.

			(*T) TagConn(ctx context.Context, cti *stats.ConnTagInfo) context.Context
				TagConn exists to satisfy gRPC stats.Handler.

			(*T) TagRPC(ctx context.Context, rti *stats.RPCTagInfo) context.Context
				TagRPC implements per-RPC context management.

			/* 2 unexporteds ... *//* 2 unexporteds: */
			(*T) statsTagRPC(ctx context.Context, info *stats.RPCTagInfo) context.Context
				statsTagRPC gets the tag.Map populated by the application code, serializes
				its tags into the GRPC metadata in order to be sent to the server.

			(*T) traceTagRPC(ctx context.Context, rti *stats.RPCTagInfo) context.Context
				TagRPC creates a new trace span for the client side of the RPC.

				It returns ctx with the new trace span added and a serialization of the
				SpanContext added to the outgoing gRPC metadata.

		Implements (at least one exported)
			*T : google.golang.org/grpc/stats.Handler

	 type ServerHandler (struct)
		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).

		Fields (total 2, both are exported)
			IsPublicEndpoint 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.

			StartOptions trace.StartOptions
				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.SpanKind will always be set to trace.SpanKindServer
				for spans started by this handler.

		Methods (total 7, in which 4 are exported)
			(*T) HandleConn(ctx context.Context, cs stats.ConnStats)
				HandleConn exists to satisfy gRPC stats.Handler.

			(*T) HandleRPC(ctx context.Context, rs stats.RPCStats)
				HandleRPC implements per-RPC tracing and stats instrumentation.

			(*T) TagConn(ctx context.Context, cti *stats.ConnTagInfo) context.Context
				TagConn exists to satisfy gRPC stats.Handler.

			(*T) TagRPC(ctx context.Context, rti *stats.RPCTagInfo) context.Context
				TagRPC implements per-RPC context management.

			/* 3 unexporteds ... *//* 3 unexporteds: */
			(*T) extractPropagatedTags(ctx context.Context) *tag.Map
				extractPropagatedTags creates a new tag map containing the tags extracted from the
				gRPC metadata.

			(*T) statsTagRPC(ctx context.Context, info *stats.RPCTagInfo) context.Context
				statsTagRPC gets the metadata from gRPC context, extracts the encoded tags from
				it and creates a new tag.Map and puts them into the returned context.

			(*T) traceTagRPC(ctx context.Context, rti *stats.RPCTagInfo) context.Context
				TagRPC creates a new trace span for the server side of the RPC.

				It checks the incoming gRPC metadata in ctx for a SpanContext, and if
				it finds one, uses that SpanContext as the parent context of the new span.

				It returns ctx, with the new trace span added.

		Implements (at least one exported)
			*T : google.golang.org/grpc/stats.Handler

	/* 2 unexporteds ... *//* 2 unexporteds: */
	 type grpcInstrumentationKey string (basic type)

		As Types Of (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			  var rpcDataKey

	 type rpcData (struct)
		rpcData holds the instrumentation RPC data that is needed between the start
		and end of an call. It holds the info that this package needs to keep track
		of between the various GRPC events.

		Fields (total 6, none are exported)
			/* 6 unexporteds ... *//* 6 unexporteds: */
			method string
			recvBytes int64
				reqCount and respCount has to be the first words
				in order to be 64-aligned on 32-bit architectures.
				// access atomically

			recvCount int64
				reqCount and respCount has to be the first words
				in order to be 64-aligned on 32-bit architectures.
				// access atomically

			sentBytes int64
				reqCount and respCount has to be the first words
				in order to be 64-aligned on 32-bit architectures.
				// access atomically

			sentCount int64
				reqCount and respCount has to be the first words
				in order to be 64-aligned on 32-bit architectures.
				// access atomically

			startTime time.Time
				startTime represents the time at which TagRPC was invoked at the
				beginning of an RPC. It is an appoximation of the time when the
				application code invoked GRPC code.



Package-Level Functions (total 8, none are exported)

	/* 8 unexporteds ... *//* 8 unexporteds: */
	 func getSpanCtxAttachment(ctx context.Context) metricdata.Attachments
	 func handleRPCEnd(ctx context.Context, s *stats.End)
	 func handleRPCInPayload(ctx context.Context, s *stats.InPayload)
	 func handleRPCOutPayload(ctx context.Context, s *stats.OutPayload)
	 func methodName(fullname string) string
	 func statsHandleRPC(ctx context.Context, s stats.RPCStats)
		statsHandleRPC processes the RPC events.

	 func statusCodeToString(s *status.Status) string
	 func traceHandleRPC(ctx context.Context, rs stats.RPCStats)
Package-Level Variables (total 34, in which 33 are exported)

	  var ClientCompletedRPCsView *view.View
		Predefined views may be registered 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 registered by
		default.

	  var ClientReceivedBytesPerRPC *stats.Int64Measure
		The following variables are measures are recorded by ClientHandler:

	  var ClientReceivedBytesPerRPCView *view.View
		Predefined views may be registered 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 registered by
		default.

	  var ClientReceivedMessagesPerRPC *stats.Int64Measure
		The following variables are measures are recorded by ClientHandler:

	  var ClientReceivedMessagesPerRPCView *view.View
		Predefined views may be registered 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 registered by
		default.

	  var ClientRoundtripLatency *stats.Float64Measure
		The following variables are measures are recorded by ClientHandler:

	  var ClientRoundtripLatencyView *view.View
		Predefined views may be registered 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 registered by
		default.

	  var ClientSentBytesPerRPC *stats.Int64Measure
		The following variables are measures are recorded by ClientHandler:

	  var ClientSentBytesPerRPCView *view.View
		Predefined views may be registered 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 registered by
		default.

	  var ClientSentMessagesPerRPC *stats.Int64Measure
		The following variables are measures are recorded by ClientHandler:

	  var ClientSentMessagesPerRPCView *view.View
		Predefined views may be registered 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 registered by
		default.

	  var ClientServerLatency *stats.Float64Measure
		The following variables are measures are recorded by ClientHandler:

	  var ClientServerLatencyView *view.View
		Predefined views may be registered 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 registered by
		default.

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

	  var DefaultClientViews []*view.View
		DefaultClientViews are the default client views provided by this package.

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

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

	  var DefaultServerViews []*view.View
		DefaultServerViews are the default server views provided by this package.

	  var KeyClientMethod tag.Key
		Client tags are applied to measures at the end of each RPC.

	  var KeyClientStatus tag.Key
		Client tags are applied to measures at the end of each RPC.

	  var KeyServerMethod tag.Key
		Server tags are applied to the context used to process each RPC, as well as
		the measures at the end of each RPC.

	  var KeyServerStatus tag.Key
		Server tags are applied to the context used to process each RPC, as well as
		the measures at the end of each RPC.

	  var ServerCompletedRPCsView *view.View
		Predefined views may be registered 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 registered by
		default.

	  var ServerLatency *stats.Float64Measure
		The following variables are measures are recorded by ServerHandler:

	  var ServerLatencyView *view.View
		Predefined views may be registered 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 registered by
		default.

	  var ServerReceivedBytesPerRPC *stats.Int64Measure
		The following variables are measures are recorded by ServerHandler:

	  var ServerReceivedBytesPerRPCView *view.View
		Predefined views may be registered 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 registered by
		default.

	  var ServerReceivedMessagesPerRPC *stats.Int64Measure
		The following variables are measures are recorded by ServerHandler:

	  var ServerReceivedMessagesPerRPCView *view.View
		Predefined views may be registered 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 registered by
		default.

	  var ServerSentBytesPerRPC *stats.Int64Measure
		The following variables are measures are recorded by ServerHandler:

	  var ServerSentBytesPerRPCView *view.View
		Predefined views may be registered 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 registered by
		default.

	  var ServerSentMessagesPerRPC *stats.Int64Measure
		The following variables are measures are recorded by ServerHandler:

	  var ServerSentMessagesPerRPCView *view.View
		Predefined views may be registered 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 registered by
		default.

	/* one unexported ... *//* one unexported: */
	  var rpcDataKey grpcInstrumentationKey
Package-Level Constants (only one, which is unexported)

	/* one unexported ... *//* one unexported: */
	const traceContextKey = "grpc-trace-bin"

The pages are generated with Golds v0.3.2-preview. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.