opentelemetry

Documentation

Overview

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

Example (DialOption)

package main

import (
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
	"google.golang.org/grpc/stats/opentelemetry"

	"go.opentelemetry.io/otel/sdk/metric"
)

func main() {
	// This is setting default bounds for a view. Setting these bounds through
	// meter provider from SDK is recommended, as API calls in this module
	// provide default bounds, but these calls are not guaranteed to be stable
	// and API implementors are not required to implement bounds. Setting bounds
	// through SDK ensures the bounds get picked up. The specific fields in
	// Aggregation take precedence over defaults from API. For any fields unset
	// in aggregation, defaults get picked up, so can have a mix of fields from
	// SDK and fields created from API call. The overridden views themselves
	// also follow same logic, only the specific views being created in the SDK
	// use SDK information, the rest are created from API call.
	reader := metric.NewManualReader()
	provider := metric.NewMeterProvider(
		metric.WithReader(reader),
		metric.WithView(metric.NewView(metric.Instrument{
			Name: "grpc.client.call.duration",
		},
			metric.Stream{
				Aggregation: metric.AggregationExplicitBucketHistogram{
					Boundaries: opentelemetry.DefaultSizeBounds, // The specific fields set in SDK take precedence over API.
				},
			},
		)),
	)

	opts := opentelemetry.Options{
		MetricsOptions: opentelemetry.MetricsOptions{
			MeterProvider: provider,
			Metrics:       opentelemetry.DefaultMetrics(), // equivalent to unset - distinct from empty
		},
	}
	do := opentelemetry.DialOption(opts)
	cc, err := grpc.NewClient("<target string>", do, grpc.WithTransportCredentials(insecure.NewCredentials()))
	if err != nil {
		// Handle err.
	}
	defer cc.Close()
}

Example (ServerOption)

package main

import (
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials/insecure"
	"google.golang.org/grpc/stats/opentelemetry"

	"go.opentelemetry.io/otel/sdk/metric"
)

func main() {
	reader := metric.NewManualReader()
	provider := metric.NewMeterProvider(metric.WithReader(reader))
	opts := opentelemetry.Options{
		MetricsOptions: opentelemetry.MetricsOptions{
			MeterProvider: provider,
			// Because Metrics is unset, the user will get default metrics.
			MethodAttributeFilter: func(str string) bool {
				// Will allow duplex/any other type of RPC.
				return str != "/grpc.testing.TestService/UnaryCall"
			},
		},
	}
	cc, err := grpc.NewClient("some-target", opentelemetry.DialOption(opts), grpc.WithTransportCredentials(insecure.NewCredentials()))
	if err != nil {
		// Handle err.
	}
	defer cc.Close()
}

Index

• Constants
• Variables
• func DefaultMetrics() *estats.Metrics
• func DialOption(o Options) grpc.DialOption
• func ServerOption(o Options) grpc.ServerOption
• type MetricsOptions
• type Options

Examples

• Package (DialOption)
• Package (ServerOption)

Constants

const (
	// ClientAttemptStarted is the number of client call attempts started.
	ClientAttemptStarted estats.Metric = "grpc.client.attempt.started"
	// ClientAttemptDuration is the end-to-end time taken to complete a client
	// call attempt.
	ClientAttemptDuration estats.Metric = "grpc.client.attempt.duration"
	// ClientAttemptSentCompressedTotalMessageSize is the compressed message
	// bytes sent per client call attempt.
	ClientAttemptSentCompressedTotalMessageSize estats.Metric = "grpc.client.attempt.sent_total_compressed_message_size"
	// ClientAttemptRcvdCompressedTotalMessageSize is the compressed message
	// bytes received per call attempt.
	ClientAttemptRcvdCompressedTotalMessageSize estats.Metric = "grpc.client.attempt.rcvd_total_compressed_message_size"
	// ClientCallDuration is the time taken by gRPC to complete an RPC from
	// application's perspective.
	ClientCallDuration estats.Metric = "grpc.client.call.duration"
)

const (
	// ServerCallStarted is the number of server calls started.
	ServerCallStarted estats.Metric = "grpc.server.call.started"
	// ServerCallSentCompressedTotalMessageSize is the compressed message bytes
	// sent per server call.
	ServerCallSentCompressedTotalMessageSize estats.Metric = "grpc.server.call.sent_total_compressed_message_size"
	// ServerCallRcvdCompressedTotalMessageSize is the compressed message bytes
	// received per server call.
	ServerCallRcvdCompressedTotalMessageSize estats.Metric = "grpc.server.call.rcvd_total_compressed_message_size"
	// ServerCallDuration is the end-to-end time taken to complete a call from
	// server transport's perspective.
	ServerCallDuration estats.Metric = "grpc.server.call.duration"
)

Variables

var (
	// DefaultLatencyBounds are the default bounds for latency metrics.
	DefaultLatencyBounds = []float64{0, 0.00001, 0.00005, 0.0001, 0.0003, 0.0006, 0.0008, 0.001, 0.002, 0.003, 0.004, 0.005, 0.006, 0.008, 0.01, 0.013, 0.016, 0.02, 0.025, 0.03, 0.04, 0.05, 0.065, 0.08, 0.1, 0.13, 0.16, 0.2, 0.25, 0.3, 0.4, 0.5, 0.65, 0.8, 1, 2, 5, 10, 20, 50, 100} // provide "advice" through API, SDK should set this too
	// DefaultSizeBounds are the default bounds for metrics which record size.
	DefaultSizeBounds = []float64{0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296}
)

Users of this component should use these bucket boundaries as part of their SDK MeterProvider passed in. This component sends this as "advice" to the API, which works, however this stability is not guaranteed, so for safety the SDK Meter Provider provided should set these bounds for corresponding metrics.

Functions

func DefaultMetrics

func DefaultMetrics() *estats.Metrics

DefaultMetrics returns a set of default OpenTelemetry metrics.

This should only be invoked after init time.

func DialOption

func DialOption(o Options) grpc.DialOption

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

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

For the metrics supported by this instrumentation code, specify the client metrics to record in metrics options. Also provide an implementation of a MeterProvider. If the passed in Meter Provider does not have the view configured for an individual metric turned on, the API call in this component will create a default view for that metric.

func ServerOption

func ServerOption(o Options) grpc.ServerOption

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

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

For the metrics supported by this instrumentation code, specify the server metrics to record in metrics options. Also provide an implementation of a MeterProvider. If the passed in Meter Provider does not have the view configured for an individual metric turned on, the API call in this component will create a default view for that metric.

Types

type MetricsOptions

type MetricsOptions struct {
	// MeterProvider is the MeterProvider instance that will be used to create
	// instruments. To enable metrics collection, set a meter provider. If
	// unset, no metrics will be recorded. Any implementation knobs (i.e. views,
	// bounds) set in the MeterProvider take precedence over the API calls from
	// this interface. (i.e. it will create default views for unset views).
	MeterProvider otelmetric.MeterProvider

	// Metrics are the metrics to instrument. Will create instrument and record telemetry
	// for corresponding metric supported by the client and server
	// instrumentation components if applicable. If not set, the default metrics
	// will be recorded.
	Metrics *estats.Metrics

	// MethodAttributeFilter is to record the method name of RPCs handled by
	// grpc.UnknownServiceHandler, but take care to limit the values allowed, as
	// allowing too many will increase cardinality and could cause severe memory
	// or performance problems. On Client Side, pass a
	// grpc.StaticMethodCallOption as a call option into Invoke or NewStream.
	// This only applies for server side metrics.
	MethodAttributeFilter func(string) bool

	// OptionalLabels are labels received from LB Policies that this component
	// should add to metrics that record after receiving incoming metadata.
	OptionalLabels []string
	// contains filtered or unexported fields
}

MetricsOptions are the metrics options for OpenTelemetry instrumentation.

type Options

type Options struct {
	// MetricsOptions are the metrics options for OpenTelemetry instrumentation.
	MetricsOptions MetricsOptions
}

Options are the options for OpenTelemetry instrumentation.