opentelemetry

package
v1.69.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 5, 2024 License: Apache-2.0 Imports: 19 Imported by: 9

Documentation

Overview

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

For details on configuring opentelemetry and various instruments that this package creates, see [gRPC OpenTelemetry Metrics](https://grpc.io/docs/guides/opentelemetry-metrics/).

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()
}

Output:
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()
}

Output:

Index

Examples

Constants

View Source 
const (
	// ClientAttemptStartedMetricName is the number of client call attempts
	// started.
	ClientAttemptStartedMetricName string = "grpc.client.attempt.started"
	// ClientAttemptDurationMetricName is the end-to-end time taken to complete
	// a client call attempt.
	ClientAttemptDurationMetricName string = "grpc.client.attempt.duration"
	// ClientAttemptSentCompressedTotalMessageSizeMetricName is the compressed
	// message bytes sent per client call attempt.
	ClientAttemptSentCompressedTotalMessageSizeMetricName string = "grpc.client.attempt.sent_total_compressed_message_size"
	// ClientAttemptRcvdCompressedTotalMessageSizeMetricName is the compressed
	// message bytes received per call attempt.
	ClientAttemptRcvdCompressedTotalMessageSizeMetricName string = "grpc.client.attempt.rcvd_total_compressed_message_size"
	// ClientCallDurationMetricName is the time taken by gRPC to complete an RPC
	// from application's perspective.
	ClientCallDurationMetricName string = "grpc.client.call.duration"
)
View Source 
const (
	// ServerCallStartedMetricName is the number of server calls started.
	ServerCallStartedMetricName string = "grpc.server.call.started"
	// ServerCallSentCompressedTotalMessageSizeMetricName is the compressed
	// message bytes sent per server call.
	ServerCallSentCompressedTotalMessageSizeMetricName string = "grpc.server.call.sent_total_compressed_message_size"
	// ServerCallRcvdCompressedTotalMessageSizeMetricName is the compressed
	// message bytes received per server call.
	ServerCallRcvdCompressedTotalMessageSizeMetricName string = "grpc.server.call.rcvd_total_compressed_message_size"
	// ServerCallDurationMetricName is the end-to-end time taken to complete a
	// call from server transport's perspective.
	ServerCallDurationMetricName string = "grpc.server.call.duration"
)

Variables

View Source 
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() *stats.MetricSet

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 GRPCTraceBinPropagator added in v1.69.0 

type GRPCTraceBinPropagator struct{}

GRPCTraceBinPropagator is an OpenTelemetry TextMapPropagator which is used to extract and inject trace context data from and into headers exchanged by gRPC applications. It propagates trace data in binary format using the `grpc-trace-bin` header.

func (GRPCTraceBinPropagator) Extract added in v1.69.0 

func (GRPCTraceBinPropagator) Extract(ctx context.Context, carrier otelpropagation.TextMapCarrier) context.Context

Extract reads OpenTelemetry span context from the `grpc-trace-bin` header of carrier into the provided context, if present.

If a valid span context is retrieved from `grpc-trace-bin`, it returns a new context containing the extracted OpenTelemetry span context marked as remote.

If `grpc-trace-bin` header is not present, it returns the context as is.

func (GRPCTraceBinPropagator) Fields added in v1.69.0 

func (GRPCTraceBinPropagator) Fields() []string

Fields returns the keys whose values are set with Inject.

GRPCTraceBinPropagator always returns a slice containing only `grpc-trace-bin` key because it only sets the `grpc-trace-bin` header for propagating trace context.

func (GRPCTraceBinPropagator) Inject added in v1.69.0 

func (GRPCTraceBinPropagator) Inject(ctx context.Context, carrier otelpropagation.TextMapCarrier)

Inject sets OpenTelemetry span context from the Context into the carrier as a `grpc-trace-bin` header if span context is valid.

If span context is not valid, it returns without setting `grpc-trace-bin` header.

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.
	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 *stats.MetricSet

	// MethodAttributeFilter is a function that determines whether to record the
	// method name of RPCs as an attribute, or to bucket into "other". Take care
	// to limit the values allowed, as allowing too many will increase
	// cardinality and could cause severe memory or performance problems.
	//
	// This only applies for server-side metrics.  For clients, to record the
	// method name in the attributes, pass grpc.StaticMethodCallOption to Invoke
	// or NewStream. Note that when using protobuf generated clients, this
	// CallOption is included automatically.
	MethodAttributeFilter func(string) bool

	// OptionalLabels specifies a list of optional labels to enable on any
	// metrics that support them.
	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.

Source Files

View all Source files

Directories

Path Synopsis
Package csm contains utilities for Google Cloud Service Mesh observability.
 Package csm contains utilities for Google Cloud Service Mesh observability.
Package internal defines the PluginOption interface.
 Package internal defines the PluginOption interface.
testutils
Package testutils contains helpers for OpenTelemetry tests.
 Package testutils contains helpers for OpenTelemetry tests.
tracing
Package tracing implements the OpenTelemetry carrier for context propagation in gRPC tracing.
 Package tracing implements the OpenTelemetry carrier for context propagation in gRPC tracing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.