instaawssdk

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
• Lambda
  • Read about usage and limitations here

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
// ...

Important Note:

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()
• (*lambda.Lambda).InvokeWithContext()
• 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)
    }

    // ...
}

Instrumenting calls to AWS Lambda

If a session is instrumented, it will propagate tracing context automatically using values from the ctx.

Example:

sensor := instana.NewSensor("my-new-sensor")
sess, _ := session.NewSession()
instaawssdk.InstrumentSession(sess, sensor)
svc := sdk.New(sess)
input := &sdk.InvokeInput{
    FunctionName: "my-lambda-function-name",
    // this field is optional
    // IMPORTANT type `Event` is not supported by the instrumentation
    InvocationType: aws.String("RequestResponse"), 
    Payload: []byte("{}"),
}

// invoke with context, otherwise, you will need to set context manually to propagate tracing data
svc.InvokeWithContext(ctx, input)

Tracing context propagated inside a ClientContext.Custom field in the InvokeInput object. Reserved keys are:

• x-instana-t
• x-instana-s
• x-instana-l

To avoid collisions, it is recommended to avoid setting them in your application code.

Known limitations:

• Current instrumentation does not support asynchronous lambda invocation.
• If the length of base64 encoded ClientContext will exceed 3582 bytes, tracing headers will be not propagated.
• Deprecated methods like InvokeAsync, InvokeAsyncWithContext etc. are not supported.