# Building Lambda functions with Go
Go is implemented differently than other managed runtimes. Because Go compiles natively to an executable binary, it doesn't require a dedicated language runtime. Use an [OS-only runtime](runtimes-provided.md) (the `provided` runtime family) to deploy Go functions to Lambda.
**Topics**
+ [Go runtime support](#golang-al1)
+ [Tools and libraries](#golang-libraries)
+ [Define Lambda function handlers in Go](golang-handler.md)
+ [Using the Lambda context object to retrieve Go function information](golang-context.md)
+ [Deploy Go Lambda functions with .zip file archives](golang-package.md)
+ [Deploy Go Lambda functions with container images](go-image.md)
+ [Working with layers for Go Lambda functions](golang-layers.md)
+ [Log and monitor Go Lambda functions](golang-logging.md)
+ [Instrumenting Go code in Amazon Lambda](golang-tracing.md)
## Go runtime support
The Go 1.x managed runtime for Lambda is [deprecated](lambda-runtimes.md#runtime-support-policy). If you have functions that use the Go 1.x runtime, you must migrate your functions to `provided.al2023` or `provided.al2`. The `provided.al2023` and `provided.al2` runtimes offer several advantages over `go1.x`, including support for the arm64 architecture (Amazon Graviton2 processors), smaller binaries, and slightly faster invoke times.
No code changes are required for this migration. The only required changes relate to how you build your deployment package and which runtime you use to create your function. For more information, see [Migrating Amazon Lambda functions from the Go1.x runtime to the custom runtime on Amazon Linux 2](https://amazonaws-china.com/blogs/compute/migrating-aws-lambda-functions-from-the-go1-x-runtime-to-the-custom-runtime-on-amazon-linux-2/) on the *Amazon Compute Blog*.
| Name | Identifier | Operating system | Deprecation date | Block function create | Block function update |
| --- | --- | --- | --- | --- | --- |
| OS-only Runtime | `provided.al2023` | Amazon Linux 2023 | Jun 30, 2029 | Jul 31, 2029 | Aug 31, 2029 |
| OS-only Runtime | `provided.al2` | Amazon Linux 2 | Jul 31, 2026 | Aug 31, 2026 | Sep 30, 2026 |
## Tools and libraries
Lambda provides the following tools and libraries for the Go runtime:
+ [Amazon SDK for Go v2](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2): The official Amazon SDK for the Go programming language.
+ [github.com/aws/aws-lambda-go/lambda](https://github.com/aws/aws-lambda-go/tree/master/lambda): The implementation of the Lambda programming model for Go. This package is used by Amazon Lambda to invoke your [handler](golang-handler.md).
+ [github.com/aws/aws-lambda-go/lambdacontext](https://github.com/aws/aws-lambda-go/tree/master/lambdacontext): Helpers for accessing context information from the [context object](golang-context.md).
+ [github.com/aws/aws-lambda-go/events](https://github.com/aws/aws-lambda-go/tree/master/events): This library provides type definitions for common event source integrations.
+ [github.com/aws/aws-lambda-go/cmd/build-lambda-zip](https://github.com/aws/aws-lambda-go/tree/master/cmd/build-lambda-zip): This tool can be used to create a .zip file archive on Windows.
For more information, see [aws-lambda-go](https://github.com/aws/aws-lambda-go) on GitHub.
Lambda provides the following sample applications for the Go runtime:
**Sample Lambda applications in Go**
+ [go-al2](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/go-al2) – A hello world function that returns the public IP address. This app uses the `provided.al2` custom runtime.
+ [blank-go](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-go) – A Go function that shows the use of Lambda's Go libraries, logging, environment variables, and the Amazon SDK. This app uses the `go1.x` runtime.
# Define Lambda function handlers in Go
The Lambda function *handler* is the method in your function code that processes events. When your function is invoked, Lambda runs the handler method. Your function runs until the handler returns a response, exits, or times out.
This page describes how to work with Lambda function handlers in Go, including project setup, naming conventions, and best practices. This page also includes an example of a Go Lambda function that takes in information about an order, produces a text file receipt, and puts this file in an Amazon Simple Storage Service (Amazon S3) bucket. For information about how to deploy your function after writing it, see [Deploy Go Lambda functions with .zip file archives](golang-package.md) or [Deploy Go Lambda functions with container images](go-image.md).
**Topics**
+ [Setting up your Go handler project](#golang-handler-setup)
+ [Example Go Lambda function code](#golang-example-code)
+ [Handler naming conventions](#golang-handler-naming)
+ [Defining and accessing the input event object](#golang-example-input)
+ [Accessing and using the Lambda context object](#golang-example-context)
+ [Valid handler signatures for Go handlers](#golang-handler-signatures)
+ [Using the Amazon SDK for Go v2 in your handler](#golang-example-sdk-usage)
+ [Accessing environment variables](#golang-example-envvars)
+ [Using global state](#golang-handler-state)
+ [Code best practices for Go Lambda functions](#go-best-practices)
## Setting up your Go handler project
A Lambda function written in [Go](https://golang.org/) is authored as a Go executable. You can initialize a Go Lambda function project the same way you initialize any other Go project using the following `go mod init` command:
```
go mod init example-go
```
Here, `example-go` is the module name. You can replace this with anything. This command initializes your project and generates the `go.mod` file that lists your project's dependencies.
Use the `go get` command to add any external dependencies to your project. For example, for all Lambda functions in Go, you must include the [ github.com/aws/aws-lambda-go/lambda](https://github.com/aws/aws-lambda-go/tree/master/lambda) package, which implements the Lambda programming model for Go. Include this package with the following `go get` command:
```
go get github.com/aws/aws-lambda-go
```
Your function code should live in a Go file. In the following example, we name this file `main.go`. In this file, you implement your core function logic in a handler method, as well as a `main()` function that calls this handler.
## Example Go Lambda function code
The following example Go Lambda function code takes in information about an order, produces a text file receipt, and puts this file in an Amazon S3 bucket.
**Example `main.go` Lambda function**
```
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"os"
"strings"
"github.com/aws/aws-lambda-go/lambda"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
)
type Order struct {
OrderID string `json:"order_id"`
Amount float64 `json:"amount"`
Item string `json:"item"`
}
var (
s3Client *s3.Client
)
func init() {
// Initialize the S3 client outside of the handler, during the init phase
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
log.Fatalf("unable to load SDK config, %v", err)
}
s3Client = s3.NewFromConfig(cfg)
}
func uploadReceiptToS3(ctx context.Context, bucketName, key, receiptContent string) error {
_, err := s3Client.PutObject(ctx, &s3.PutObjectInput{
Bucket: &bucketName,
Key: &key,
Body: strings.NewReader(receiptContent),
})
if err != nil {
log.Printf("Failed to upload receipt to S3: %v", err)
return err
}
return nil
}
func handleRequest(ctx context.Context, event json.RawMessage) error {
// Parse the input event
var order Order
if err := json.Unmarshal(event, &order); err != nil {
log.Printf("Failed to unmarshal event: %v", err)
return err
}
// Access environment variables
bucketName := os.Getenv("RECEIPT_BUCKET")
if bucketName == "" {
log.Printf("RECEIPT_BUCKET environment variable is not set")
return fmt.Errorf("missing required environment variable RECEIPT_BUCKET")
}
// Create the receipt content and key destination
receiptContent := fmt.Sprintf("OrderID: %s\nAmount: $%.2f\nItem: %s",
order.OrderID, order.Amount, order.Item)
key := "receipts/" + order.OrderID + ".txt"
// Upload the receipt to S3 using the helper method
if err := uploadReceiptToS3(ctx, bucketName, key, receiptContent); err != nil {
return err
}
log.Printf("Successfully processed order %s and stored receipt in S3 bucket %s", order.OrderID, bucketName)
return nil
}
func main() {
lambda.Start(handleRequest)
}
```
This `main.go` file contains the following sections of code:
+ `package main`: In Go, the package containing your `func main()` function must always be named `main`.
+ `import` block: Use this block to include libraries that your Lambda function requires.
+ `type Order struct {}` block: Define the shape of the expected input event in this Go struct.
+ `var ()` block: Use this block to define any global variables that you'll use in your Lambda function.
+ `func init() {}`: Include any code you want Lambda to run during the during the [initialization phase](lambda-runtime-environment.md#runtimes-lifecycle-ib) in this `init()` method.
+ `func uploadReceiptToS3(...) {}`: This is a helper method that's referenced by the main `handleRequest` handler method.
+ `func handleRequest(ctx context.Context, event json.RawMessage) error {}`: This is the **main handler method**, which contains your main application logic.
+ `func main() {}`: This is a required entry point for your Lambda handler. The argument to the `lambda.Start()` method is your main handler method.
For this function to work properly, its [execution role](lambda-intro-execution-role.md) must allow the `s3:PutObject` action. Also, ensure that you define the `RECEIPT_BUCKET` environment variable. After a successful invocation, the Amazon S3 bucket should contain a receipt file.
## Handler naming conventions
For Lambda functions in Go, you can use any name for the handler. In this example, the handler method name is `handleRequest`. To reference the handler value in your code, you can use the `_HANDLER` environment variable.
For Go functions deployed using a [.zip deployment package](golang-package.md), the executable file that contains your function code must be named `bootstrap`. In addition, the `bootstrap` file must be at the root of the .zip file. For Go functions deployed using a [container image](go-image.md#go-image-provided), you can use any name for the executable file.
## Defining and accessing the input event object
JSON is the most common and standard input format for Lambda functions. In this example, the function expects an input similar to the following:
```
{
"order_id": "12345",
"amount": 199.99,
"item": "Wireless Headphones"
}
```
When working with Lambda functions in Go, you can define the shape of the expected input event as a Go struct. In this example, we define a struct to represent an `Order`:
```
type Order struct {
OrderID string `json:"order_id"`
Amount float64 `json:"amount"`
Item string `json:"item"`
}
```
This struct matches the expected input shape. After you define your struct, you can write a handler signature that takes in a generic JSON type compatible with the [encoding/json standard library](https://pkg.go.dev/encoding/json). You can then deserialize it into your struct using the [func Unmarshal](https://golang.org/pkg/encoding/json/#Unmarshal) function. This is illustrated in the first few lines of the handler:
```
func handleRequest(ctx context.Context, event json.RawMessage) error {
// Parse the input event
var order Order
if err := json.Unmarshal(event, &order); err != nil {
log.Printf("Failed to unmarshal event: %v", err)
return err
...
}
```
After this deserialization, you can access the fields of the `order` variable. For example, `order.OrderID` retrieves the value of `"order_id"` from the original input.
**Note**
The `encoding/json` package can access only exported fields. To be exported, field names in the event struct must be capitalized.
## Accessing and using the Lambda context object
The Lambda [context object](golang-context.md) contains information about the invocation, function, and execution environment. In this example, we declared this variable as `ctx` in the handler signature:
```
func handleRequest(ctx context.Context, event json.RawMessage) error {
...
}
```
The `ctx context.Context` input is an optional argument in your function handler. For more information about accepted handler signatures, see [Valid handler signatures for Go handlers](#golang-handler-signatures).
If you make calls to other services using the Amazon SDK, the context object is required in a few key areas. For example, to properly initialize your SDK clients, you can load the correct Amazon SDK configuration using the context object as follows:
```
// Load AWS SDK configuration using the default credential provider chain
cfg, err := config.LoadDefaultConfig(ctx)
```
SDK calls themselves may require the context object as an input. For example, the `s3Client.PutObject` call accepts the context object as its first argument:
```
// Upload the receipt to S3
_, err = s3Client.PutObject(ctx, &s3.PutObjectInput{
...
})
```
Outside of Amazon SDK requests, you can also use the context object for function monitoring. For more information about the context object, see [Using the Lambda context object to retrieve Go function information](golang-context.md).
## Valid handler signatures for Go handlers
You have several options when building a Lambda function handler in Go, but you must adhere to the following rules:
+ The handler must be a function.
+ The handler may take between 0 and 2 arguments. If there are two arguments, the first argument must implement `context.Context`.
+ The handler may return between 0 and 2 arguments. If there is a single return value, it must implement `error`. If there are two return values, the second value must implement `error`.
The following lists valid handler signatures. `TIn` and `TOut` represent types compatible with the *encoding/json* standard library. For more information, see [func Unmarshal](https://golang.org/pkg/encoding/json/#Unmarshal) to learn how these types are deserialized.
+
```
func ()
```
+
```
func () error
```
+
```
func () (TOut, error)
```
+
```
func (TIn) error
```
+
```
func (TIn) (TOut, error)
```
+
```
func (context.Context) error
```
+
```
func (context.Context) (TOut, error)
```
+
```
func (context.Context, TIn) error
```
+
```
func (context.Context, TIn) (TOut, error)
```
## Using the Amazon SDK for Go v2 in your handler
Often, you'll use Lambda functions to interact with or make updates to other Amazon resources. The simplest way to interface with these resources is to use the [Amazon SDK for Go v2](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2).
**Note**
The Amazon SDK for Go (v1) is in maintenance mode, and will reach end-of-support on July 31, 2025. We recommend that you use only the Amazon SDK for Go v2 going forward.
To add SDK dependencies to your function, use the `go get` command for the specific SDK clients that you need. In the example code earlier, we used the `config` library and the `s3` library. Add these dependencies by running the following commands in the directory that contains your `go.mod` and `main.go `files:
```
go get github.com/aws/aws-sdk-go-v2/config
go get github.com/aws/aws-sdk-go-v2/service/s3
```
Then, import the dependencies accordingly in your function's import block:
```
import (
...
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
)
```
When using the SDK in your handler, configure your clients with the right settings. The simplest way to do this is to use the [default credential provider chain](https://docs.amazonaws.cn/sdkref/latest/guide/standardized-credentials.html#credentialProviderChain). This example illustrates one way to load this configuration:
```
// Load AWS SDK configuration using the default credential provider chain
cfg, err := config.LoadDefaultConfig(ctx)
if err != nil {
log.Printf("Failed to load AWS SDK config: %v", err)
return err
}
```
After loading this configuration into the `cfg` variable, you can pass this variable into client instantiations. The example code instantiates an Amazon S3 client as follows:
```
// Create an S3 client
s3Client := s3.NewFromConfig(cfg)
```
In this example, we initialized our Amazon S3 client in the `init()` function to avoid having to initialize it every time we invoke our function. The problem is that in the `init()` function, Lambda doesn't have access to the context object. As a workaround, you can pass in a placeholder like `context.TODO()` during the initialization phase. Later, when you make a call using the client, pass in the full context object. This workaround is also described in [Using the context in Amazon SDK client initializations and calls](golang-context.md#golang-context-sdk).
After you configure and initialize your SDK client, you can then use it to interact with other Amazon services. The example code calls the Amazon S3 `PutObject` API as follows:
```
_, err = s3Client.PutObject(ctx, &s3.PutObjectInput{
Bucket: &bucketName,
Key: &key,
Body: strings.NewReader(receiptContent),
})
```
## Accessing environment variables
In your handler code, you can reference any [environment variables](configuration-envvars.md) by using the `os.Getenv()` method. In this example, we reference the defined `RECEIPT_BUCKET` environment variable using the following line of code:
```
// Access environment variables
bucketName := os.Getenv("RECEIPT_BUCKET")
if bucketName == "" {
log.Printf("RECEIPT_BUCKET environment variable is not set")
return fmt.Errorf("missing required environment variable RECEIPT_BUCKET")
}
```
## Using global state
To avoid creating new resources every time you invoke your function, you can declare and modify global variables outside of your Lambda function's handler code. You define these global variables in a `var` block or statement. In addition, your handler may declare an `init()` function that is executed during the [initialization phase](lambda-runtime-environment.md#runtimes-lifecycle-ib). The `init` method behaves the same in Amazon Lambda as it does in standard Go programs.
## Code best practices for Go Lambda functions
Adhere to the guidelines in the following list to use best coding practices when building your Lambda functions:
+ **Separate the Lambda handler from your core logic.** This allows you to make a more unit-testable function.
+ **Minimize the complexity of your dependencies.** Prefer simpler frameworks that load quickly on [execution environment](lambda-runtime-environment.md) startup.
+ **Minimize your deployment package size to its runtime necessities.** This will reduce the amount of time that it takes for your deployment package to be downloaded and unpacked ahead of invocation.
**Take advantage of execution environment reuse to improve the performance of your function.** Initialize SDK clients and database connections outside of the function handler, and cache static assets locally in the `/tmp` directory. Subsequent invocations processed by the same instance of your function can reuse these resources. This saves cost by reducing function run time.
To avoid potential data leaks across invocations, don’t use the execution environment to store user data, events, or other information with security implications. If your function relies on a mutable state that can’t be stored in memory within the handler, consider creating a separate function or separate versions of a function for each user.
**Use a keep-alive directive to maintain persistent connections.** Lambda purges idle connections over time. Attempting to reuse an idle connection when invoking a function will result in a connection error. To maintain your persistent connection, use the keep-alive directive associated with your runtime. For an example, see [Reusing Connections with Keep-Alive in Node.js](https://docs.amazonaws.cn/sdk-for-javascript/v3/developer-guide/node-reusing-connections.html).
**Use [environment variables](configuration-envvars.md) to pass operational parameters to your function.** For example, if you are writing to an Amazon S3 bucket, instead of hard-coding the bucket name you are writing to, configure the bucket name as an environment variable.
**Avoid using recursive invocations** in your Lambda function, where the function invokes itself or initiates a process that may invoke the function again. This could lead to unintended volume of function invocations and escalated costs. If you see an unintended volume of invocations, set the function reserved concurrency to `0` immediately to throttle all invocations to the function, while you update the code.
**Do not use non-documented, non-public APIs** in your Lambda function code. For Amazon Lambda managed runtimes, Lambda periodically applies security and functional updates to Lambda's internal APIs. These internal API updates may be backwards-incompatible, leading to unintended consequences such as invocation failures if your function has a dependency on these non-public APIs. See [the API reference](https://docs.amazonaws.cn/lambda/latest/api/welcome.html) for a list of publicly available APIs.
**Write idempotent code.** Writing idempotent code for your functions ensures that duplicate events are handled the same way. Your code should properly validate events and gracefully handle duplicate events. For more information, see [How do I make my Lambda function idempotent?](https://aws.amazon.com/premiumsupport/knowledge-center/lambda-function-idempotent/).
# Using the Lambda context object to retrieve Go function information
In Lambda, the context object provides methods and properties with information about the invocation, function, and execution environment. When Lambda runs your function, it passes a context object to the [handler](golang-handler.md). To use the context object in your handler, you can optionally declare it as an input parameter to your handler. The context object is necessary if you want to do the following in your handler:
+ You need access to any of the [global variables, methods, or properties](#golang-context-library) offered by the context object. These methods and properties are useful for tasks like determining the entity that invoked your function or measuring the invocation time of your function, as illustrated in [Accessing invoke context information](#golang-context-access).
+ You need to use the Amazon SDK for Go to make calls to other services. The context object is an important input parameter to most of these calls. For more information, see [Using the context in Amazon SDK client initializations and calls](#golang-context-sdk).
**Topics**
+ [Supported variables, methods, and properties in the context object](#golang-context-library)
+ [Accessing invoke context information](#golang-context-access)
+ [Using the context in Amazon SDK client initializations and calls](#golang-context-sdk)
## Supported variables, methods, and properties in the context object
The Lambda context library provides the following global variables, methods, and properties.
**Global variables**
+ `FunctionName` – The name of the Lambda function.
+ `FunctionVersion` – The [version](configuration-versions.md) of the function.
+ `MemoryLimitInMB` – The amount of memory that's allocated for the function.
+ `LogGroupName` – The log group for the function.
+ `LogStreamName` – The log stream for the function instance.
**Context methods**
+ `Deadline` – Returns the date that the execution times out, in Unix time milliseconds.
**Context properties**
+ `InvokedFunctionArn` – The Amazon Resource Name (ARN) that's used to invoke the function. Indicates if the invoker specified a version number or alias.
+ `AwsRequestID` – The identifier of the invocation request.
+ `Identity` – (mobile apps) Information about the Amazon Cognito identity that authorized the request.
+ `ClientContext` – (mobile apps) Client context that's provided to Lambda by the client application.
## Accessing invoke context information
Lambda functions have access to metadata about their environment and the invocation request. This can be accessed at [Package context](https://golang.org/pkg/context/). Should your handler include `context.Context` as a parameter, Lambda will insert information about your function into the context's `Value` property. Note that you need to import the `lambdacontext` library to access the contents of the `context.Context` object.
```
package main
import (
"context"
"log"
"github.com/aws/aws-lambda-go/lambda"
"github.com/aws/aws-lambda-go/lambdacontext"
)
func CognitoHandler(ctx context.Context) {
lc, _ := lambdacontext.FromContext(ctx)
log.Print(lc.Identity.CognitoIdentityPoolID)
}
func main() {
lambda.Start(CognitoHandler)
}
```
In the example above, `lc` is the variable used to consume the information that the context object captured and `log.Print(lc.Identity.CognitoIdentityPoolID)` prints that information, in this case, the CognitoIdentityPoolID.
The following example introduces how to use the context object to monitor how long your Lambda function takes to complete. This allows you to analyze performance expectations and adjust your function code accordingly, if needed.
```
package main
import (
"context"
"log"
"time"
"github.com/aws/aws-lambda-go/lambda"
)
func LongRunningHandler(ctx context.Context) (string, error) {
deadline, _ := ctx.Deadline()
deadline = deadline.Add(-100 * time.Millisecond)
timeoutChannel := time.After(time.Until(deadline))
for {
select {
case <- timeoutChannel:
return "Finished before timing out.", nil
default:
log.Print("hello!")
time.Sleep(50 * time.Millisecond)
}
}
}
func main() {
lambda.Start(LongRunningHandler)
}
```
## Using the context in Amazon SDK client initializations and calls
If your handler needs to use the Amazon SDK for Go to make calls to other services, include the context object as an input to your handler. In Amazon, it's a best practice to pass in the context object in most Amazon SDK calls. For example, the Amazon S3 `PutObject` call accepts the context object (`ctx`) as its first argument:
```
// Upload an object to S3
_, err = s3Client.PutObject(ctx, &s3.PutObjectInput{
...
})
```
To initialize your SDK clients properly, you can also use the context object to load the correct configuration before passing that configuration object to the client:
```
// Load AWS SDK configuration using the default credential provider chain
cfg, err := config.LoadDefaultConfig(ctx)
...
s3Client = s3.NewFromConfig(cfg)
```
If you want to initialize your SDK clients outside of your main handler (i.e. during the initialization phase), you can pass in a placeholder context object:
```
func init() {
// Initialize the S3 client outside of the handler, during the init phase
cfg, err := config.LoadDefaultConfig(context.TODO())
...
s3Client = s3.NewFromConfig(cfg)
}
```
If you initialize your clients this way, ensure that you pass in the correct context object in SDK calls from your main handler.
# Deploy Go Lambda functions with .zip file archives
Your Amazon Lambda function's code consists of scripts or compiled programs and their dependencies. You use a *deployment package* to deploy your function code to Lambda. Lambda supports two types of deployment packages: container images and .zip file archives.
This page describes how to create a .zip file as your deployment package for the Go runtime, and then use the .zip file to deploy your function code to Amazon Lambda using the Amazon Web Services Management Console, Amazon Command Line Interface (Amazon CLI), and Amazon Serverless Application Model (Amazon SAM).
Note that Lambda uses POSIX file permissions, so you may need to [ set permissions for the deployment package folder](http://www.amazonaws.cn/premiumsupport/knowledge-center/lambda-deployment-package-errors/) before you create the .zip file archive.
**Topics**
+ [Creating a .zip file on macOS and Linux](#golang-package-mac-linux)
+ [Creating a .zip file on Windows](#golang-package-windows)
+ [Creating and updating Go Lambda functions using .zip files](#golang-package-create-function)
## Creating a .zip file on macOS and Linux
The following steps show how to compile your executable using the `go build` command and create a .zip file deployment package for Lambda. Before compiling your code, make sure you have installed the [lambda](https://github.com/aws/aws-lambda-go/tree/master/lambda) package from GitHub. This module provides an implementation of the runtime interface, which manages the interaction between Lambda and your function code. To download this library, run the following command.
```
go get github.com/aws/aws-lambda-go/lambda
```
If your function uses the Amazon SDK for Go, download the standard set of SDK modules, along with any Amazon service API clients required by your application. To learn how to install the SDK for Go, see [Getting Started with the Amazon SDK for Go V2](https://github.com/aws/aws-sdk-go-v2?tab=readme-ov-file#getting-started).
### Using the provided runtime family
Go is implemented differently than other managed runtimes. Because Go compiles natively to an executable binary, it doesn't require a dedicated language runtime. Use an [OS-only runtime](runtimes-provided.md) (the `provided` runtime family) to deploy Go functions to Lambda.
**To create a .zip deployment package (macOS/Linux)**
1. In the project directory that contains your application's `main.go` file, compile your executable. Note the following:
+ The executable must be named `bootstrap`. For more information, see [Handler naming conventions](golang-handler.md#golang-handler-naming).
+ Set your target [instruction set architecture](foundation-arch.md). OS-only runtimes support both arm64 and x86\$164.
+ You can use the optional `lambda.norpc` tag to exclude the Remote Procedure Call (RPC) component of the [lambda](https://github.com/aws/aws-lambda-go/tree/master/lambda) library. The RPC component is only required if you are using the deprecated Go 1.x runtime. Excluding the RPC reduces the size of the deployment package.
For the arm64 architecture:
```
GOOS=linux GOARCH=arm64 go build -tags lambda.norpc -o bootstrap main.go
```
For the x86\$164 architecture:
```
GOOS=linux GOARCH=amd64 go build -tags lambda.norpc -o bootstrap main.go
```
1. (Optional) You may need to compile packages with `CGO_ENABLED=0` set on Linux:
```
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o bootstrap -tags lambda.norpc main.go
```
This command creates a stable binary package for standard C library (`libc`) versions, which may be different on Lambda and other devices.
1. Create a deployment package by packaging the executable in a .zip file.
```
zip myFunction.zip bootstrap
```
**Note**
The `bootstrap` file must be at the root of the .zip file.
1. Create the function. Note the following:
+ The binary must be named `bootstrap`, but the handler name can be anything. For more information, see [Handler naming conventions](golang-handler.md#golang-handler-naming).
+ The `--architectures` option is only required if you're using arm64. The default value is x86\$164.
+ For `--role`, specify the Amazon Resource Name (ARN) of the [execution role](lambda-intro-execution-role.md).
```
aws lambda create-function --function-name myFunction \
--runtime provided.al2023 --handler bootstrap \
--architectures arm64 \
--role arn:aws-cn:iam::111122223333:role/lambda-ex \
--zip-file fileb://myFunction.zip
```
## Creating a .zip file on Windows
The following steps show how to download the [build-lambda-zip](https://github.com/aws/aws-lambda-go/tree/main/cmd/build-lambda-zip) tool for Windows from GitHub, compile your executable, and create a .zip deployment package.
**Note**
If you have not already done so, you must install [git](https://git-scm.com/) and then add the `git` executable to your Windows `%PATH%` environment variable.
Before compiling your code, make sure you have installed the [lambda](https://github.com/aws/aws-lambda-go/tree/master/lambda) library from GitHub. To download this library, run the following command.
```
go get github.com/aws/aws-lambda-go/lambda
```
If your function uses the Amazon SDK for Go, download the standard set of SDK modules, along with any Amazon service API clients required by your application. To learn how to install the SDK for Go, see [Getting Started with the Amazon SDK for Go V2](https://aws.github.io/aws-sdk-go-v2/docs/getting-started/).
### Using the provided runtime family
Go is implemented differently than other managed runtimes. Because Go compiles natively to an executable binary, it doesn't require a dedicated language runtime. Use an [OS-only runtime](runtimes-provided.md) (the `provided` runtime family) to deploy Go functions to Lambda.
**To create a .zip deployment package (Windows)**
1. Download the **build-lambda-zip** tool from GitHub.
```
go install github.com/aws/aws-lambda-go/cmd/build-lambda-zip@latest
```
1. Use the tool from your `GOPATH` to create a .zip file. If you have a default installation of Go, the tool is typically in `%USERPROFILE%\Go\bin`. Otherwise, navigate to where you installed the Go runtime and do one of the following:
------
#### [ cmd.exe ]
In cmd.exe, run one of the following, depending on your target [instruction set architecture](foundation-arch.md). OS-only runtimes support both arm64 and x86\$164.
You can use the optional `lambda.norpc` tag to exclude the Remote Procedure Call (RPC) component of the [lambda](https://github.com/aws/aws-lambda-go/tree/master/lambda) library. The RPC component is only required if you are using the deprecated Go 1.x runtime. Excluding the RPC reduces the size of the deployment package.
**Example — For the x86\$164 architecture**
```
set GOOS=linux
set GOARCH=amd64
set CGO_ENABLED=0
go build -tags lambda.norpc -o bootstrap main.go
%USERPROFILE%\Go\bin\build-lambda-zip.exe -o myFunction.zip bootstrap
```
**Example — For the arm64 architecture**
```
set GOOS=linux
set GOARCH=arm64
set CGO_ENABLED=0
go build -tags lambda.norpc -o bootstrap main.go
%USERPROFILE%\Go\bin\build-lambda-zip.exe -o myFunction.zip bootstrap
```
------
#### [ PowerShell ]
In PowerShell, run one of the following, depending on your target [instruction set architecture](foundation-arch.md). OS-only runtimes support both arm64 and x86\$164.
You can use the optional `lambda.norpc` tag to exclude the Remote Procedure Call (RPC) component of the [lambda](https://github.com/aws/aws-lambda-go/tree/master/lambda) library. The RPC component is only required if you are using the deprecated Go 1.x runtime. Excluding the RPC reduces the size of the deployment package.
For the x86\$164 architecture:
```
$env:GOOS = "linux"
$env:GOARCH = "amd64"
$env:CGO_ENABLED = "0"
go build -tags lambda.norpc -o bootstrap main.go
~\Go\Bin\build-lambda-zip.exe -o myFunction.zip bootstrap
```
For the arm64 architecture:
```
$env:GOOS = "linux"
$env:GOARCH = "arm64"
$env:CGO_ENABLED = "0"
go build -tags lambda.norpc -o bootstrap main.go
~\Go\Bin\build-lambda-zip.exe -o myFunction.zip bootstrap
```
------
1. Create the function. Note the following:
+ The binary must be named `bootstrap`, but the handler name can be anything. For more information, see [Handler naming conventions](golang-handler.md#golang-handler-naming).
+ The `--architectures` option is only required if you're using arm64. The default value is x86\$164.
+ For `--role`, specify the Amazon Resource Name (ARN) of the [execution role](lambda-intro-execution-role.md).
```
aws lambda create-function --function-name myFunction \
--runtime provided.al2023 --handler bootstrap \
--architectures arm64 \
--role arn:aws-cn:iam::111122223333:role/lambda-ex \
--zip-file fileb://myFunction.zip
```
## Creating and updating Go Lambda functions using .zip files
After you have created your .zip deployment package, you can use it to create a new Lambda function or update an existing one. You can deploy your .zip package using the Lambda console, the Amazon Command Line Interface, and the Lambda API. You can also create and update Lambda functions using Amazon Serverless Application Model (Amazon SAM) and Amazon CloudFormation.
The maximum size for a .zip deployment package for Lambda is 250 MB (unzipped). Note that this limit applies to the combined size of all the files you upload, including any Lambda layers.
The Lambda runtime needs permission to read the files in your deployment package. In Linux permissions octal notation, Lambda needs 644 permissions for non-executable files (rw-r--r--) and 755 permissions (rwxr-xr-x) for directories and executable files.
In Linux and MacOS, use the `chmod` command to change file permissions on files and directories in your deployment package. For example, to give a non-executable file the correct permissions, run the following command.
```
chmod 644
```
To change file permissions in Windows, see [Set, View, Change, or Remove Permissions on an Object](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc731667(v=ws.10)) in the Microsoft Windows documentation.
**Note**
If you don't grant Lambda the permissions it needs to access directories in your deployment package, Lambda sets the permissions for those directories to 755 (rwxr-xr-x).
### Creating and updating functions with .zip files using the console
To create a new function, you must first create the function in the console, then upload your .zip archive. To update an existing function, open the page for your function, then follow the same procedure to add your updated .zip file.
If your .zip file is less than 50MB, you can create or update a function by uploading the file directly from your local machine. For .zip files greater than 50MB, you must upload your package to an Amazon S3 bucket first. For instructions on how to upload a file to an Amazon S3 bucket using the Amazon Web Services Management Console, see [Getting started with Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html). To upload files using the Amazon CLI, see [Move objects](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-managing-objects-move) in the *Amazon CLI User Guide*.
**Note**
You cannot convert an existing container image function to use a .zip archive. You must create a new function.
**To create a new function (console)**
1. Open the [Functions page](https://console.amazonaws.cn/lambda/home#/functions) of the Lambda console and choose **Create Function**.
1. Choose **Author from scratch**.
1. Under **Basic information**, do the following:
1. For **Function name**, enter the name for your function.
1. For **Runtime**, choose `provided.al2023`.
1. (Optional) Under **Permissions**, expand **Change default execution role**. You can create a new **Execution role** or use an existing one.
1. Choose **Create function**. Lambda creates a basic 'Hello world' function using your chosen runtime.
**To upload a .zip archive from your local machine (console)**
1. In the [Functions page](https://console.amazonaws.cn/lambda/home#/functions) of the Lambda console, choose the function you want to upload the .zip file for.
1. Select the **Code** tab.
1. In the **Code source** pane, choose **Upload from**.
1. Choose **.zip file**.
1. To upload the .zip file, do the following:
1. Select **Upload**, then select your .zip file in the file chooser.
1. Choose **Open**.
1. Choose **Save**.
**To upload a .zip archive from an Amazon S3 bucket (console)**
1. In the [Functions page](https://console.amazonaws.cn/lambda/home#/functions) of the Lambda console, choose the function you want to upload a new .zip file for.
1. Select the **Code** tab.
1. In the **Code source** pane, choose **Upload from**.
1. Choose **Amazon S3 location**.
1. Paste the Amazon S3 link URL of your .zip file and choose **Save**.
### Creating and updating functions with .zip files using the Amazon CLI
You can can use the [Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/getting-started-install.html) to create a new function or to update an existing one using a .zip file. Use the [create-function](https://docs.amazonaws.cn/cli/latest/reference/lambda/create-function.html) and [update-function-code](https://docs.amazonaws.cn/cli/latest/reference/lambda/create-function.html) commands to deploy your .zip package. If your .zip file is smaller than 50MB, you can upload the .zip package from a file location on your local build machine. For larger files, you must upload your .zip package from an Amazon S3 bucket. For instructions on how to upload a file to an Amazon S3 bucket using the Amazon CLI, see [Move objects](https://docs.amazonaws.cn/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-managing-objects-move) in the *Amazon CLI User Guide*.
**Note**
If you upload your .zip file from an Amazon S3 bucket using the Amazon CLI, the bucket must be located in the same Amazon Web Services Region as your function.
To create a new function using a .zip file with the Amazon CLI, you must specify the following:
+ The name of your function (`--function-name`)
+ Your function’s runtime (`--runtime`)
+ The Amazon Resource Name (ARN) of your function’s [execution role](https://docs.amazonaws.cn/lambda/latest/dg/lambda-intro-execution-role.html) (`--role`)
+ The name of the handler method in your function code (`--handler`)
You must also specify the location of your .zip file. If your .zip file is located in a folder on your local build machine, use the `--zip-file` option to specify the file path, as shown in the following example command.
```
aws lambda create-function --function-name myFunction \
--runtime provided.al2023 --handler bootstrap \
--role arn:aws-cn:iam::111122223333:role/service-role/my-lambda-role \
--zip-file fileb://myFunction.zip
```
To specify the location of .zip file in an Amazon S3 bucket, use the `--code` option as shown in the following example command. You only need to use the `S3ObjectVersion` parameter for versioned objects.
```
aws lambda create-function --function-name myFunction \
--runtime provided.al2023 --handler bootstrap \
--role arn:aws-cn:iam::111122223333:role/service-role/my-lambda-role \
--code S3Bucket=amzn-s3-demo-bucket,S3Key=myFileName.zip,S3ObjectVersion=myObjectVersion
```
To update an existing function using the CLI, you specify the the name of your function using the `--function-name` parameter. You must also specify the location of the .zip file you want to use to update your function code. If your .zip file is located in a folder on your local build machine, use the `--zip-file` option to specify the file path, as shown in the following example command.
```
aws lambda update-function-code --function-name myFunction \
--zip-file fileb://myFunction.zip
```
To specify the location of .zip file in an Amazon S3 bucket, use the `--s3-bucket` and `--s3-key` options as shown in the following example command. You only need to use the `--s3-object-version` parameter for versioned objects.
```
aws lambda update-function-code --function-name myFunction \
--s3-bucket amzn-s3-demo-bucket --s3-key myFileName.zip --s3-object-version myObject Version
```
### Creating and updating functions with .zip files using the Lambda API
To create and update functions using a .zip file archive, use the following API operations:
+ [CreateFunction](https://docs.amazonaws.cn/lambda/latest/api/API_CreateFunction.html)
+ [UpdateFunctionCode](https://docs.amazonaws.cn/lambda/latest/api/API_UpdateFunctionCode.html)
### Creating and updating functions with .zip files using Amazon SAM
The Amazon Serverless Application Model (Amazon SAM) is a toolkit that helps streamline the process of building and running serverless applications on Amazon. You define the resources for your application in a YAML or JSON template and use the Amazon SAM command line interface (Amazon SAM CLI) to build, package, and deploy your applications. When you build a Lambda function from an Amazon SAM template, Amazon SAM automatically creates a .zip deployment package or container image with your function code and any dependencies you specify. To learn more about using Amazon SAM to build and deploy Lambda functions, see [Getting started with Amazon SAM](https://docs.amazonaws.cn/serverless-application-model/latest/developerguide/serverless-getting-started.html) in the *Amazon Serverless Application Model Developer Guide*.
You can also use Amazon SAM to create a Lambda function using an existing .zip file archive. To create a Lambda function using Amazon SAM, you can save your .zip file in an Amazon S3 bucket or in a local folder on your build machine. For instructions on how to upload a file to an Amazon S3 bucket using the Amazon CLI, see [Move objects](https://docs.amazonaws.cn/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-managing-objects-move) in the *Amazon CLI User Guide*.
In your Amazon SAM template, the `AWS::Serverless::Function` resource specifies your Lambda function. In this resource, set the following properties to create a function using a .zip file archive:
+ `PackageType` - set to `Zip`
+ `CodeUri` - set to the function code's Amazon S3 URI, path to local folder, or [FunctionCode](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-property-function-functioncode.html) object
+ `Runtime` - Set to your chosen runtime
With Amazon SAM, if your .zip file is larger than 50MB, you don’t need to upload it to an Amazon S3 bucket first. Amazon SAM can upload .zip packages up to the maximum allowed size of 250MB (unzipped) from a location on your local build machine.
To learn more about deploying functions using .zip file in Amazon SAM, see [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html) in the *Amazon SAM Developer Guide*.
**Example: Using Amazon SAM to build a Go function with provided.al2023**
1. Create an Amazon SAM template with the following properties:
+ **BuildMethod**: Specifies the compiler for your application. Use `go1.x`.
+ **Runtime**: Use `provided.al2023`.
+ **CodeUri**: Enter the path to your code.
+ **Architectures**: Use `[arm64]` for the arm64 architecture. For the x86\$164 instruction set architecture, use `[amd64]` or remove the `Architectures` property.
**Example template.yaml**
```
AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Resources:
HelloWorldFunction:
Type: AWS::Serverless::Function
Metadata:
BuildMethod: go1.x
Properties:
CodeUri: hello-world/ # folder where your main program resides
Handler: bootstrap
Runtime: provided.al2023
Architectures: [arm64]
```
1. Use the [sam build](https://docs.amazonaws.cn/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-build.html) command to compile the executable.
```
sam build
```
1. Use the [sam deploy](https://docs.amazonaws.cn/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-deploy.html) command to deploy the function to Lambda.
```
sam deploy --guided
```
### Creating and updating functions with .zip files using Amazon CloudFormation
You can use Amazon CloudFormation to create a Lambda function using a .zip file archive. To create a Lambda function from a .zip file, you must first upload your file to an Amazon S3 bucket. For instructions on how to upload a file to an Amazon S3 bucket using the Amazon CLI, see [Move objects](https://docs.amazonaws.cn/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-managing-objects-move) in the *Amazon CLI User Guide. *
In your Amazon CloudFormation template, the `AWS::Lambda::Function` resource specifies your Lambda function. In this resource, set the following properties to create a function using a .zip file archive:
+ `PackageType` - Set to `Zip`
+ `Code` - Enter the Amazon S3 bucket name and the .zip file name in the `S3Bucket` and `S3Key` fields
+ `Runtime` - Set to your chosen runtime
The .zip file that Amazon CloudFormation generates cannot exceed 4MB. To learn more about deploying functions using .zip file in Amazon CloudFormation, see [AWS::Lambda::Function](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html) in the *Amazon CloudFormation User Guide*.
# Deploy Go Lambda functions with container images
There are two ways to build a container image for a Go Lambda function:
+ [Using an Amazon OS-only base image](#go-image-provided)
Go is implemented differently than other managed runtimes. Because Go compiles natively to an executable binary, it doesn't require a dedicated language runtime. Use an [OS-only base image](images-create.md#runtimes-images-provided) to build Go images for Lambda. To make the image compatible with Lambda, you must include the `aws-lambda-go/lambda` package in the image.
+ [Using a non-Amazon base image](#go-image-other)
You can use an alternative base image from another container registry, such as Alpine Linux or Debian. You can also use a custom image created by your organization. To make the image compatible with Lambda, you must include the `aws-lambda-go/lambda` package in the image.
**Tip**
To reduce the time it takes for Lambda container functions to become active, see [Use multi-stage builds](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#use-multi-stage-builds) in the Docker documentation. To build efficient container images, follow the [Best practices for writing Dockerfiles](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/).
This page explains how to build, test, and deploy container images for Lambda.
## Amazon base images for deploying Go functions
Go is implemented differently than other managed runtimes. Because Go compiles natively to an executable binary, it doesn't require a dedicated language runtime. Use an [OS-only base image](images-create.md#runtimes-images-provided) to deploy Go functions to Lambda.
| Name | Identifier | Operating system | Deprecation date | Block function create | Block function update |
| --- | --- | --- | --- | --- | --- |
| OS-only Runtime | `provided.al2023` | Amazon Linux 2023 | Jun 30, 2029 | Jul 31, 2029 | Aug 31, 2029 |
| OS-only Runtime | `provided.al2` | Amazon Linux 2 | Jul 31, 2026 | Aug 31, 2026 | Sep 30, 2026 |
Amazon Elastic Container Registry Public Gallery: [gallery.ecr.aws/lambda/provided](https://gallery.ecr.aws/lambda/provided)
## Go runtime interface client
The `aws-lambda-go/lambda` package includes an implementation of the runtime interface. For examples of how to use `aws-lambda-go/lambda` in your image, see [Using an Amazon OS-only base image](#go-image-provided) or [Using a non-Amazon base image](#go-image-other).
## Using an Amazon OS-only base image
Go is implemented differently than other managed runtimes. Because Go compiles natively to an executable binary, it doesn't require a dedicated language runtime. Use an [OS-only base image](images-create.md#runtimes-images-provided) to build container images for Go functions.
| Tags | Runtime | Operating system | Dockerfile | Deprecation |
| --- | --- | --- | --- | --- |
| al2023 | OS-only Runtime | Amazon Linux 2023 | [Dockerfile for OS-only Runtime on GitHub](https://github.com/aws/aws-lambda-base-images/blob/provided.al2023/Dockerfile.provided.al2023) | Jun 30, 2029 |
| al2 | OS-only Runtime | Amazon Linux 2 | [Dockerfile for OS-only Runtime on GitHub](https://github.com/aws/aws-lambda-base-images/blob/provided.al2/Dockerfile.provided.al2) | Jul 31, 2026 |
For more information about these base images, see [provided](https://gallery.ecr.aws/lambda/provided) in the Amazon ECR public gallery.
You must include the [aws-lambda-go/lambda](https://github.com/aws/aws-lambda-go) package with your Go handler. This package implements the programming model for Go, including the runtime interface.
### Prerequisites
To complete the steps in this section, you must have the following:
+ [Amazon CLI version 2](https://docs.amazonaws.cn/cli/latest/userguide/getting-started-install.html)
+ [Docker](https://docs.docker.com/get-docker) (minimum version 25.0.0)
+ The Docker [buildx plugin](https://github.com/docker/buildx/blob/master/README.md).
+ Go
### Creating an image from the provided.al2023 base image
**To build and deploy a Go function with the `provided.al2023` base image**
1. Create a directory for the project, and then switch to that directory.
```
mkdir hello
cd hello
```
1. Initialize a new Go module.
```
go mod init example.com/hello-world
```
1. Add the **lambda** library as a dependency of your new module.
```
go get github.com/aws/aws-lambda-go/lambda
```
1. Create a file named `main.go` and then open it in a text editor. This is the code for the Lambda function. You can use the following sample code for testing, or replace it with your own.
```
package main
import (
"context"
"github.com/aws/aws-lambda-go/events"
"github.com/aws/aws-lambda-go/lambda"
)
func handler(ctx context.Context, event events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
response := events.APIGatewayProxyResponse{
StatusCode: 200,
Body: "\"Hello from Lambda!\"",
}
return response, nil
}
func main() {
lambda.Start(handler)
}
```
1. Use a text editor to create a Dockerfile in your project directory.
+ The following example Dockerfile uses a [multi-stage build](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#use-multi-stage-builds). This allows you to use a different base image in each step. You can use one image, such as a [Go base image](https://hub.docker.com/_/golang), to compile your code and build the executable binary. You can then use a different image, such as `provided.al2023`, in the final `FROM` statement to define the image that you deploy to Lambda. The build process is separated from the final deployment image, so the final image only contains the files needed to run the application.
+ You can use the optional `lambda.norpc` tag to exclude the Remote Procedure Call (RPC) component of the [lambda](https://github.com/aws/aws-lambda-go/tree/master/lambda) library. The RPC component is only required if you are using the deprecated Go 1.x runtime. Excluding the RPC reduces the size of the deployment package.
+ Note that the example Dockerfile does not include a [USER instruction](https://docs.docker.com/reference/dockerfile/#user). When you deploy a container image to Lambda, Lambda automatically defines a default Linux user with least-privileged permissions. This is different from standard Docker behavior which defaults to the `root` user when no `USER` instruction is provided.
**Example — Multi-stage build Dockerfile**
**Note**
Make sure that the version of Go that you specify in your Dockerfile (for example, `golang:1.20`) is the same version of Go that you used to create your application.
```
FROM golang:1.20 as build
WORKDIR /helloworld
# Copy dependencies list
COPY go.mod go.sum ./
# Build with optional lambda.norpc tag
COPY main.go .
RUN go build -tags lambda.norpc -o main main.go
# Copy artifacts to a clean image
FROM public.ecr.aws/lambda/provided:al2023
COPY --from=build /helloworld/main ./main
ENTRYPOINT [ "./main" ]
```
1. Build the Docker image with the [docker build](https://docs.docker.com/engine/reference/commandline/build/) command. The following example names the image `docker-image` and gives it the `test` [tag](https://docs.docker.com/engine/reference/commandline/build/#tag). To make your image compatible with Lambda, you must use the `--provenance=false` option.
```
docker buildx build --platform linux/amd64 --provenance=false -t docker-image:test .
```
**Note**
The command specifies the `--platform linux/amd64` option to ensure that your container is compatible with the Lambda execution environment regardless of the architecture of your build machine. If you intend to create a Lambda function using the ARM64 instruction set architecture, be sure to change the command to use the `--platform linux/arm64` option instead.
### (Optional) Test the image locally
Use the [runtime interface emulator](https://github.com/aws/aws-lambda-runtime-interface-emulator/) to locally test your image. The runtime interface emulator is included in the `provided.al2023` base image.
**To run the runtime interface emulator on your local machine**
1. Start the Docker image with the **docker run** command. Note the following:
+ `docker-image` is the image name and `test` is the tag.
+ `./main` is the `ENTRYPOINT` from your Dockerfile.
```
docker run -d -p 9000:8080 \
--entrypoint /usr/local/bin/aws-lambda-rie \
docker-image:test ./main
```
This command runs the image as a container and creates a local endpoint at `localhost:9000/2015-03-31/functions/function/invocations`.
1. From a new terminal window, post an event to the following endpoint using a **curl** command:
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
```
This command invokes the function with an empty event and returns a response. Some functions might require a JSON payload. Example:
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"payload":"hello world!"}'
```
1. Get the container ID.
```
docker ps
```
1. Use the [docker kill](https://docs.docker.com/engine/reference/commandline/kill/) command to stop the container. In this command, replace `3766c4ab331c` with the container ID from the previous step.
```
docker kill 3766c4ab331c
```
### Deploying the image
**To upload the image to Amazon ECR and create the Lambda function**
1. Run the [get-login-password](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/get-login-password.html) command to authenticate the Docker CLI to your Amazon ECR registry.
+ Set the `--region` value to the Amazon Web Services Region where you want to create the Amazon ECR repository.
+ Replace `111122223333` with your Amazon Web Services account ID.
```
aws ecr get-login-password --region cn-north-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn
```
1. Create a repository in Amazon ECR using the [create-repository](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/create-repository.html) command.
```
aws ecr create-repository --repository-name hello-world --region cn-north-1 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE
```
**Note**
The Amazon ECR repository must be in the same Amazon Web Services Region as the Lambda function.
If successful, you see a response like this:
```
{
"repository": {
"repositoryArn": "arn:aws-cn:ecr:cn-north-1:111122223333:repository/hello-world",
"registryId": "111122223333",
"repositoryName": "hello-world",
"repositoryUri": "111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world",
"createdAt": "2023-03-09T10:39:01+00:00",
"imageTagMutability": "MUTABLE",
"imageScanningConfiguration": {
"scanOnPush": true
},
"encryptionConfiguration": {
"encryptionType": "AES256"
}
}
}
```
1. Copy the `repositoryUri` from the output in the previous step.
1. Run the [docker tag](https://docs.docker.com/engine/reference/commandline/tag/) command to tag your local image into your Amazon ECR repository as the latest version. In this command:
+ `docker-image:test` is the name and [tag](https://docs.docker.com/engine/reference/commandline/build/#tag) of your Docker image. This is the image name and tag that you specified in the `docker build` command.
+ Replace `` with the `repositoryUri` that you copied. Make sure to include `:latest` at the end of the URI.
```
docker tag docker-image:test :latest
```
Example:
```
docker tag docker-image:test 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world:latest
```
1. Run the [docker push](https://docs.docker.com/engine/reference/commandline/push/) command to deploy your local image to the Amazon ECR repository. Make sure to include `:latest` at the end of the repository URI.
```
docker push 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world:latest
```
1. [Create an execution role](lambda-intro-execution-role.md#permissions-executionrole-api) for the function, if you don't already have one. You need the Amazon Resource Name (ARN) of the role in the next step.
1. Create the Lambda function. For `ImageUri`, specify the repository URI from earlier. Make sure to include `:latest` at the end of the URI.
```
aws lambda create-function \
--function-name hello-world \
--package-type Image \
--code ImageUri=111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world:latest \
--role arn:aws-cn:iam::111122223333:role/lambda-ex
```
**Note**
You can create a function using an image in a different Amazon account, as long as the image is in the same Region as the Lambda function. For more information, see [Amazon ECR cross-account permissions](images-create.md#configuration-images-xaccount-permissions).
1. Invoke the function.
```
aws lambda invoke --function-name hello-world response.json
```
You should see a response like this:
```
{
"ExecutedVersion": "$LATEST",
"StatusCode": 200
}
```
1. To see the output of the function, check the `response.json` file.
To update the function code, you must build the image again, upload the new image to the Amazon ECR repository, and then use the [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html) command to deploy the image to the Lambda function.
Lambda resolves the image tag to a specific image digest. This means that if you point the image tag that was used to deploy the function to a new image in Amazon ECR, Lambda doesn't automatically update the function to use the new image.
To deploy the new image to the same Lambda function, you must use the [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html) command, even if the image tag in Amazon ECR remains the same. In the following example, the `--publish` option creates a new version of the function using the updated container image.
```
aws lambda update-function-code \
--function-name hello-world \
--image-uri 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world:latest \
--publish
```
## Using a non-Amazon base image
You can build a container image for Go from a non-Amazon base image. The example Dockerfile in the following steps uses an [Alpine base image](https://hub.docker.com/_/golang/).
You must include the [aws-lambda-go/lambda](https://github.com/aws/aws-lambda-go) package with your Go handler. This package implements the programming model for Go, including the runtime interface.
### Prerequisites
To complete the steps in this section, you must have the following:
+ [Amazon CLI version 2](https://docs.amazonaws.cn/cli/latest/userguide/getting-started-install.html)
+ [Docker](https://docs.docker.com/get-docker) (minimum version 25.0.0)
+ The Docker [buildx plugin](https://github.com/docker/buildx/blob/master/README.md).
+ Go
### Creating an image from an alternative base image
**To build and deploy a Go function with an Alpine base image**
1. Create a directory for the project, and then switch to that directory.
```
mkdir hello
cd hello
```
1. Initialize a new Go module.
```
go mod init example.com/hello-world
```
1. Add the **lambda** library as a dependency of your new module.
```
go get github.com/aws/aws-lambda-go/lambda
```
1. Create a file named `main.go` and then open it in a text editor. This is the code for the Lambda function. You can use the following sample code for testing, or replace it with your own.
```
package main
import (
"context"
"github.com/aws/aws-lambda-go/events"
"github.com/aws/aws-lambda-go/lambda"
)
func handler(ctx context.Context, event events.APIGatewayProxyRequest) (events.APIGatewayProxyResponse, error) {
response := events.APIGatewayProxyResponse{
StatusCode: 200,
Body: "\"Hello from Lambda!\"",
}
return response, nil
}
func main() {
lambda.Start(handler)
}
```
1. Use a text editor to create a Dockerfile in your project directory. The following example Dockerfile uses an [Alpine base image](https://hub.docker.com/_/golang/). Note that the example Dockerfile does not include a [USER instruction](https://docs.docker.com/reference/dockerfile/#user). When you deploy a container image to Lambda, Lambda automatically defines a default Linux user with least-privileged permissions. This is different from standard Docker behavior which defaults to the `root` user when no `USER` instruction is provided.
**Example Dockerfile**
**Note**
Make sure that the version of Go that you specify in your Dockerfile (for example, `golang:1.20`) is the same version of Go that you used to create your application.
```
FROM golang:1.20.2-alpine3.16 as build
WORKDIR /helloworld
# Copy dependencies list
COPY go.mod go.sum ./
# Build
COPY main.go .
RUN go build -o main main.go
# Copy artifacts to a clean image
FROM alpine:3.16
COPY --from=build /helloworld/main /main
ENTRYPOINT [ "/main" ]
```
1. Build the Docker image with the [docker build](https://docs.docker.com/engine/reference/commandline/build/) command. The following example names the image `docker-image` and gives it the `test` [tag](https://docs.docker.com/engine/reference/commandline/build/#tag). To make your image compatible with Lambda, you must use the `--provenance=false` option.
```
docker buildx build --platform linux/amd64 --provenance=false -t docker-image:test .
```
**Note**
The command specifies the `--platform linux/amd64` option to ensure that your container is compatible with the Lambda execution environment regardless of the architecture of your build machine. If you intend to create a Lambda function using the ARM64 instruction set architecture, be sure to change the command to use the `--platform linux/arm64` option instead.
### (Optional) Test the image locally
Use the [runtime interface emulator](https://github.com/aws/aws-lambda-runtime-interface-emulator/) to locally test the image. You can [build the emulator into your image](https://github.com/aws/aws-lambda-runtime-interface-emulator/?tab=readme-ov-file#build-rie-into-your-base-image) or use the following procedure to install it on your local machine.
**To install and run the runtime interface emulator on your local machine**
1. From your project directory, run the following command to download the runtime interface emulator (x86-64 architecture) from GitHub and install it on your local machine.
------
#### [ Linux/macOS ]
```
mkdir -p ~/.aws-lambda-rie && \
curl -Lo ~/.aws-lambda-rie/aws-lambda-rie https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie && \
chmod +x ~/.aws-lambda-rie/aws-lambda-rie
```
To install the arm64 emulator, replace the GitHub repository URL in the previous command with the following:
```
https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie-arm64
```
------
#### [ PowerShell ]
```
$dirPath = "$HOME\.aws-lambda-rie"
if (-not (Test-Path $dirPath)) {
New-Item -Path $dirPath -ItemType Directory
}
$downloadLink = "https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie"
$destinationPath = "$HOME\.aws-lambda-rie\aws-lambda-rie"
Invoke-WebRequest -Uri $downloadLink -OutFile $destinationPath
```
To install the arm64 emulator, replace the `$downloadLink` with the following:
```
https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie-arm64
```
------
1. Start the Docker image with the **docker run** command. Note the following:
+ `docker-image` is the image name and `test` is the tag.
+ `/main` is the `ENTRYPOINT` from your Dockerfile.
------
#### [ Linux/macOS ]
```
docker run --platform linux/amd64 -d -v ~/.aws-lambda-rie:/aws-lambda -p 9000:8080 \
--entrypoint /aws-lambda/aws-lambda-rie \
docker-image:test \
/main
```
------
#### [ PowerShell ]
```
docker run --platform linux/amd64 -d -v "$HOME\.aws-lambda-rie:/aws-lambda" -p 9000:8080 `
--entrypoint /aws-lambda/aws-lambda-rie `
docker-image:test `
/main
```
------
This command runs the image as a container and creates a local endpoint at `localhost:9000/2015-03-31/functions/function/invocations`.
**Note**
If you built the Docker image for the ARM64 instruction set architecture, be sure to use the `--platform linux/arm64` option instead of `--platform linux/amd64`.
1. Post an event to the local endpoint.
------
#### [ Linux/macOS ]
In Linux and macOS, run the following `curl` command:
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
```
This command invokes the function with an empty event and returns a response. If you're using your own function code rather than the sample function code, you might want to invoke the function with a JSON payload. Example:
```
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"payload":"hello world!"}'
```
------
#### [ PowerShell ]
In PowerShell, run the following `Invoke-WebRequest` command:
```
Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{}' -ContentType "application/json"
```
This command invokes the function with an empty event and returns a response. If you're using your own function code rather than the sample function code, you might want to invoke the function with a JSON payload. Example:
```
Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{"payload":"hello world!"}' -ContentType "application/json"
```
------
1. Get the container ID.
```
docker ps
```
1. Use the [docker kill](https://docs.docker.com/engine/reference/commandline/kill/) command to stop the container. In this command, replace `3766c4ab331c` with the container ID from the previous step.
```
docker kill 3766c4ab331c
```
### Deploying the image
**To upload the image to Amazon ECR and create the Lambda function**
1. Run the [get-login-password](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/get-login-password.html) command to authenticate the Docker CLI to your Amazon ECR registry.
+ Set the `--region` value to the Amazon Web Services Region where you want to create the Amazon ECR repository.
+ Replace `111122223333` with your Amazon Web Services account ID.
```
aws ecr get-login-password --region cn-north-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn
```
1. Create a repository in Amazon ECR using the [create-repository](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/create-repository.html) command.
```
aws ecr create-repository --repository-name hello-world --region cn-north-1 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE
```
**Note**
The Amazon ECR repository must be in the same Amazon Web Services Region as the Lambda function.
If successful, you see a response like this:
```
{
"repository": {
"repositoryArn": "arn:aws-cn:ecr:cn-north-1:111122223333:repository/hello-world",
"registryId": "111122223333",
"repositoryName": "hello-world",
"repositoryUri": "111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world",
"createdAt": "2023-03-09T10:39:01+00:00",
"imageTagMutability": "MUTABLE",
"imageScanningConfiguration": {
"scanOnPush": true
},
"encryptionConfiguration": {
"encryptionType": "AES256"
}
}
}
```
1. Copy the `repositoryUri` from the output in the previous step.
1. Run the [docker tag](https://docs.docker.com/engine/reference/commandline/tag/) command to tag your local image into your Amazon ECR repository as the latest version. In this command:
+ `docker-image:test` is the name and [tag](https://docs.docker.com/engine/reference/commandline/build/#tag) of your Docker image. This is the image name and tag that you specified in the `docker build` command.
+ Replace `` with the `repositoryUri` that you copied. Make sure to include `:latest` at the end of the URI.
```
docker tag docker-image:test :latest
```
Example:
```
docker tag docker-image:test 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world:latest
```
1. Run the [docker push](https://docs.docker.com/engine/reference/commandline/push/) command to deploy your local image to the Amazon ECR repository. Make sure to include `:latest` at the end of the repository URI.
```
docker push 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world:latest
```
1. [Create an execution role](lambda-intro-execution-role.md#permissions-executionrole-api) for the function, if you don't already have one. You need the Amazon Resource Name (ARN) of the role in the next step.
1. Create the Lambda function. For `ImageUri`, specify the repository URI from earlier. Make sure to include `:latest` at the end of the URI.
```
aws lambda create-function \
--function-name hello-world \
--package-type Image \
--code ImageUri=111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world:latest \
--role arn:aws-cn:iam::111122223333:role/lambda-ex
```
**Note**
You can create a function using an image in a different Amazon account, as long as the image is in the same Region as the Lambda function. For more information, see [Amazon ECR cross-account permissions](images-create.md#configuration-images-xaccount-permissions).
1. Invoke the function.
```
aws lambda invoke --function-name hello-world response.json
```
You should see a response like this:
```
{
"ExecutedVersion": "$LATEST",
"StatusCode": 200
}
```
1. To see the output of the function, check the `response.json` file.
To update the function code, you must build the image again, upload the new image to the Amazon ECR repository, and then use the [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html) command to deploy the image to the Lambda function.
Lambda resolves the image tag to a specific image digest. This means that if you point the image tag that was used to deploy the function to a new image in Amazon ECR, Lambda doesn't automatically update the function to use the new image.
To deploy the new image to the same Lambda function, you must use the [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html) command, even if the image tag in Amazon ECR remains the same. In the following example, the `--publish` option creates a new version of the function using the updated container image.
```
aws lambda update-function-code \
--function-name hello-world \
--image-uri 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world:latest \
--publish
```
# Working with layers for Go Lambda functions
We don't recommend using [layers](chapter-layers.md) to manage dependencies for Lambda functions written in Go. This is because Lambda functions in Go compile into a single executable, which you provide to Lambda when you deploy your function. This executable contains your compiled function code, along with all of its dependencies. Using layers not only complicates this process, but also leads to increased cold start times because your functions need to manually load extra assemblies into memory during the init phase.
To use external dependencies with your Go handlers, include them directly in your deployment package. By doing so, you simplify the deployment process and also take advantage of built-in Go compiler optimizations. For an example of how to import and use a dependency like the Amazon SDK for Go in your function, see [Define Lambda function handlers in Go](golang-handler.md).
# Log and monitor Go Lambda functions
Amazon Lambda automatically monitors Lambda functions on your behalf and sends logs to Amazon CloudWatch. Your Lambda function comes with a CloudWatch Logs log group and a log stream for each instance of your function. The Lambda runtime environment sends details about each invocation to the log stream, and relays logs and other output from your function's code. For more information, see [Sending Lambda function logs to CloudWatch Logs](monitoring-cloudwatchlogs.md).
This page describes how to produce log output from your Lambda function's code, and access logs using the Amazon Command Line Interface, the Lambda console, or the CloudWatch console.
**Topics**
+ [Creating a function that returns logs](#golang-logging-output)
+ [Viewing logs in the Lambda console](#golang-logging-console)
+ [Viewing logs in the CloudWatch console](#golang-logging-cwconsole)
+ [Viewing logs using the Amazon Command Line Interface (Amazon CLI)](#golang-logging-cli)
+ [Deleting logs](#golang-logging-delete)
## Creating a function that returns logs
To output logs from your function code, you can use methods on [the fmt package](https://golang.org/pkg/fmt/), or any logging library that writes to `stdout` or `stderr`. The following example uses [the log package](https://golang.org/pkg/log/).
**Example [main.go](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-go/function/main.go) – Logging**
```
func handleRequest(ctx context.Context, event events.SQSEvent) (string, error) {
// event
eventJson, _ := json.MarshalIndent(event, "", " ")
log.Printf("EVENT: %s", eventJson)
// environment variables
log.Printf("REGION: %s", os.Getenv("AWS_REGION"))
log.Println("ALL ENV VARS:")
for _, element := range os.Environ() {
log.Println(element)
}
```
**Example log format**
```
START RequestId: dbda340c-xmpl-4031-8810-11bb609b4c71 Version: $LATEST
2020/03/27 03:40:05 EVENT: {
"Records": [
{
"messageId": "19dd0b57-b21e-4ac1-bd88-01bbb068cb78",
"receiptHandle": "MessageReceiptHandle",
"body": "Hello from SQS!",
"md5OfBody": "7b27xmplb47ff90a553787216d55d91d",
"md5OfMessageAttributes": "",
"attributes": {
"ApproximateFirstReceiveTimestamp": "1523232000001",
"ApproximateReceiveCount": "1",
"SenderId": "123456789012",
"SentTimestamp": "1523232000000"
},
...
2020/03/27 03:40:05 AWS_LAMBDA_LOG_STREAM_NAME=2020/03/27/[$LATEST]569cxmplc3c34c7489e6a97ad08b4419
2020/03/27 03:40:05 AWS_LAMBDA_FUNCTION_NAME=blank-go-function-9DV3XMPL6XBC
2020/03/27 03:40:05 AWS_LAMBDA_FUNCTION_MEMORY_SIZE=128
2020/03/27 03:40:05 AWS_LAMBDA_FUNCTION_VERSION=$LATEST
2020/03/27 03:40:05 AWS_EXECUTION_ENV=AWS_Lambda_go1.x
END RequestId: dbda340c-xmpl-4031-8810-11bb609b4c71
REPORT RequestId: dbda340c-xmpl-4031-8810-11bb609b4c71 Duration: 38.66 ms Billed Duration: 243 ms Memory Size: 128 MB Max Memory Used: 54 MB Init Duration: 203.69 ms
XRAY TraceId: 1-5e7d7595-212fxmpl9ee07c4884191322 SegmentId: 42ffxmpl0645f474 Sampled: true
```
The Go runtime logs the `START`, `END`, and `REPORT` lines for each invocation. The report line provides the following details.
**REPORT line data fields**
+ **RequestId** – The unique request ID for the invocation.
+ **Duration** – The amount of time that your function's handler method spent processing the event.
+ **Billed Duration** – The amount of time billed for the invocation.
+ **Memory Size** – The amount of memory allocated to the function.
+ **Max Memory Used** – The amount of memory used by the function. When invocations share an execution environment, Lambda reports the maximum memory used across all invocations. This behavior might result in a higher than expected reported value.
+ **Init Duration** – For the first request served, the amount of time it took the runtime to load the function and run code outside of the handler method.
+ **XRAY TraceId** – For traced requests, the [Amazon X-Ray trace ID](services-xray.md).
+ **SegmentId** – For traced requests, the X-Ray segment ID.
+ **Sampled** – For traced requests, the sampling result.
## Viewing logs in the Lambda console
You can use the Lambda console to view log output after you invoke a Lambda function.
If your code can be tested from the embedded **Code** editor, you will find logs in the **execution results**. When you use the console test feature to invoke a function, you'll find **Log output** in the **Details** section.
## Viewing logs in the CloudWatch console
You can use the Amazon CloudWatch console to view logs for all Lambda function invocations.
**To view logs on the CloudWatch console**
1. Open the [Log groups page](https://console.amazonaws.cn/cloudwatch/home?#logs:) on the CloudWatch console.
1. Choose the log group for your function (**/aws/lambda/*your-function-name***).
1. Choose a log stream.
Each log stream corresponds to an [instance of your function](lambda-runtime-environment.md). A log stream appears when you update your Lambda function, and when additional instances are created to handle concurrent invocations. To find logs for a specific invocation, we recommend instrumenting your function with Amazon X-Ray. X-Ray records details about the request and the log stream in the trace.
## Viewing logs using the Amazon Command Line Interface (Amazon CLI)
The Amazon CLI is an open-source tool that enables you to interact with Amazon services using commands in your command line shell. To complete the steps in this section, you must have the [Amazon CLI version 2](https://docs.amazonaws.cn/cli/latest/userguide/getting-started-install.html).
You can use the [Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-chap-welcome.html) to retrieve logs for an invocation using the `--log-type` command option. The response contains a `LogResult` field that contains up to 4 KB of base64-encoded logs from the invocation.
**Example retrieve a log ID**
The following example shows how to retrieve a *log ID* from the `LogResult` field for a function named `my-function`.
```
aws lambda invoke --function-name my-function out --log-type Tail
```
You should see the following output:
```
{
"StatusCode": 200,
"LogResult": "U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...",
"ExecutedVersion": "$LATEST"
}
```
**Example decode the logs**
In the same command prompt, use the `base64` utility to decode the logs. The following example shows how to retrieve base64-encoded logs for `my-function`.
```
aws lambda invoke --function-name my-function out --log-type Tail \
--query 'LogResult' --output text --cli-binary-format raw-in-base64-out | base64 --decode
```
The **cli-binary-format** option is required if you're using Amazon CLI version 2. To make this the default setting, run `aws configure set cli-binary-format raw-in-base64-out`. For more information, see [Amazon CLI supported global command line options](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list) in the *Amazon Command Line Interface User Guide for Version 2*.
You should see the following output:
```
START RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Version: $LATEST
"AWS_SESSION_TOKEN": "AgoJb3JpZ2luX2VjELj...", "_X_AMZN_TRACE_ID": "Root=1-5d02e5ca-f5792818b6fe8368e5b51d50;Parent=191db58857df8395;Sampled=0"",ask/lib:/opt/lib",
END RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8
REPORT RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Duration: 79.67 ms Billed Duration: 80 ms Memory Size: 128 MB Max Memory Used: 73 MB
```
The `base64` utility is available on Linux, macOS, and [Ubuntu on Windows](https://docs.microsoft.com/en-us/windows/wsl/install-win10). macOS users may need to use `base64 -D`.
**Example get-logs.sh script**
In the same command prompt, use the following script to download the last five log events. The script uses `sed` to remove quotes from the output file, and sleeps for 15 seconds to allow time for the logs to become available. The output includes the response from Lambda and the output from the `get-log-events` command.
Copy the contents of the following code sample and save in your Lambda project directory as `get-logs.sh`.
The **cli-binary-format** option is required if you're using Amazon CLI version 2. To make this the default setting, run `aws configure set cli-binary-format raw-in-base64-out`. For more information, see [Amazon CLI supported global command line options](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list) in the *Amazon Command Line Interface User Guide for Version 2*.
```
#!/bin/bash
aws lambda invoke --function-name my-function --cli-binary-format raw-in-base64-out --payload '{"key": "value"}' out
sed -i'' -e 's/"//g' out
sleep 15
aws logs get-log-events --log-group-name /aws/lambda/my-function --log-stream-name stream1 --limit 5
```
**Example macOS and Linux (only)**
In the same command prompt, macOS and Linux users may need to run the following command to ensure the script is executable.
```
chmod -R 755 get-logs.sh
```
**Example retrieve the last five log events**
In the same command prompt, run the following script to get the last five log events.
```
./get-logs.sh
```
You should see the following output:
```
{
"StatusCode": 200,
"ExecutedVersion": "$LATEST"
}
{
"events": [
{
"timestamp": 1559763003171,
"message": "START RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf Version: $LATEST\n",
"ingestionTime": 1559763003309
},
{
"timestamp": 1559763003173,
"message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tENVIRONMENT VARIABLES\r{\r \"AWS_LAMBDA_FUNCTION_VERSION\": \"$LATEST\",\r ...",
"ingestionTime": 1559763018353
},
{
"timestamp": 1559763003173,
"message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tEVENT\r{\r \"key\": \"value\"\r}\n",
"ingestionTime": 1559763018353
},
{
"timestamp": 1559763003218,
"message": "END RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\n",
"ingestionTime": 1559763018353
},
{
"timestamp": 1559763003218,
"message": "REPORT RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\tDuration: 26.73 ms\tBilled Duration: 27 ms \tMemory Size: 128 MB\tMax Memory Used: 75 MB\t\n",
"ingestionTime": 1559763018353
}
],
"nextForwardToken": "f/34783877304859518393868359594929986069206639495374241795",
"nextBackwardToken": "b/34783877303811383369537420289090800615709599058929582080"
}
```
## Deleting logs
Log groups aren't deleted automatically when you delete a function. To avoid storing logs indefinitely, delete the log group, or [configure a retention period](https://docs.amazonaws.cn/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html#SettingLogRetention) after which logs are deleted automatically.
# Instrumenting Go code in Amazon Lambda
Lambda integrates with Amazon X-Ray to help you trace, debug, and optimize Lambda applications. You can use X-Ray to trace a request as it traverses resources in your application, which may include Lambda functions and other Amazon services.
To send tracing data to X-Ray, you can use one of two SDK libraries:
+ [Amazon Distro for OpenTelemetry (ADOT)](https://www.amazonaws.cn/otel) – A secure, production-ready, Amazon-supported distribution of the OpenTelemetry (OTel) SDK.
+ [Amazon X-Ray SDK for Go](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-go.html) – An SDK for generating and sending trace data to X-Ray.
Each of the SDKs offer ways to send your telemetry data to the X-Ray service. You can then use X-Ray to view, filter, and gain insights into your application's performance metrics to identify issues and opportunities for optimization.
**Important**
The X-Ray and Powertools for Amazon Lambda SDKs are part of a tightly integrated instrumentation solution offered by Amazon. The ADOT Lambda Layers are part of an industry-wide standard for tracing instrumentation that collect more data in general, but may not be suited for all use cases. You can implement end-to-end tracing in X-Ray using either solution. To learn more about choosing between them, see [Choosing between the Amazon Distro for Open Telemetry and X-Ray SDKs](https://docs.amazonaws.cn/xray/latest/devguide/xray-instrumenting-your-app.html#xray-instrumenting-choosing).
**Topics**
+ [Using ADOT to instrument your Go functions](#golang-adot)
+ [Using the X-Ray SDK to instrument your Go functions](#golang-xray-sdk)
+ [Activating tracing with the Lambda console](#golang-tracing-console)
+ [Activating tracing with the Lambda API](#golang-tracing-api)
+ [Activating tracing with Amazon CloudFormation](#golang-tracing-cloudformation)
+ [Interpreting an X-Ray trace](#golang-tracing-interpretation)
## Using ADOT to instrument your Go functions
ADOT provides fully managed Lambda [layers](chapter-layers.md) that package everything you need to collect telemetry data using the OTel SDK. By consuming this layer, you can instrument your Lambda functions without having to modify any function code. You can also configure your layer to do custom initialization of OTel. For more information, see [Custom configuration for the ADOT Collector on Lambda](https://aws-otel.github.io/docs/getting-started/lambda#custom-configuration-for-the-adot-collector-on-lambda) in the ADOT documentation.
For Go runtimes, you can add the **Amazon managed Lambda layer for ADOT Go** to automatically instrument your functions. For detailed instructions on how to add this layer, see [Amazon Distro for OpenTelemetry Lambda Support for Go](https://aws-otel.github.io/docs/getting-started/lambda/lambda-go) in the ADOT documentation.
## Using the X-Ray SDK to instrument your Go functions
To record details about calls that your Lambda function makes to other resources in your application, you can also use the Amazon X-Ray SDK for Go. To get the SDK, download the SDK from its [GitHub repository](https://github.com/aws/aws-xray-sdk-go) with `go get`:
```
go get github.com/aws/aws-xray-sdk-go
```
To instrument Amazon SDK clients, pass the client to the `xray.AWS()` method. You can then trace calls by using the `WithContext` version of the method.
```
svc := s3.New(session.New())
xray.AWS(svc.Client)
...
svc.ListBucketsWithContext(ctx aws.Context, input *ListBucketsInput)
```
After you add the correct dependencies and make the necessary code changes, activate tracing in your function's configuration via the Lambda console or the API.
## Activating tracing with the Lambda console
To toggle active tracing on your Lambda function with the console, follow these steps:
**To turn on active tracing**
1. Open the [Functions page](https://console.amazonaws.cn/lambda/home#/functions) of the Lambda console.
1. Choose a function.
1. Choose **Configuration** and then choose **Monitoring and operations tools**.
1. Under **Additional monitoring tools**, choose **Edit**.
1. Under **CloudWatch Application Signals and Amazon X-Ray**, choose **Enable** for **Lambda service traces**.
1. Choose **Save**.
## Activating tracing with the Lambda API
Configure tracing on your Lambda function with the Amazon CLI or Amazon SDK, use the following API operations:
+ [UpdateFunctionConfiguration](https://docs.amazonaws.cn/lambda/latest/api/API_UpdateFunctionConfiguration.html)
+ [GetFunctionConfiguration](https://docs.amazonaws.cn/lambda/latest/api/API_GetFunctionConfiguration.html)
+ [CreateFunction](https://docs.amazonaws.cn/lambda/latest/api/API_CreateFunction.html)
The following example Amazon CLI command enables active tracing on a function named **my-function**.
```
aws lambda update-function-configuration --function-name my-function \
--tracing-config Mode=Active
```
Tracing mode is part of the version-specific configuration when you publish a version of your function. You can't change the tracing mode on a published version.
## Activating tracing with Amazon CloudFormation
To activate tracing on an `AWS::Lambda::Function` resource in an Amazon CloudFormation template, use the `TracingConfig` property.
**Example [function-inline.yml](https://github.com/awsdocs/aws-lambda-developer-guide/blob/master/templates/function-inline.yml) – Tracing configuration**
```
Resources:
function:
Type: [AWS::Lambda::Function](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html)
Properties:
TracingConfig:
Mode: Active
...
```
For an Amazon Serverless Application Model (Amazon SAM) `AWS::Serverless::Function` resource, use the `Tracing` property.
**Example [template.yml](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/template.yml) – Tracing configuration**
```
Resources:
function:
Type: [AWS::Serverless::Function](https://docs.amazonaws.cn/serverless-application-model/latest/developerguide/sam-resource-function.html)
Properties:
Tracing: Active
...
```
## Interpreting an X-Ray trace
Your function needs permission to upload trace data to X-Ray. When you activate tracing in the Lambda console, Lambda adds the required permissions to your function's [execution role](lambda-intro-execution-role.md). Otherwise, add the [AWSXRayDaemonWriteAccess](https://console.amazonaws.cn/iam/home#/policies/arn:aws-cn:iam::aws:policy/AWSXRayDaemonWriteAccess) policy to the execution role.
After you've configured active tracing, you can observe specific requests through your application. The [ X-Ray service graph](https://docs.amazonaws.cn/xray/latest/devguide/aws-xray.html#xray-concepts-servicegraph) shows information about your application and all its components. The following example shows an application with two functions. The primary function processes events and sometimes returns errors. The second function at the top processes errors that appear in the first's log group and uses the Amazon SDK to call X-Ray, Amazon Simple Storage Service (Amazon S3), and Amazon CloudWatch Logs.
![\[\]](http://docs.amazonaws.cn/en_us/lambda/latest/dg/images/sample-errorprocessor-servicemap.png)
X-Ray doesn't trace all requests to your application. X-Ray applies a sampling algorithm to ensure that tracing is efficient, while still providing a representative sample of all requests. The sampling rate is 1 request per second and 5 percent of additional requests. You can't configure the X-Ray sampling rate for your functions.
In X-Ray, a *trace* records information about a request that is processed by one or more *services*. Lambda records 2 segments per trace, which creates two nodes on the service graph. The following image highlights these two nodes:
![\[\]](http://docs.amazonaws.cn/en_us/lambda/latest/dg/images/xray-servicemap-function.png)
The first node on the left represents the Lambda service, which receives the invocation request. The second node represents your specific Lambda function. The following example shows a trace with these two segments. Both are named **my-function**, but one has an origin of `AWS::Lambda` and the other has an origin of `AWS::Lambda::Function`. If the `AWS::Lambda` segment shows an error, the Lambda service had an issue. If the `AWS::Lambda::Function` segment shows an error, your function had an issue.
![\[\]](http://docs.amazonaws.cn/en_us/lambda/latest/dg/images/V2_sandbox_images/my-function-2-v1.png)
This example expands the `AWS::Lambda::Function` segment to show its three subsegments.
**Note**
Amazon is currently implementing changes to the Lambda service. Due to these changes, you may see minor differences between the structure and content of system log messages and trace segments emitted by different Lambda functions in your Amazon Web Services account.
The example trace shown here illustrates the old-style function segment. The differences between the old- and new-style segments are described in the following paragraphs.
These changes will be implemented during the coming weeks, and all functions in all Amazon Web Services Regions except the China and GovCloud regions will transition to use the new-format log messages and trace segments.
The old-style function segment contains the following subsegments:
+ **Initialization** – Represents time spent loading your function and running [initialization code](foundation-progmodel.md). This subsegment only appears for the first event that each instance of your function processes.
+ **Invocation** – Represents the time spent running your handler code.
+ **Overhead** – Represents the time the Lambda runtime spends preparing to handle the next event.
The new-style function segment doesn't contain an `Invocation` subsegment. Instead, customer subsegments are attached directly to the function segment. For more information about the structure of the old- and new-style function segments, see [Understanding X-Ray traces](services-xray.md#services-xray-traces).
You can also instrument HTTP clients, record SQL queries, and create custom subsegments with annotations and metadata. For more information, see the [Amazon X-Ray SDK for Go](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-python.html) in the *Amazon X-Ray Developer Guide*.
**Pricing**
You can use X-Ray tracing for free each month up to a certain limit as part of the Amazon Free Tier. Beyond that threshold, X-Ray charges for trace storage and retrieval. For more information, see [Amazon X-Ray pricing](https://www.amazonaws.cn/xray/pricing/).