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:
Installation
$ go get github.com/instana/go-sensor/instrumentation/instaawssdk
Usage
This instrumentation requires an instana.Collector
to initialize spans and handle the trace context propagation.
You can create a new instance of Instana Collector using instana.InitCollector()
.
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 collector
collector := instana.InitCollector(&instana.Options{
Service: "my-aws-app",
})
// Instrument aws/session.Session
instaawssdk.InstrumentSession(sess, collector)
// 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, collector); ok {
sp := collector.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:
collector := instana.InitCollector(&instana.Options{
Service: "my-lambda-service",
})
sess, _ := session.NewSession()
instaawssdk.InstrumentSession(sess, collector)
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
- 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.37.0"
Version is the instrumentation module semantic version
Variables ¶
This section is empty.
Functions ¶
func FinalizeDynamoDBSpan ¶
FinalizeDynamoDBSpan retrieves tags from completed request.Request and adds them to the span
func FinalizeInvokeLambdaSpan ¶ added in v1.1.0
FinalizeInvokeLambdaSpan retrieves error from completed request.Request if any and adds it to the span
func FinalizeS3Span ¶
FinalizeS3Span retrieves tags from completed request.Request and adds them to the span
func FinalizeSNSSpan ¶
FinalizeSNSSpan retrieves tags from completed request.Request and adds them to the span
func FinalizeSQSSpan ¶
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 NewSession ¶ added in v1.2.0
NewSession is a wrapper for `session.NewSession`
func NewSessionWithOptions ¶ added in v1.2.0
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 ¶ added in v1.1.0
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 ¶ added in v1.1.0
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 ¶ added in v1.1.0
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 ¶ added in v1.1.0
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 ¶ added in v1.1.0
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.