otelttrpc

README

ttrpc OpenTelemetry Instrumentation

This golang package implements OpenTelemetry instrumentation support for ttrpc. It can be used to automatically generate OpenTelemetry trace spans for RPC methods called on the ttrpc client side and served on the ttrpc server side.

Usage

Instrumentation is provided by two interceptors, one to enable instrumentation for unary clients and another for enabling instrumentation for unary servers. These interceptors can be passed as ttrpc.ClientOpts and ttrpc.ServerOpt to ttrpc during client and server creation with code like this:

   import (
       "github.com/containerd/ttrpc"
       "github.com/containerd/otelttrpc"
   )

   // on the client side
   ...
   client := ttrpc.NewClient(
       conn,
       ttrpc.UnaryClientInterceptor(
           otelttrpc.UnaryClientInterceptor(),
       ),
   )

   // and on the server side
   ...
   server, err := ttrpc.NewServer(
       ttrpc.WithUnaryServerInterceptor(
           otelttrpc.UnaryServerInterceptor(),
       ),
   )

Once enabled, the interceptors generate trace Spans for all called and served unary method calls. If the rest of the code is properly set up to collect and export tracing data to opentelemetry, these spans should show up as part of the collected traces.

For a more complete example see the sample client and the sample server code.

Limitations

Currently only unary client and unary server methods can be instrumented. Support for streaming interfaces is yet to be implemented.

Project details

otelttrpc is a containerd sub-project, licensed under the Apache 2.0 license. As a containerd sub-project, you will find the:

• Project governance,
• Maintainers,
• and Contributing guidelines

information in our containerd/project repository.

Documentation

Overview

package otelttrpc implements Opentelemetry instrumentation support for ttRPC. The package implements unary client and server interceptors for opentelemetry tracing instrumentation. The interceptors can be passed as ttrpc.ClientOpts and ttrpc.ServerOpt to ttRPC during client and server creation. The interceptors then automatically handle generating trace spans for all called and served unary method calls. If the rest of the code is properly set up to collect and export tracing data to opentelemetry, these spans should show up as part of the collected traces.

Index

• Constants
• Variables
• func UnaryClientInterceptor(opts ...Option) ttrpc.UnaryClientInterceptor
• func UnaryServerInterceptor(opts ...Option) ttrpc.UnaryServerInterceptor
• func Version() string
• type Event
• type Option
  • func WithMessageEvents(events ...Event) Option
  • func WithMeterProvider(mp metric.MeterProvider) Option
  • func WithPropagators(p propagation.TextMapPropagator) Option
  • func WithTracerProvider(tp trace.TracerProvider) Option

Examples

• UnaryClientInterceptor
• UnaryServerInterceptor

Constants

const (
	// Name of message transmitted or received.
	RPCNameKey = attribute.Key("name")

	// Type of message transmitted or received.
	RPCMessageTypeKey = attribute.Key("message.type")

	// Identifier of message transmitted or received.
	RPCMessageIDKey = attribute.Key("message.id")
)

Semantic conventions for attribute keys for ttRPC.

const (

	// TTRPCStatusCodeKey is convention for numeric status code of a ttRPC request.
	TTRPCStatusCodeKey = attribute.Key("rpc.ttrpc.status_code")
)

Variables

var (
	// Semantic convention for ttRPC as the remoting system.
	RPCSystemTTRPC = semconv.RPCSystemKey.String("ttrpc")

	// Semantic conventions for RPC message types.
	RPCMessageTypeSent     = RPCMessageTypeKey.String("SENT")
	RPCMessageTypeReceived = RPCMessageTypeKey.String("RECEIVED")
)

Semantic conventions for common RPC attributes.

Functions

func UnaryClientInterceptor

func UnaryClientInterceptor(opts ...Option) ttrpc.UnaryClientInterceptor

UnaryClientInterceptor returns a ttrpc.UnaryClientInterceptor suitable for use in a ttrpc.NewClient call.

Example

var c net.Conn
_ = ttrpc.NewClient(c, ttrpc.WithUnaryClientInterceptor(UnaryClientInterceptor()))

func UnaryServerInterceptor

func UnaryServerInterceptor(opts ...Option) ttrpc.UnaryServerInterceptor

UnaryServerInterceptor returns ttrpc.UnaryServerInterceptor suitable for use in a ttrpc.NewServer call.

Example

_, _ = ttrpc.NewServer(ttrpc.WithUnaryServerInterceptor(UnaryServerInterceptor()))

func Version

func Version() string

Version is the current release version of the ttRPC instrumentation.

Types

type Event

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 Option

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

Option applies an option value for a config.

func WithMessageEvents

func WithMessageEvents(events ...Event) Option

WithMessageEvents configures the interceptors 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 an event for every message received.
• SentEvents: Record an event for every message sent.

func WithMeterProvider

func WithMeterProvider(mp metric.MeterProvider) Option

WithMeterProvider returns an Option for setting the MeterProvider when creating a Meter. If this option is not provided the global MeterProvider will be used.

func WithPropagators

func WithPropagators(p propagation.TextMapPropagator) Option

WithPropagators returns an Option for setting the Propagators used to inject and extract trace context from requests. If this option is not provided the global TextMapPropagator will be used.

func WithTracerProvider

func WithTracerProvider(tp trace.TracerProvider) Option

WithTracerProvider returns an Option for setting the TracerProvider for creating a Tracer. If this option is not provided the global TracerProvider will be used.