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

Documentation

Overview

Package instaawssdk instruments github.com/aws/aws-sdk-go

Index

• Constants
• func FinalizeDynamoDBSpan(req *request.Request)
• func FinalizeInvokeLambdaSpan(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.TracerLogger)
• func New(sensor instana.TracerLogger, cfgs ...*aws.Config) *session.Session
• func NewSession(sensor instana.TracerLogger, cfgs ...*aws.Config) (*session.Session, error)
• func NewSessionWithOptions(sensor instana.TracerLogger, opts session.Options) (*session.Session, error)
• func SNSMessageAttributesCarrier(attrs map[string]*sns.MessageAttributeValue) messageAttributesCarrier
• func SQSMessageAttributesCarrier(attrs map[string]*sqs.MessageAttributeValue) messageAttributesCarrier
• func SpanContextFromSQSMessage(msg *sqs.Message, sensor instana.TracerLogger) (opentracing.SpanContext, bool)
• func StartDynamoDBSpan(req *request.Request, sensor instana.TracerLogger)
• func StartInvokeLambdaSpan(req *request.Request, sensor instana.TracerLogger)
• func StartS3Span(req *request.Request, sensor instana.TracerLogger)
• func StartSNSSpan(req *request.Request, sensor instana.TracerLogger)
• func StartSQSSpan(req *request.Request, sensor instana.TracerLogger)
• func TraceSQSMessage(msg *sqs.Message, sensor instana.TracerLogger) opentracing.Span
• type LambdaClientContext
  • func NewLambdaClientContextFromBase64EncodedJSON(data string) (LambdaClientContext, error)
  • func (lc *LambdaClientContext) Base64JSON() (string, error)
• type LambdaClientContextClientApplication

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"
)

const Version = "1.17.1"

Version is the instrumentation module semantic version

Functions

func FinalizeDynamoDBSpan

func FinalizeDynamoDBSpan(req *request.Request)

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

func FinalizeInvokeLambdaSpan

func FinalizeInvokeLambdaSpan(req *request.Request)

FinalizeInvokeLambdaSpan retrieves error from completed request.Request if any and adds it 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.TracerLogger)

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

func New

func New(sensor instana.TracerLogger, cfgs ...*aws.Config) *session.Session

New is a wrapper for `session.New`

func NewSession

func NewSession(sensor instana.TracerLogger, cfgs ...*aws.Config) (*session.Session, error)

NewSession is a wrapper for `session.NewSession`

func NewSessionWithOptions

func NewSessionWithOptions(sensor instana.TracerLogger, opts session.Options) (*session.Session, error)

NewSessionWithOptions is a wrapper for `session.NewSessionWithOptions`

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.TracerLogger) (opentracing.SpanContext, bool)

SpanContextFromSQSMessage returns the trace context from an SQS message

func StartDynamoDBSpan

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

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

func StartInvokeLambdaSpan

func StartInvokeLambdaSpan(req *request.Request, sensor instana.TracerLogger)

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

func StartS3Span

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

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.TracerLogger)

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.TracerLogger)

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.TracerLogger) 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.

Types

type LambdaClientContext

type LambdaClientContext struct {
	Client LambdaClientContextClientApplication
	Env    map[string]string `json:"env"`
	Custom map[string]string `json:"custom"`
}

LambdaClientContext represents ClientContext from the AWS Invoke call https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html#API_Invoke_RequestSyntax.

func NewLambdaClientContextFromBase64EncodedJSON

func NewLambdaClientContextFromBase64EncodedJSON(data string) (LambdaClientContext, error)

NewLambdaClientContextFromBase64EncodedJSON creates LambdaClientContext from the base64 encoded JSON or returns error if there is decoding error.

func (*LambdaClientContext) Base64JSON

func (lc *LambdaClientContext) Base64JSON() (string, error)

Base64JSON marshal LambdaClientContext to JSON and returns it as the base64 encoded string or error if any occurs.

type LambdaClientContextClientApplication

type LambdaClientContextClientApplication struct {
	InstallationID string `json:"installation_id"`
	AppTitle       string `json:"app_title"`
	AppVersionCode string `json:"app_version_code"`
	AppPackageName string `json:"app_package_name"`
}

LambdaClientContextClientApplication represent client application specific data part of the LambdaClientContext.