otellambda

package module
v0.54.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 23, 2024 License: Apache-2.0 Imports: 14 Imported by: 18

README

OpenTelemetry AWS Lambda Instrumentation for Golang

Go Reference Apache License

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 propagation.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{})))
}

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

View Source
const (
	// ScopeName is the instrumentation scope name.
	ScopeName = "go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda"
)

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 deprecated

func SemVersion() string

SemVersion is the semantic version to be supplied to tracer/meter creation.

Deprecated: Use Version instead.

func Version

func Version() string

Version is the current release version of the AWS Lambda instrumentation.

func WrapHandler

func WrapHandler(handler lambda.Handler, options ...Option) lambda.Handler

WrapHandler Provides a Handler which wraps customer Handler with OTel Tracing.

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

type Flusher interface {
	ForceFlush(context.Context) error
}

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 WithFlusher

func WithFlusher(flusher Flusher) Option

WithFlusher sets the used flusher.

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.

Directories

Path Synopsis
example module
test module
xrayconfig module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL