README
¶
OpenTelemetry AWS Lambda Instrumentation for Golang
This module provides instrumentation for AWS Lambda.
Installation
go get -u go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda
example
See ./example
Usage
Create a sample Lambda Go application such as below.
package main
import (
"context"
"fmt"
"github.com/aws/aws-lambda-go/lambda"
)
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(HandleRequest)
}
Now use the provided wrapper to instrument your basic Lambda function:
// Add import
import "go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda"
// wrap lambda handler function
func main() {
lambda.Start(otellambda.InstrumentHandler(HandleRequest))
}
AWS Lambda Instrumentation Options
| Options | Input Type | Description | Default |
|---|---|---|---|
WithTracerProvider |
trace.TracerProvider |
Provide a custom TracerProvider for creating spans. Consider using the AWS Lambda Resource Detector with your tracer provider to improve tracing information. |
otel.GetTracerProvider() |
WithFlusher |
otellambda.Flusher |
This instrumentation will call the ForceFlush method of its Flusher at the end of each invocation. Should you be using asynchronous logic (such as sddktrace's BatchSpanProcessor) it is very import for spans to be ForceFlush'ed before Lambda freezes to avoid data delays. |
Flusher with noop ForceFlush |
WithEventToCarrier |
func(eventJSON []byte) propagation.TextMapCarrier{} |
Function for providing custom logic to support retrieving trace header from different event types that are handled by AWS Lambda (e.g., SQS, CloudWatch, Kinesis, API Gateway) and returning them in a propagation.TextMapCarrier which a Propagator can use to extract the trace header into the context. |
Function which returns an empty TextMapCarrier - new spans will be part of a new Trace and have no parent past Lambda instrumentation span |
WithPropagator |
propagation.Propagator |
The Propagator the instrumentation will use to extract trace information into the context. |
otel.GetTextMapPropagator() |
Usage With Options Example
var someHeaderKey = "Key" // used by propagator and EventToCarrier function to identify trace header
type mockHTTPRequest struct {
Headers map[string][]string
Body string
}
func mockEventToCarrier(eventJSON []byte) propagation.TextMapCarrier{
var request mockHTTPRequest
_ = json.unmarshal(eventJSON, &request)
return propogation.HeaderCarrier{someHeaderKey: []string{request.Headers[someHeaderKey]}}
}
type mockPropagator struct{}
// Extract - read from `someHeaderKey`
// Inject
// Fields
func HandleRequest(ctx context.Context, request mockHTTPRequest) error {
return fmt.Sprintf("Hello %s!", request.Body ), nil
}
func main() {
exp, _ := stdouttrace.New()
tp := sdktrace.NewTracerProvider(
sdktrace.WithBatcher(exp))
lambda.Start(otellambda.InstrumentHandler(HandleRequest,
otellambda.WithTracerProvider(tp),
otellambda.WithFlusher(tp),
otellambda.WithEventToCarrier(mockEventToCarrier),
otellambda.WithPropagator(mockPropagator{})))
}
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.
Documentation
¶
Overview ¶
Package otellambda instruments the github.com/aws/aws-lambda-go package.
Two wrappers are provided which can be used to instrument Lambda, one for each Lambda entrypoint. Their usages are shown below.
lambda.Start(<user function>) entrypoint: lambda.Start(otellambda.InstrumentHandler(<user function>)) lambda.StartHandler(<user Handler>) entrypoint: lambda.StartHandler(otellambda.WrapHandler(<user Handler>))
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func InstrumentHandler ¶
func InstrumentHandler(handlerFunc interface{}, options ...Option) interface{}
InstrumentHandler Provides a lambda handler which wraps customer lambda handler with OTel Tracing.
func SemVersion ¶
func SemVersion() string
SemVersion is the semantic version to be supplied to tracer/meter creation.
Types ¶
type EventToCarrier ¶
type EventToCarrier func(eventJSON []byte) propagation.TextMapCarrier
An EventToCarrier function defines how the instrumentation should prepare a TextMapCarrier for the configured propagator to read from. This extra step is necessary because Lambda does not have HTTP headers to read from and instead stores the headers it was invoked with (including TraceID, etc.) as part of the invocation event. If using the AWS XRay tracing then the trace information is instead stored in the Lambda environment.
type Flusher ¶
A Flusher dictates how the instrumentation will attempt to flush unexported spans at the end of each Lambda innovation. This is very important in asynchronous settings because the Lambda runtime may enter a 'frozen' state any time after the invocation completes. Should this freeze happen and spans are left unexported, there can be a long delay before those spans are exported.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option applies a configuration option.
func WithEventToCarrier ¶
func WithEventToCarrier(eventToCarrier EventToCarrier) Option
WithEventToCarrier sets the used EventToCarrier.
func WithPropagator ¶
func WithPropagator(propagator propagation.TextMapPropagator) Option
WithPropagator configures the propagator used by the instrumentation.
By default, the global TextMapPropagator will be used.
func WithTracerProvider ¶
func WithTracerProvider(tracerProvider trace.TracerProvider) Option
WithTracerProvider configures the TracerProvider used by the instrumentation.
By default, the global TracerProvider is used.
Source Files
Directories