Need help with aws-xray-sdk-go?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

238 Stars 95 Forks Apache License 2.0 256 Commits 25 Opened issues


AWS X-Ray SDK for the Go programming language.

Services available


Need anything else?

Contributors list


AWS X-Ray SDK for Go

Screenshot of the AWS X-Ray console

Installing into GOPATH

The AWS X-Ray SDK for Go is compatible with Go 1.9 and above.

Install the SDK using the following command (The SDK's non-testing dependencies will be installed): Use

go get
to retrieve the SDK to add it to your
go get

To update the SDK, use

go get -u
to retrieve the latest version of the SDK.
go get -u

If you also want to install SDK's testing dependencies. They can be installed using:

go get -u -t

Installing using Go Modules

The latest version of the SDK is the recommended version.

If you are using Go 1.11 and above, you can install the SDK using Go Modules (in project's go.mod), like so:

go get

To get a different specific release version of the SDK use

in your
go get
command. Also, to get the rc version use this command with the specific version.
go get[email protected]

Installing using Dep

If you are using Go 1.9 and above, you can also use Dep to add the SDK to your application's dependencies. Using Dep will help your application stay pinned to a specific version of the SDK.

To add the SDK to your application using Dep, run:

dep ensure -add

Getting Help

Please use these community resources for getting help. We use the GitHub issues for tracking bugs and feature requests.

Opening Issues

If you encounter a bug with the AWS X-Ray SDK for Go we would like to hear about it. Search the existing issues and see if others are also experiencing the issue before opening a new issue. Please include the version of AWS X-Ray SDK for Go, AWS SDK for Go, Go language, and OS you’re using. Please also include repro case when appropriate.

The GitHub issues are intended for bug reports and feature requests. For help and questions regarding the use of the AWS X-Ray SDK for Go please make use of the resources listed in the Getting Help section. Keeping the list of open issues lean will help us respond in a timely manner.


The developer guide provides in-depth guidance on using the AWS X-Ray service and the AWS X-Ray SDK for Go.

See aws-xray-sdk-go-sample for a sample application that provides example of tracing SQL queries, incoming and outgoing request. Follow README instructions in that repository to get started with sample application.

Quick Start


import ""

func init() { xray.Configure(xray.Config{ DaemonAddr: "", // default ServiceVersion: "1.2.3", }) }


xray uses an interface for its logger:

type Logger interface {
  Log(level LogLevel, msg fmt.Stringer)

const ( LogLevelDebug LogLevel = iota + 1 LogLevelInfo LogLevelWarn LogLevelError )

The default logger logs to stdout at "info" and above. To change the logger, call

. There is a default logger implementation that writes to an
from a specified minimum log level. For example, to log to stderr at "error" and above:
xray.SetLogger(xraylog.NewDefaultLogger(os.Stderr, xraylog.LogLevelError))

Note that the

are deprecated starting from version
and no longer have any effect.


Plugins can be loaded conditionally at runtime. For this purpose, plugins under "" have an explicit

function. Customer must call this method to load the plugin:
import (

"" "" )

func init() { // conditionally load plugin if os.Getenv("ENVIRONMENT") == "production" { ec2.Init() }

xray.Configure(xray.Config{ ServiceVersion: "1.2.3", }) }

Start a custom segment/subsegment Note that customers using xray.BeginSegment API directly will only be able to evaluate sampling rules based on service name.

  // Start a segment
  ctx, seg := xray.BeginSegment(context.Background(), "service-name")
  // Start a subsegment
  subCtx, subSeg := xray.BeginSubsegment(ctx, "subsegment-name")
  // ...
  // Add metadata or annotation here if necessary
  // ...
  // Close the segment

Generate no-op trace and segment id

X-Ray Go SDK will by default generate no-op trace and segment id for unsampled requests and secure random trace and entity id for sampled requests. If customer wants to enable generating secure random trace and entity id for all the (sampled/unsampled) requests (this is applicable for trace id injection into logs use case) then they achieve that by setting AWSXRAYNOOP_ID environment variable as False.

Disabling XRay Tracing

XRay tracing can be disabled by setting up environment variable

. Disabling XRay can be useful for specific use case like if customer wants to stop tracing in their test environment they can do so just by setting up the environment variable.
  // Set environment variable TRUE to disable XRay


func criticalSection(ctx context.Context) {
  // This example traces a critical code path using a custom subsegment
  xray.Capture(ctx, "MyService.criticalSection", func(ctx1 context.Context) error {
    var err error

result := someLockedResource.Go()

xray.AddMetadata(ctx1, "ResourceResult", result)

}) }

HTTP Handler

func main() {
  http.Handle("/", xray.Handler(xray.NewFixedSegmentNamer("myApp"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
  http.ListenAndServe(":8000", nil)

HTTP Client

func getExample(ctx context.Context) ([]byte, error) {
    resp, err := ctxhttp.Get(ctx, xray.Client(nil), "")
    if err != nil {
      return nil, err
    return ioutil.ReadAll(resp.Body)

AWS SDK Instrumentation

sess := session.Must(session.NewSession())
dynamo := dynamodb.New(sess)
dynamo.ListTablesWithContext(ctx, &dynamodb.ListTablesInput{})

AWS SDK V2 Instrumentation

package main

import ( "context" "log"



func main() { ctx, root := xray.BeginSegment(context.TODO(), "AWSSDKV2_Dynamodb") defer root.Close(nil) cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-west-2")) if err != nil { log.Fatalf("unable to load SDK config, %v", err) } // Instrumenting AWS SDK v2 awsv2.AWSV2Instrumentor(&cfg.APIOptions) // Using the Config value, create the DynamoDB client svc := dynamodb.NewFromConfig(cfg) // Build the request with its input parameters _, err = svc.ListTables(ctx, &dynamodb.ListTablesInput{ Limit: aws.Int32(5), }) if err != nil { log.Fatalf("failed to list tables, %v", err) } }


does not currently support
operations and will panic if one is encountered. This results in an error similar to:

panic: failed to begin subsegment named 's3': segment cannot be found.

If you encounter this, you can set

environment variable to
. This will instruct the SDK to log the error and continue processing your requests.



calls can be traced with X-Ray by replacing the
call with
. It is recommended to use URLs instead of configuration strings if possible.
func main() {
  db, err := xray.SQLContext("postgres", "postgres://user:[email protected]:port/db")
  row, err := db.QueryRowContext(ctx, "SELECT 1") // Use as normal


For Lambda support use version v1.0.0-rc.1 and higher

If you are using the AWS X-Ray Go SDK inside a Lambda function, there will be a FacadeSegment inside the Lambda context. This allows you to instrument your Lambda function using

HTTP Client
Custom Subsegments
operations are not supported.
func HandleRequest(ctx context.Context, name string) (string, error) {
    sess := session.Must(session.NewSession())
    dynamo := dynamodb.New(sess)
    input := &dynamodb.PutItemInput{
        Item: map[string]*dynamodb.AttributeValue{
            "12": {
                S: aws.String("example"),
        TableName: aws.String("xray"),
    _, err := dynamo.PutItemWithContext(ctx, input)
    if err != nil {
        return name, err

_, err = ctxhttp.Get(ctx, xray.Client(nil), "")
if err != nil {
    return name, err

_, subseg := xray.BeginSubsegment(ctx, "subsegment-name")

db := xray.SQLContext("postgres", "postgres://user:[email protected]:port/db")
row, _ := db.QueryRow(ctx, "SELECT 1")

return fmt.Sprintf("Hello %s!", name), nil




doesn't currently support streaming gRPC call.

Apply xray gRPC interceptors (

) to instrument gRPC unary requests/responses, and the handling code.

gRPC Client

conn, err := grpc.Dial(
    // use grpc.WithChainUnaryInterceptor instead to apply multiple interceptors
        // or xray.UnaryClientInterceptor(xray.WithSegmentNamer(xray.NewFixedSegmentNamer("myApp"))) to use a custom segment namer

gRPC Server

grpcServer := grpc.NewServer(
    // use grpc.ChainUnaryInterceptor instead to apply multiple interceptors
        // or xray.UnaryServerInterceptor(xray.WithSegmentNamer(xray.NewFixedSegmentNamer("myApp"))) to use a custom segment namer

fasthttp instrumentation

Support for incoming requests with valyala/fasthttp:

package main

import ( "fmt" "log" "os"



func index(ctx *fasthttp.RequestCtx) { ctx.WriteString("Welcome!") }

func hello(ctx *fasthttp.RequestCtx) { fmt.Fprintf(ctx, "Hello, %s!\n", ctx.UserValue("name")) }

func middleware(name string, h fasthttp.RequestHandler, fh xray.FastHTTPHandler) fasthttp.RequestHandler { f := func(ctx *fasthttp.RequestCtx) { h(ctx) }

return fh.Handler(xray.NewFixedSegmentNamer(name), f)


func init() { if err := xray.Configure(xray.Config{ DaemonAddr: "xray:2000", ServiceVersion: "0.1", }); err != nil { panic(err) }

xray.SetLogger(xraylog.NewDefaultLogger(os.Stdout, xraylog.LogLevelDebug))


func main() { fh := xray.NewFastHTTPInstrumentor(nil) r := router.New() r.GET("/", middleware("index", index, fh)) r.GET("/hello/{name}", middleware("hello", hello, fh))

log.Fatal(fasthttp.ListenAndServe(":8080", r.Handler))



The AWS X-Ray SDK for Go is licensed under the Apache 2.0 License. See LICENSE and NOTICE.txt for more information.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.