xray_grpc

README

gRPC Interceptors for AWS X-Ray Tracing

Provides Go gRPC Unary Client and Server Interceptors for AWS X-Ray that play nicely with the AWS X-Ray SDK (and existing AWS X-Ray HTTP wrappers).

Why

The AWS X-Ray SDK's do not currently provide native support for gRPC client/server wrappers (see https://github.com/aws/aws-xray-sdk-go/issues/110). This repository provides a temporary solution while there is no native gRPC support.

Usage

For both Client and Server Interceptors, setup the AWS X-Ray SDK normally:

xray.Configure(xray.Config{
    ...
})

and import the xray-grpc module:

import "github.com/vendrive/xray-grpc"

Both Client and Server Interceptors use the AWS X-Ray SDK, and support most features. Check main.go (code is minimal) if you are curious if your use case is supported.

Note: Populating URL, gRPC error codes, and Content Length in segments are currently not supported.

gRPC Unary Client

// Converts the grpc.ClientConn target (first parameter passed to grpc.Dial below) into your preferred outbound server name
customHostFromTarget = func (target string) string {
    withoutPort := target[:strings.IndexByte(target, ':')]
    return strings.ReplaceAll(withoutPort, ".my-namespace.local", "")
}

conn, err := grpc.Dial("my-service.my-namespace.local:3000",
                       grpc.WithInsecure(),
                       grpc.WithUnaryInterceptor(xray_grpc.NewGrpcXrayUnaryClientInterceptor(customHostFromTarget)))

gRPC Unary Server

// NewFixedSegmentNamer is the only segment namer currently supported
s := grpc.NewServer(grpc.UnaryInterceptor(xray_grpc.NewGrpcXrayUnaryServerInterceptor(xray.NewFixedSegmentNamer("my-service"))))

Resources

• https://github.com/aws/aws-xray-sdk-go/
• https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md

Documentation

Overview

Library for tracing gRPC client/server interactions via AWS X-Ray

Index

• Constants
• func GetDefaultHostFromTargetFunc(namespace string) func(string) string
• func NewGrpcXrayUnaryClientInterceptor(hostFromTarget func(string) string) grpc.UnaryClientInterceptor
• func NewGrpcXrayUnaryServerInterceptor(sn xray.SegmentNamer) grpc.UnaryServerInterceptor

Constants

const (
	GrpcMethod      = "POST"
	CustomUserAgent = "Vendrive-gRPC-XRAY-Interceptor"
)

Functions

func GetDefaultHostFromTargetFunc

func GetDefaultHostFromTargetFunc(namespace string) func(string) string

func NewGrpcXrayUnaryClientInterceptor

func NewGrpcXrayUnaryClientInterceptor(hostFromTarget func(string) string) grpc.UnaryClientInterceptor

Returns a UnaryClientInterceptor that supports populating gRPC metadata with AWS X-Ray information. Parameter hostFromTarget allows you to translate the grpc.ClientConn target into your preferred outbound server name. DNS Information, URL, gRPC error codes, and Content Length are currently not supported. Usage:

customHostFromTarget = func (target string) string {
    withoutPort := target[:strings.IndexByte(target, ':')]
	   return strings.ReplaceAll(withoutPort, ".my-namespace.local", "")
}

conn, err := grpc.Dial("my-service.my-namespace.local:3000",

grpc.WithInsecure(),
grpc.WithUnaryInterceptor(xray_grpc.NewGrpcXrayUnaryClientInterceptor(customHostFromTarget)))

func NewGrpcXrayUnaryServerInterceptor

func NewGrpcXrayUnaryServerInterceptor(sn xray.SegmentNamer) grpc.UnaryServerInterceptor

Returns a UnaryServerInterceptor that supports reading gRPC metadata that contains AWS X-Ray information. Intended to recieve requests from a gRPC client that uses NewGrpcXrayUnaryClientInterceptor. Currently only supports NewFixedSegmentNamer for parameter sn. Populating URL, gRPC error codes, and Content Length in segments are currently not supported. Usage:

s := grpc.NewServer(grpc.UnaryInterceptor(xray_grpc.NewGrpcXrayUnaryServerInterceptor(xray.NewFixedSegmentNamer("my-service"))))