opencensus

Documentation

Overview

Package opencensus implements opencensus instrumentation code for gRPC-Go clients and servers.

Index

• Variables
• func DialOption(to TraceOptions) grpc.DialOption
• func GetTraceAndSpanID(ctx context.Context) (trace.TraceID, trace.SpanID, bool)
• func ServerOption(to TraceOptions) grpc.ServerOption
• type TraceOptions

Variables

var (
	// ClientSentMessagesPerRPCView is the distribution of sent messages per
	// RPC, keyed on method.
	ClientSentMessagesPerRPCView = &view.View{
		Measure:     clientSentMessagesPerRPC,
		Name:        "grpc.io/client/sent_messages_per_rpc",
		Description: "Distribution of sent messages per RPC, by method.",
		TagKeys:     []tag.Key{keyClientMethod},
		Aggregation: countDistribution,
	}
	// ClientReceivedMessagesPerRPCView is the distribution of received messages
	// per RPC, keyed on method.
	ClientReceivedMessagesPerRPCView = &view.View{
		Measure:     clientReceivedMessagesPerRPC,
		Name:        "grpc.io/client/received_messages_per_rpc",
		Description: "Distribution of received messages per RPC, by method.",
		TagKeys:     []tag.Key{keyClientMethod},
		Aggregation: countDistribution,
	}
	// ClientSentBytesPerRPCView is the distribution of sent bytes per RPC,
	// keyed on method.
	ClientSentBytesPerRPCView = &view.View{
		Measure:     clientSentBytesPerRPC,
		Name:        "grpc.io/client/sent_bytes_per_rpc",
		Description: "Distribution of sent bytes per RPC, by method.",
		TagKeys:     []tag.Key{keyClientMethod},
		Aggregation: bytesDistribution,
	}
	// ClientSentCompressedMessageBytesPerRPCView is the distribution of
	// compressed sent message bytes per RPC, keyed on method.
	ClientSentCompressedMessageBytesPerRPCView = &view.View{
		Measure:     clientSentCompressedBytesPerRPC,
		Name:        "grpc.io/client/sent_compressed_message_bytes_per_rpc",
		Description: "Distribution of sent compressed message bytes per RPC, by method.",
		TagKeys:     []tag.Key{keyClientMethod},
		Aggregation: bytesDistribution,
	}
	// ClientReceivedBytesPerRPCView is the distribution of received bytes per
	// RPC, keyed on method.
	ClientReceivedBytesPerRPCView = &view.View{
		Measure:     clientReceivedBytesPerRPC,
		Name:        "grpc.io/client/received_bytes_per_rpc",
		Description: "Distribution of received bytes per RPC, by method.",
		TagKeys:     []tag.Key{keyClientMethod},
		Aggregation: bytesDistribution,
	}
	// ClientReceivedCompressedMessageBytesPerRPCView is the distribution of
	// compressed received message bytes per RPC, keyed on method.
	ClientReceivedCompressedMessageBytesPerRPCView = &view.View{
		Measure:     clientReceivedCompressedBytesPerRPC,
		Name:        "grpc.io/client/received_compressed_message_bytes_per_rpc",
		Description: "Distribution of received compressed message bytes per RPC, by method.",
		TagKeys:     []tag.Key{keyClientMethod},
		Aggregation: bytesDistribution,
	}
	// ClientStartedRPCsView is the count of opened RPCs, keyed on method.
	ClientStartedRPCsView = &view.View{
		Measure:     clientStartedRPCs,
		Name:        "grpc.io/client/started_rpcs",
		Description: "Number of opened client RPCs, by method.",
		TagKeys:     []tag.Key{keyClientMethod},
		Aggregation: view.Count(),
	}
	// ClientCompletedRPCsView is the count of completed RPCs, keyed on method
	// and status.
	ClientCompletedRPCsView = &view.View{
		Measure:     clientRoundtripLatency,
		Name:        "grpc.io/client/completed_rpcs",
		Description: "Number of completed RPCs by method and status.",
		TagKeys:     []tag.Key{keyClientMethod, keyClientStatus},
		Aggregation: view.Count(),
	}
	// ClientRoundtripLatencyView is the distribution of round-trip latency in
	// milliseconds per RPC, keyed on method.
	ClientRoundtripLatencyView = &view.View{
		Measure:     clientRoundtripLatency,
		Name:        "grpc.io/client/roundtrip_latency",
		Description: "Distribution of round-trip latency, by method.",
		TagKeys:     []tag.Key{keyClientMethod},
		Aggregation: millisecondsDistribution,
	}

	// ClientAPILatencyView is the distribution of client api latency for the
	// full RPC call, keyed on method and status.
	ClientAPILatencyView = &view.View{
		Measure:     clientAPILatency,
		Name:        "grpc.io/client/api_latency",
		Description: "Distribution of client api latency, by method and status",
		TagKeys:     []tag.Key{keyClientMethod, keyClientStatus},
		Aggregation: millisecondsDistribution,
	}
)

var (
	// ServerSentMessagesPerRPCView is the distribution of sent messages per
	// RPC, keyed on method.
	ServerSentMessagesPerRPCView = &view.View{
		Name:        "grpc.io/server/sent_messages_per_rpc",
		Description: "Distribution of sent messages per RPC, by method.",
		TagKeys:     []tag.Key{keyServerMethod},
		Measure:     serverSentMessagesPerRPC,
		Aggregation: countDistribution,
	}
	// ServerReceivedMessagesPerRPCView is the distribution of received messages
	// per RPC, keyed on method.
	ServerReceivedMessagesPerRPCView = &view.View{
		Name:        "grpc.io/server/received_messages_per_rpc",
		Description: "Distribution of received messages per RPC, by method.",
		TagKeys:     []tag.Key{keyServerMethod},
		Measure:     serverReceivedMessagesPerRPC,
		Aggregation: countDistribution,
	}
	// ServerSentBytesPerRPCView is the distribution of received bytes per RPC,
	// keyed on method.
	ServerSentBytesPerRPCView = &view.View{
		Name:        "grpc.io/server/sent_bytes_per_rpc",
		Description: "Distribution of sent bytes per RPC, by method.",
		Measure:     serverSentBytesPerRPC,
		TagKeys:     []tag.Key{keyServerMethod},
		Aggregation: bytesDistribution,
	}
	// ServerSentCompressedMessageBytesPerRPCView is the distribution of
	// received compressed message bytes per RPC, keyed on method.
	ServerSentCompressedMessageBytesPerRPCView = &view.View{
		Name:        "grpc.io/server/sent_compressed_message_bytes_per_rpc",
		Description: "Distribution of sent compressed message bytes per RPC, by method.",
		Measure:     serverSentCompressedBytesPerRPC,
		TagKeys:     []tag.Key{keyServerMethod},
		Aggregation: bytesDistribution,
	}
	// ServerReceivedBytesPerRPCView is the distribution of sent bytes per RPC,
	// keyed on method.
	ServerReceivedBytesPerRPCView = &view.View{
		Name:        "grpc.io/server/received_bytes_per_rpc",
		Description: "Distribution of received bytes per RPC, by method.",
		Measure:     serverReceivedBytesPerRPC,
		TagKeys:     []tag.Key{keyServerMethod},
		Aggregation: bytesDistribution,
	}
	// ServerReceivedCompressedMessageBytesPerRPCView is the distribution of
	// sent compressed message bytes per RPC, keyed on method.
	ServerReceivedCompressedMessageBytesPerRPCView = &view.View{
		Name:        "grpc.io/server/received_compressed_message_bytes_per_rpc",
		Description: "Distribution of received compressed message bytes per RPC, by method.",
		Measure:     serverReceivedCompressedBytesPerRPC,
		TagKeys:     []tag.Key{keyServerMethod},
		Aggregation: bytesDistribution,
	}
	// ServerStartedRPCsView is the count of opened RPCs, keyed on method.
	ServerStartedRPCsView = &view.View{
		Measure:     serverStartedRPCs,
		Name:        "grpc.io/server/started_rpcs",
		Description: "Number of opened server RPCs, by method.",
		TagKeys:     []tag.Key{keyServerMethod},
		Aggregation: view.Count(),
	}
	// ServerCompletedRPCsView is the count of completed RPCs, keyed on
	// method and status.
	ServerCompletedRPCsView = &view.View{
		Name:        "grpc.io/server/completed_rpcs",
		Description: "Number of completed RPCs by method and status.",
		TagKeys:     []tag.Key{keyServerMethod, keyServerStatus},
		Measure:     serverLatency,
		Aggregation: view.Count(),
	}
	// ServerLatencyView is the distribution of server latency in milliseconds
	// per RPC, keyed on method.
	ServerLatencyView = &view.View{
		Name:        "grpc.io/server/server_latency",
		Description: "Distribution of server latency in milliseconds, by method.",
		TagKeys:     []tag.Key{keyServerMethod},
		Measure:     serverLatency,
		Aggregation: millisecondsDistribution,
	}
)

var DefaultClientViews = []*view.View{
	ClientSentBytesPerRPCView,
	ClientReceivedBytesPerRPCView,
	ClientRoundtripLatencyView,
	ClientCompletedRPCsView,
	ClientStartedRPCsView,
}

DefaultClientViews is the set of client views which are considered the minimum required to monitor client side performance.

var DefaultServerViews = []*view.View{
	ServerReceivedBytesPerRPCView,
	ServerSentBytesPerRPCView,
	ServerLatencyView,
	ServerCompletedRPCsView,
	ServerStartedRPCsView,
}

DefaultServerViews is the set of server views which are considered the minimum required to monitor server side performance.

Functions

func DialOption

func DialOption(to TraceOptions) grpc.DialOption

DialOption returns a dial option which enables OpenCensus instrumentation code for a grpc.ClientConn.

Client applications interested in instrumenting their grpc.ClientConn should pass the dial option returned from this function as the first dial option to grpc.Dial().

Using this option will always lead to instrumentation, however in order to use the data an exporter must be registered with the OpenCensus trace package for traces and the OpenCensus view package for metrics. Client side has retries, so a Unary and Streaming Interceptor are registered to handle per RPC traces/metrics, and a Stats Handler is registered to handle per RPC attempt trace/metrics. These three components registered work together in conjunction, and do not work standalone. It is not supported to use this alongside another stats handler dial option.

func GetTraceAndSpanID

func GetTraceAndSpanID(ctx context.Context) (trace.TraceID, trace.SpanID, bool)

GetTraceAndSpanID returns the trace and span ID of the span in the context. Returns true if IDs present and false if IDs not present.

func ServerOption

func ServerOption(to TraceOptions) grpc.ServerOption

ServerOption returns a server option which enables OpenCensus instrumentation code for a grpc.Server.

Server applications interested in instrumenting their grpc.Server should pass the server option returned from this function as the first argument to grpc.NewServer().

Using this option will always lead to instrumentation, however in order to use the data an exporter must be registered with the OpenCensus trace package for traces and the OpenCensus view package for metrics. Server side does not have retries, so a registered Stats Handler is the only option that is returned. It is not supported to use this alongside another stats handler server option.

Types

type TraceOptions

type TraceOptions struct {
	// TS is the Sampler used for tracing.
	TS trace.Sampler
	// DisableTrace determines whether traces are disabled for an OpenCensus
	// Dial or Server option. will overwrite any global option setting.
	DisableTrace bool
}

TraceOptions are the tracing options for opencensus instrumentation.