otelgrpc

package module
v0.71.0 Latest Latest
Warning

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

 Go to latest Published: Aug 26, 2026 License: Apache-2.0, BSD-3-Clause Imports: 22 Imported by: 1,810

Documentation

Overview

Package otelgrpc is the instrumentation library for google.golang.org/grpc.

Use NewClientHandler with grpc.WithStatsHandler to instrument a gRPC client.

Use NewServerHandler with grpc.StatsHandler to instrument a gRPC server.

Index

Examples

Constants

View Source 
const ScopeName = "go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"

ScopeName is the instrumentation scope name.

View Source 
const Version = "0.71.0"

Version is the current release version of the gRPC instrumentation.

Variables

This section is empty.

Functions

func NewClientHandler added in v0.45.0 

func NewClientHandler(opts ...Option) stats.Handler

NewClientHandler creates a stats.Handler for a gRPC client.

Example 
package main

import (
	"google.golang.org/grpc"

	"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
)

func main() {
	_, _ = grpc.NewClient("localhost", grpc.WithStatsHandler(otelgrpc.NewClientHandler()))
}
Example (WithMetricAttributesFn_baggage)

ExampleNewClientHandler_withMetricAttributesFn_baggage demonstrates how to add a dynamic client-side attribute using W3C baggage to the auto-instrumented metrics. 

package main

import (
	"context"

	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/baggage"
	"google.golang.org/grpc"

	"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
)

func main() {
	// Baggage must be set in the context before making the call, e.g.,
	// ...
	// member, err := baggage.NewMember("traffic.type", "internal")
	// ...
	// bag, err := baggage.New(member)
	// ...
	// ctx := baggage.ContextWithBaggage(ctx, bag)
	// ...

	_, _ = grpc.NewClient("localhost", grpc.WithStatsHandler(otelgrpc.NewClientHandler(
		otelgrpc.WithMetricAttributesFn(func(ctx context.Context) []attribute.KeyValue {
			bag := baggage.FromContext(ctx)
			if trafficType := bag.Member("traffic.type"); trafficType.Value() != "" {
				return []attribute.KeyValue{
					attribute.String("traffic.type", trafficType.Value()),
				}
			}

			return nil
		}),
	)))
}
Example (WithMetricAttributesFn_interceptor)

ExampleNewClientHandler_withMetricAttributesFn_interceptor demonstrates how to add a dynamic client-side attribute using gRPC interceptors to the auto-instrumented metrics. 

package main

import (
	"context"

	"go.opentelemetry.io/otel/attribute"
	"google.golang.org/grpc"

	"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
)

func main() {
	// should be centralized, example only
	type retryAttemptKey struct{}

	// a gRPC client interceptor must populate that key with the actual retry attempt, e.g.,
	// ...
	// interceptor := func(ctx context.Context, method string, req, reply any,
	//     cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
	//     ...
	//     ctx = context.WithValue(ctx, retryAttemptKey{}, attempt)
	//     return invoker(ctx, method, req, reply, cc, opts...)
	// }
	// ...

	_, _ = grpc.NewClient("localhost", grpc.WithStatsHandler(otelgrpc.NewClientHandler(
		otelgrpc.WithMetricAttributesFn(func(ctx context.Context) []attribute.KeyValue {
			if attempt, ok := ctx.Value(retryAttemptKey{}).(int); ok {
				return []attribute.KeyValue{
					// Caution: example only.
					// This must be a controlled, bounded and very limited set of numbers
					// so that you don't end up with very high cardinality.
					attribute.Int("retry.attempt", attempt),
				}
			}

			return nil
		}),
	)))
}

func NewServerHandler added in v0.45.0 

func NewServerHandler(opts ...Option) stats.Handler

NewServerHandler creates a stats.Handler for a gRPC server.

Example 
package main

import (
	"google.golang.org/grpc"

	"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
)

func main() {
	_ = grpc.NewServer(grpc.StatsHandler(otelgrpc.NewServerHandler()))
}
Example (WithMetricAttributesFn_baggage)

ExampleNewServerHandler_withMetricAttributesFn_baggage demonstrates how to add a dynamic server-side attribute using W3C baggage to the auto-instrumented metrics. 

package main

import (
	"context"

	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/baggage"
	"go.opentelemetry.io/otel/propagation"
	"google.golang.org/grpc"

	"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
)

func main() {
	// The client must set baggage in context beforehand and have baggage propagators configured to
	// inject it into the headers (see https://pkg.go.dev/go.opentelemetry.io/otel/propagation#section-documentation), e.g.,
	//
	// conn, err := grpc.NewClient(
	// ...
	// grpc.WithStatsHandler(otelgrpc.NewClientHandler(
	//	    otelgrpc.WithPropagators(propagation.NewCompositeTextMapPropagator(
	//			  propagation.Baggage{},
	//		)),
	//	)),
	//)
	// ...
	// member, err := baggage.NewMember("tenant.tier", "premium")
	// ...
	// bag, err := baggage.New(member)
	// ...
	// ctx := baggage.ContextWithBaggage(ctx, bag)
	// ...

	_ = grpc.NewServer(grpc.StatsHandler(otelgrpc.NewServerHandler(
		// Propagators are required to extract baggage from incoming request headers.
		otelgrpc.WithPropagators(propagation.NewCompositeTextMapPropagator(
			propagation.TraceContext{},
			propagation.Baggage{},
		)),
		otelgrpc.WithMetricAttributesFn(func(ctx context.Context) []attribute.KeyValue {
			bag := baggage.FromContext(ctx)
			if tier := bag.Member("tenant.tier"); tier.Value() != "" {
				return []attribute.KeyValue{
					attribute.String("tenant.tier", tier.Value()),
				}
			}

			return nil
		}),
	)))
}
Example (WithMetricAttributesFn_metadata)

ExampleNewServerHandler_withMetricAttributesFn_metadata demonstrates how to add a dynamic server-side attribute using gRPC metadata to the auto-instrumented metrics. 

package main

import (
	"context"

	"go.opentelemetry.io/otel/attribute"
	"google.golang.org/grpc"
	"google.golang.org/grpc/metadata"

	"go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
)

func main() {
	// The client must set metadata in the outgoing context beforehand, e.g.,
	// ...
	// ctx := metadata.NewOutgoingContext(context.Background(), metadata.Pairs("origin", "some-origin"))
	// ...
	_ = grpc.NewServer(grpc.StatsHandler(otelgrpc.NewServerHandler(
		otelgrpc.WithMetricAttributesFn(func(ctx context.Context) []attribute.KeyValue {
			md, ok := metadata.FromIncomingContext(ctx)
			if ok {
				if origins := md.Get("origin"); len(origins) > 0 && origins[0] != "" {
					return []attribute.KeyValue{attribute.String("origin", origins[0])}
				}
			}

			// Some use-cases might require to fallback to a default.
			return []attribute.KeyValue{attribute.String("origin", "unknown")}
		}),
	)))
}

Types

type Event added in v0.43.0 

type Event int

Event type that can be recorded, see WithMessageEvents. 

const (
	ReceivedEvents Event = iota
	SentEvents
)

Different types of events that can be recorded, see WithMessageEvents.

type Filter added in v0.35.0 

type Filter func(*stats.RPCTagInfo) bool

Filter is a predicate used to determine whether a given request in should be instrumented by the attached RPC tag info. A Filter must return true if the request should be instrumented.

type InterceptorFilter deprecated added in v0.52.0 

type InterceptorFilter func(*InterceptorInfo) bool

InterceptorFilter is a predicate used to determine whether a given request in interceptor info should be instrumented. A InterceptorFilter must return true if the request should be traced.

Deprecated: Use stats handlers instead.

type InterceptorInfo added in v0.35.0 

type InterceptorInfo struct {
	// Method is method name registered to UnaryClient and StreamClient
	Method string
	// UnaryServerInfo is the metadata for UnaryServer
	UnaryServerInfo *grpc.UnaryServerInfo
	// StreamServerInfo if the metadata for StreamServer
	StreamServerInfo *grpc.StreamServerInfo
	// Type is the type for interceptor
	Type InterceptorType
}

InterceptorInfo is the union of some arguments to four types of gRPC interceptors.

type InterceptorType added in v0.35.0 

type InterceptorType uint8

InterceptorType is the flag to define which gRPC interceptor the InterceptorInfo object is. 

const (
	// UndefinedInterceptor is the type for the interceptor information that is not
	// well initialized or categorized to other types.
	UndefinedInterceptor InterceptorType = iota
	// UnaryClient is the type for grpc.UnaryClient interceptor.
	UnaryClient
	// StreamClient is the type for grpc.StreamClient interceptor.
	StreamClient
	// UnaryServer is the type for grpc.UnaryServer interceptor.
	UnaryServer
	// StreamServer is the type for grpc.StreamServer interceptor.
	StreamServer
)

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option applies an option value for a config.

func WithFilter added in v0.52.0 

func WithFilter(f Filter) Option

WithFilter returns an Option to use the request filter.

func WithInterceptorFilter deprecated added in v0.35.0 

func WithInterceptorFilter(f InterceptorFilter) Option

WithInterceptorFilter returns an Option to use the request filter.

Deprecated: Use stats handlers instead.

func WithMessageEvents added in v0.43.0 

func WithMessageEvents(events ...Event) Option

WithMessageEvents configures the Handler to record the specified events (span.AddEvent) on spans. By default only summary attributes are added at the end of the request.

Valid events are:

  • ReceivedEvents: Record the number of bytes read after every gRPC read operation.
  • SentEvents: Record the number of bytes written after every gRPC write operation.

func WithMeterProvider added in v0.37.0 

func WithMeterProvider(mp metric.MeterProvider) Option

WithMeterProvider returns an Option to use the MeterProvider when creating a Meter. If this option is not provide the global MeterProvider will be used.

func WithMetricAttributes added in v0.54.0 

func WithMetricAttributes(a ...attribute.KeyValue) Option

WithMetricAttributes returns an Option to add custom attributes to the metrics.

func WithMetricAttributesFn added in v0.65.0 

func WithMetricAttributesFn(fn func(ctx context.Context) []attribute.KeyValue) Option

WithMetricAttributesFn returns an Option to add dynamic custom attributes to the handler's metrics. The function is called once per RPC and the returned attributes are applied to all metrics recorded by this handler.

The context parameter is the standard gRPC request context and provides access to request-scoped data.

func WithPropagators 

func WithPropagators(p propagation.TextMapPropagator) Option

WithPropagators returns an Option to use the Propagators when extracting and injecting trace context from requests.

func WithPublicEndpoint added in v0.62.0 

func WithPublicEndpoint() Option

WithPublicEndpoint configures the Handler to link the span with an incoming span context. If this option is not provided, then the association is a child association instead of a link.

func WithPublicEndpointFn added in v0.62.0 

func WithPublicEndpointFn(fn func(context.Context, *stats.RPCTagInfo) bool) Option

WithPublicEndpointFn runs with every request, and allows conditionally configuring the Handler to link the span with an incoming span context. If this option is not provided or returns false, then the association is a child association instead of a link. Note: WithPublicEndpoint takes precedence over WithPublicEndpointFn.

func WithSpanAttributes added in v0.54.0 

func WithSpanAttributes(a ...attribute.KeyValue) Option

WithSpanAttributes returns an Option to add custom attributes to the spans.

func WithSpanKind added in v0.66.0 

func WithSpanKind(sk trace.SpanKind) Option

WithSpanKind returns an Option to set the span kind for spans created by the handler.

By default, NewServerHandler creates spans with trace.SpanKindServer and NewClientHandler creates spans with trace.SpanKindClient.

func WithTracerProvider added in v0.13.0 

func WithTracerProvider(tp trace.TracerProvider) Option

WithTracerProvider returns an Option to use the TracerProvider when creating a Tracer.

Source Files

View all Source files

Directories

Path Synopsis
example module
Package filters provides a set of filters useful with the otelgrpc.WithFilter option to control which inbound requests are instrumented.
 Package filters provides a set of filters useful with the otelgrpc.WithFilter option to control which inbound requests are instrumented.
Package internal provides internal functionality for the otelgrpc package.
 Package internal provides internal functionality for the otelgrpc package.
test
Package test contains functions used by interop client/server.
 Package test contains functions used by interop client/server.
test module

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.