instaawssdk

README

Instana instrumentation for AWS SDK for Go v1

This module contains instrumentation code for AWS API clients that use github.com/aws/aws-sdk-go library v1.8.0 and above.

Following services are currently instrumented:

• DynamoDB
• S3
• SNS
• SQS

Installation

$ go get github.com/instana/go-sensor/instrumentation/instaawssdk

Usage

This instrumentation requires an instana.Sensor to initialize spans and handle the trace context propagation. You can create a new instance of Instana tracer using instana.NewSensor().

To trace requests made to the AWS API instrument the aws/session.Session using instaawssdk.InstrumentSession() before creating the service client:

sess := session.Must(session.NewSession(&aws.Config{}))

// Initialize Instana sensor
sensor := instana.NewSensor("my-aws-app")
// Instrument aws/session.Session
instaawssdk.InstrumentSession(sess, sensor)

// Create a service client using instrumented session
dynamoDBClient := dynamodb.New(sess)

// Use service client as usual
// ...

Instana tracer uses context.Context to propagate the trace context. To ensure trace continuation within the instrumented service use AWS SDK client methods that take context.Context as an argument. Usually these method names end with WithContext suffix, e.g.

• (*dynamodb.Client).PutItemWithContext()
• (*s3.Client).CreateBucketWithContext()
• (*sns.Client).PublishWithContext()
• (*sqs.Client).ReceiveMessagesWithContext()
• etc.

Instrumenting SQS consumers

An SQS client that uses instrumented session.Session automatically creates entry spans for each incoming sqs.Message. To use this entry span context as a parent in your message handler use instaawssdk.SpanContextFromSQSMessage():

func handleMessage(ctx context.Context, msg *sqs.Message) {
	if parent, ok := instaawssdk.SpanContextFromSQSMessage(msg, sensor); ok {
		sp := sensor.Tracer().StartSpan("handleMessage", opentracing.ChildOf(parent))
		defer sp.Finish()

		ctx = instana.ContextWithSpan(ctx, sp)
    }

    // ...
}

Documentation

Index

• Constants
• func FinalizeDynamoDBSpan(req *request.Request)
• func FinalizeS3Span(req *request.Request)
• func FinalizeSNSSpan(req *request.Request)
• func FinalizeSQSSpan(req *request.Request)
• func InstrumentSession(sess *session.Session, sensor *instana.Sensor)
• func SNSMessageAttributesCarrier(attrs map[string]*sns.MessageAttributeValue) messageAttributesCarrier
• func SQSMessageAttributesCarrier(attrs map[string]*sqs.MessageAttributeValue) messageAttributesCarrier
• func SpanContextFromSQSMessage(msg *sqs.Message, sensor *instana.Sensor) (opentracing.SpanContext, bool)
• func StartDynamoDBSpan(req *request.Request, sensor *instana.Sensor)
• func StartS3Span(req *request.Request, sensor *instana.Sensor)
• func StartSNSSpan(req *request.Request, sensor *instana.Sensor)
• func StartSQSSpan(req *request.Request, sensor *instana.Sensor)
• func TraceSQSMessage(msg *sqs.Message, sensor *instana.Sensor) opentracing.Span

Constants

const (
	// FieldT is the trace ID message attribute key
	FieldT = "X_INSTANA_T"
	// FieldS is the span ID message attribute key
	FieldS = "X_INSTANA_S"
	// FieldL is the trace level message attribute key
	FieldL = "X_INSTANA_L"
)

Functions

func FinalizeDynamoDBSpan

func FinalizeDynamoDBSpan(req *request.Request)

FinalizeDynamoDBSpan retrieves tags from completed request.Request and adds them to the span

func FinalizeS3Span

func FinalizeS3Span(req *request.Request)

FinalizeS3Span retrieves tags from completed request.Request and adds them to the span

func FinalizeSNSSpan

func FinalizeSNSSpan(req *request.Request)

FinalizeSNSSpan retrieves tags from completed request.Request and adds them to the span

func FinalizeSQSSpan

func FinalizeSQSSpan(req *request.Request)

FinalizeSQSSpan retrieves tags from completed request.Request and adds them to the span

func InstrumentSession

func InstrumentSession(sess *session.Session, sensor *instana.Sensor)

InstrumentSession instruments github.com/aws/aws-sdk-go/aws/session.Session by injecting handlers to create and finalize Instana spans

func SNSMessageAttributesCarrier

func SNSMessageAttributesCarrier(attrs map[string]*sns.MessageAttributeValue) messageAttributesCarrier

SNSMessageAttributesCarrier creates a new trace context carrier suitable for (opentracing.Tracer).Inject() that uses SNS message attributes as a storage

func SQSMessageAttributesCarrier

func SQSMessageAttributesCarrier(attrs map[string]*sqs.MessageAttributeValue) messageAttributesCarrier

SQSMessageAttributesCarrier creates a new trace context carrier suitable for (opentracing.Tracer).Inject() that uses SQS message attributes as a storage

func SpanContextFromSQSMessage

func SpanContextFromSQSMessage(msg *sqs.Message, sensor *instana.Sensor) (opentracing.SpanContext, bool)

SpanContextFromSQSMessage returns the trace context from an SQS message

func StartDynamoDBSpan

func StartDynamoDBSpan(req *request.Request, sensor *instana.Sensor)

StartDynamoDBSpan initiates a new span from an AWS DynamoDB request and injects it into the request.Request context

func StartS3Span

func StartS3Span(req *request.Request, sensor *instana.Sensor)

StartS3Span initiates a new span from an AWS S3 request and injects it into the request.Request context

func StartSNSSpan

func StartSNSSpan(req *request.Request, sensor *instana.Sensor)

StartSNSSpan initiates a new span from an AWS SNS request and injects it into the request.Request context

func StartSQSSpan

func StartSQSSpan(req *request.Request, sensor *instana.Sensor)

StartSQSSpan initiates a new span from an AWS SQS request and injects it into the request.Request context

func TraceSQSMessage

func TraceSQSMessage(msg *sqs.Message, sensor *instana.Sensor) opentracing.Span

TraceSQSMessage creates an returns an entry span for an SQS message. The context of this span is injected into message attributes. This context can than be retrieved with instaawssdk.SpanContextFromSQSMessage() and used in the message handler method to continue the trace.