powertools-lambda-go

README

Go Powertools Lambda

Go Powertools provides structured logging, OpenTelemetry tracing, metrics and other utilities for native Go AWS Lambda applications. This independent community project uses Powertools for AWS Lambda (TypeScript) v2.35.0 as its behavioral reference. See the supported scope for differences and limitations.

Go Powertools documentation · Getting started · Modules

Powertools Lambda Go targets native Go applications on AWS Lambda. Install only the utilities you need; this is an independent community project, not an official AWS distribution.

Install

Use Go 1.27 or newer for the current source. Lambda binaries target provided.al2023, with Linux amd64 (x86_64) or arm64. Keep CGO disabled.

The latest stable version is v1.1.0. This README follows main; the installation and minimal example below use that published version. See version policy for released APIs versus development changes.

From a new application directory in PowerShell:

$env:CGO_ENABLED = '0'
go mod init example.com/hello
go get github.com/rambow-cloud/powertools-lambda-go/logger@v1.1.0 github.com/aws/aws-lambda-go@v1.55.0

Each utility has its own module. Install the modules you use; see module installation.

Your first Lambda

Save this complete example as main.go:

package main

import (
    "context"
    "fmt"

    "github.com/aws/aws-lambda-go/lambda"
    "github.com/rambow-cloud/powertools-lambda-go/logger"
)

type Event struct {
    Name string `json:"name"`
}

type Response struct {
    Message string `json:"message"`
}

func main() {
    appLog := logger.New(logger.WithServiceName("hello"))
    handler := func(ctx context.Context, event Event) (Response, error) {
        if event.Name == "" {
            return Response{}, fmt.Errorf("name is required")
        }
        requestLog := appLog.WithContext(ctx)
        if err := requestLog.Info("Handling request", logger.Fields{"name": event.Name}); err != nil {
            return Response{}, fmt.Errorf("write request log: %w", err)
        }
        return Response{Message: "Hello, " + event.Name}, nil
    }
    lambda.Start(logger.WrapHandler(appLog, handler))
}

An input of {"name":"Ada"} returns {"message":"Hello, Ada"} and writes a structured log with message: "Handling request", service: "hello" and name: "Ada". An empty name returns a handler error. Create the Logger once; use WithContext(ctx) inside its wrapper to isolate invocation fields.

Build for the architecture selected on your Lambda function:

$env:CGO_ENABLED = '0'
$env:GOOS = 'linux'
$env:GOARCH = 'arm64' # Use 'amd64' for Lambda x86_64.
go build -trimpath -tags lambda.norpc -o bootstrap .

Package bootstrap with executable permissions and configure provided.al2023. The quickstart shows repository packaging and OpenTelemetry composition.

Documentation

Read the documentation site or Go package documentation.

Area	Guides
Observability	Logger, Tracer, Metrics
Configuration and persistence	Parameters, Idempotency, Redis/Valkey
Event processing	Batch, Parser, Validation, Kafka
Event handlers	HTTP, AppSync Events, GraphQL, Bedrock
Shared tools	Masking, Signer, JMESPath, Commons, Metadata

Tracing uses OpenTelemetry, including X-Ray delivery through a collector's awsxray exporter. The legacy tracer/xray adapter is deprecated and frozen; retain its migration warning.

See Releases, v1 readiness and the feature comparison.

Contributing

Follow the issue → branch → PR → review workflow. See module development and local integration for checks. Root go test ./... covers only the root module; use tools/modules.py check with CGO_ENABLED=0 to verify nested modules and consumers.

License

Original contributions use the MIT License. Preserved attribution is listed in THIRD_PARTY_NOTICES.md and each module's NOTICE. This is an independent project, not an official AWS distribution.