README.md

Recommended Configurations for OpenTelemetry AWS Lambda Instrumentation with AWS X-Ray

This module provides recommended configuration options for AWS Lambda Instrumentation when using AWS X-Ray. By using this configuration, trace context will automatically be extracted from incoming requests with the X-Amzn-Trace-Id header if present. Trace context will also always be injected using the X-Amzn-Trace-Id format into downstream requests from the Lambda function.

Installation

go get -u go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda/xrayconfig

Usage

Create a sample Lambda Go application instrumented by the otellambda package such as below.

package main

import (
	"context"
	"fmt"
	"github.com/aws/aws-lambda-go/lambda"
	"go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda"
)

type MyEvent struct {
	Name string `json:"name"`
}

func HandleRequest(ctx context.Context, name MyEvent) (string, error) {
	return fmt.Sprintf("Hello %s!", name.Name ), nil
}

func main() {
	lambda.Start(otellambda.InstrumentHandler(HandleRequest))
}

Now configure the instrumentation with the provided options to export traces to AWS X-Ray via the OpenTelemetry Collector running as a Lambda Extension. Instructions for running the OTel Collector as a Lambda Extension can be found in the AWS OpenTelemetry Documentation.

// Add import
import "go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda/xrayconfig"

// add options to InstrumentHandler call
func main() {
	lambda.Start(otellambda.InstrumentHandler(HandleRequest, xrayconfig.RecommendedOptions()...))
}

Recommended AWS Lambda Instrumentation Options

Instrumentation Option	Recommended Value	Exported As
WithTracerProvider	An sdktrace.TracerProvider configured to export in batches to an OTel Collector running locally in Lambda	Not individually exported. Can only be used via RecommendedOptions()
WithFlusher	An otellambda.Flusher which yields before calling ForceFlush on the configured sdktrace.TracerProvider. Yielding mitigates data delays caused by asynchronous nature of batching TracerProvider when in Lambda	Not individually exported. Can only be used via RecommendedOptions()
WithEventToCarrier	Function which reads X-Ray TraceID from Lambda environment and inserts it into a propagtation.TextMapCarrier	Individually exported as EventToCarrier(), also included in RecommendedOptions()
WithPropagator	An xray.propagator	Individually exported as Propagator(), also included in RecommendedOptions()

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry Go: https://github.com/open-telemetry/opentelemetry-go
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.