nrgrpc

README

_integrations/nrgrpc

Package nrgrpc instruments https://github.com/grpc/grpc-go.

import "github.com/newrelic/go-agent/_integrations/nrgrpc"

For more information, see godocs.

Documentation

Overview

Package nrgrpc instruments https://github.com/grpc/grpc-go.

This package can be used to instrument gRPC servers and gRPC clients.

To instrument a gRPC server, use UnaryServerInterceptor and StreamServerInterceptor with your newrelic.Application to create server interceptors to pass to grpc.NewServer. Example:

cfg := newrelic.NewConfig("gRPC Server", os.Getenv("NEW_RELIC_LICENSE_KEY"))
app, _ := newrelic.NewApplication(cfg)
server := grpc.NewServer(
	grpc.UnaryInterceptor(nrgrpc.UnaryServerInterceptor(app)),
	grpc.StreamInterceptor(nrgrpc.StreamServerInterceptor(app)),
)

These interceptors create transactions for inbound calls. The transaction is added to the call context and can be accessed in your method handlers using newrelic.FromContext.

Full server example: https://github.com/newrelic/go-agent/blob/master/_integrations/nrgrpc/example/server/server.go

To instrument a gRPC client, follow these two steps:

1. Use UnaryClientInterceptor and StreamClientInterceptor when creating a grpc.ClientConn. Example:

conn, err := grpc.Dial(
	"localhost:8080",
	grpc.WithUnaryInterceptor(nrgrpc.UnaryClientInterceptor),
	grpc.WithStreamInterceptor(nrgrpc.StreamClientInterceptor),
)

2. Ensure that calls made with this grpc.ClientConn are done with a context which contains a newrelic.Transaction.

Full client example: https://github.com/newrelic/go-agent/blob/master/_integrations/nrgrpc/example/client/client.go

Index

• func StreamClientInterceptor(ctx context.Context, desc *grpc.StreamDesc, cc *grpc.ClientConn, method string, ...) (grpc.ClientStream, error)
• func StreamServerInterceptor(app newrelic.Application) grpc.StreamServerInterceptor
• func UnaryClientInterceptor(ctx context.Context, method string, req, reply interface{}, ...) error
• func UnaryServerInterceptor(app newrelic.Application) grpc.UnaryServerInterceptor

Functions

func StreamClientInterceptor

func StreamClientInterceptor(ctx context.Context, desc *grpc.StreamDesc, cc *grpc.ClientConn, method string, streamer grpc.Streamer, opts ...grpc.CallOption) (grpc.ClientStream, error)

StreamClientInterceptor instruments client streaming RPCs. This interceptor records streaming each call with an external segment. Using it requires two steps:

1. Use this function with grpc.WithChainStreamInterceptor or grpc.WithStreamInterceptor when creating a grpc.ClientConn. Example:

conn, err := grpc.Dial(
	"localhost:8080",
	grpc.WithUnaryInterceptor(nrgrpc.UnaryClientInterceptor),
	grpc.WithStreamInterceptor(nrgrpc.StreamClientInterceptor),
)

2. Ensure that calls made with this grpc.ClientConn are done with a context which contains a newrelic.Transaction.

Full example: https://github.com/newrelic/go-agent/blob/master/_integrations/nrgrpc/example/client/client.go

This interceptor only instruments streaming calls. You must use both UnaryClientInterceptor and StreamClientInterceptor to instrument unary and streaming calls. These interceptors add headers to the call metadata if distributed tracing is enabled.

func StreamServerInterceptor

func StreamServerInterceptor(app newrelic.Application) grpc.StreamServerInterceptor

StreamServerInterceptor instruments server streaming RPCs.

Use this function with grpc.StreamInterceptor and a newrelic.Application to create a grpc.ServerOption to pass to grpc.NewServer. This interceptor records each streaming call with a transaction. You must use both UnaryServerInterceptor and StreamServerInterceptor to instrument unary and streaming calls.

Example:

cfg := newrelic.NewConfig("gRPC Server", os.Getenv("NEW_RELIC_LICENSE_KEY"))
app, _ := newrelic.NewApplication(cfg)
server := grpc.NewServer(
	grpc.UnaryInterceptor(nrgrpc.UnaryServerInterceptor(app)),
	grpc.StreamInterceptor(nrgrpc.StreamServerInterceptor(app)),
)

These interceptors add the transaction to the call context so it may be accessed in your method handlers using newrelic.FromContext.

Full example: https://github.com/newrelic/go-agent/blob/master/_integrations/nrgrpc/example/server/server.go

func UnaryClientInterceptor

func UnaryClientInterceptor(ctx context.Context, method string, req, reply interface{}, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error

UnaryClientInterceptor instruments client unary RPCs. This interceptor records each unary call with an external segment. Using it requires two steps:

1. Use this function with grpc.WithChainUnaryInterceptor or grpc.WithUnaryInterceptor when creating a grpc.ClientConn. Example:

conn, err := grpc.Dial(
	"localhost:8080",
	grpc.WithUnaryInterceptor(nrgrpc.UnaryClientInterceptor),
	grpc.WithStreamInterceptor(nrgrpc.StreamClientInterceptor),
)

2. Ensure that calls made with this grpc.ClientConn are done with a context which contains a newrelic.Transaction.

Full example: https://github.com/newrelic/go-agent/blob/master/_integrations/nrgrpc/example/client/client.go

This interceptor only instruments unary calls. You must use both UnaryClientInterceptor and StreamClientInterceptor to instrument unary and streaming calls. These interceptors add headers to the call metadata if distributed tracing is enabled.

func UnaryServerInterceptor

func UnaryServerInterceptor(app newrelic.Application) grpc.UnaryServerInterceptor

UnaryServerInterceptor instruments server unary RPCs.

Use this function with grpc.UnaryInterceptor and a newrelic.Application to create a grpc.ServerOption to pass to grpc.NewServer. This interceptor records each unary call with a transaction. You must use both UnaryServerInterceptor and StreamServerInterceptor to instrument unary and streaming calls.

Example:

cfg := newrelic.NewConfig("gRPC Server", os.Getenv("NEW_RELIC_LICENSE_KEY"))
app, _ := newrelic.NewApplication(cfg)
server := grpc.NewServer(
	grpc.UnaryInterceptor(nrgrpc.UnaryServerInterceptor(app)),
	grpc.StreamInterceptor(nrgrpc.StreamServerInterceptor(app)),
)

These interceptors add the transaction to the call context so it may be accessed in your method handlers using newrelic.FromContext.

Full example: https://github.com/newrelic/go-agent/blob/master/_integrations/nrgrpc/example/server/server.go