sam logs - Amazon Serverless Application Model
UsageOptionsExamples
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

sam logs

This page provides reference information for the Amazon Serverless Application Model Command Line Interface (Amazon SAM CLI) sam logs command.

For an introduction to the Amazon SAM CLI, see What is the Amazon SAM CLI?.

The sam logs command fetches logs that are generated by your Amazon Lambda functions.

Usage

$ sam logs <options>

Options

--config-env TEXT

The environment name specifying the default parameter values in the configuration file to use. The default value is "default". For more information about configuration files, see Amazon SAM CLI configuration file.

--config-file PATH

The path and file name of the configuration file containing default parameter values to use. The default value is "samconfig.toml" in the root of the project directory. For more information about configuration files, see Amazon SAM CLI configuration file.

--cw-log-group LIST

Includes logs from the CloudWatch Logs log groups that you specify. If you specify this option along with name, Amazon SAM includes logs from the specified log groups in addition to logs from the named resources.

--debug

Turns on debug logging to print debug message generated by the Amazon SAM CLI and display timestamps.

---end-time, e TEXT

Fetches logs up to this time. The time can be relative values like '5mins ago', 'tomorrow', or a formatted timestamp like '2018-01-01 10:10:10'.

--filter TEXT

Lets you specify an expression to quickly find logs that match terms, phrases, or values in your log events. This can be a simple keyword (for example, "error") or a pattern that's supported by Amazon CloudWatch Logs. For the syntax, see the Amazon CloudWatch Logs documentation.

--help

Shows this message and exits.

--include-traces

Includes X-Ray traces in the log output.

--name, -n TEXT

The name of the resource for which to fetch logs. If this resource is part of an Amazon CloudFormation stack, this can be the logical ID of the function resource in the Amazon CloudFormation/Amazon SAM template. Multiple names can be provided by repeating the parameter again. If resource is in a nested stack, the name can be prepended by the name of the nested stack name to pull logs from that resource (NestedStackLogicalId/ResourceLogicalId). If the resource name isn't given, the given stack will be scanned and log information will be pulled for all supported resources. If you don't specify this option, Amazon SAM fetches logs for all resources in the stack that you specify. The following resource types are supported:

  • AWS::Serverless::Function

  • AWS::Lambda::Function

  • AWS::Serverless::Api

  • AWS::ApiGateway::RestApi

  • AWS::Serverless::HttpApi

  • AWS::ApiGatewayV2::Api

  • AWS::Serverless::StateMachine

  • AWS::StepFunctions::StateMachine

--output TEXT

Specifies the output format for logs. To print formatted logs, specify text. To print the logs as JSON, specify json.

--profile TEXT

The specific profile from your credential file that gets Amazon credentials.

--region TEXT

The Amazon Region to deploy to. For example, us-east-1.

--save-params

Save the parameters that you provide at the command line to the Amazon SAM configuration file.

--stack-name TEXT

The name of the Amazon CloudFormation stack that the resource is a part of.

--start-time, -s TEXT

Fetches logs starting at this time. The time can be relative values like '5mins ago', 'yesterday', or a formatted timestamp like '2018-01-01 10:10:10'. It defaults to '10mins ago'.

--tail, -t

Tails the log output. This ignores the end time argument and continues to fetch logs as they become available.

Examples

When your functions are a part of an Amazon CloudFormation stack, you can fetch logs by using the function's logical ID when you specify the stack name.

$ sam logs -n HelloWorldFunction --stack-name myStack

View logs for a specific time range using the -s (--start-time) and -e (--end-time) options.

$ sam logs -n HelloWorldFunction --stack-name myStack -s '10min ago' -e '2min ago'

You can also add the --tail option to wait for new logs and see them as they arrive.

$ sam logs -n HelloWorldFunction --stack-name myStack --tail

Use the --filter option to quickly find logs that match terms, phrases or values in your log events.

$ sam logs -n HelloWorldFunction --stack-name myStack --filter "error"

View the logs for a resource in a child stack.

$ sam logs --stack-name myStack -n childStack/HelloWorldFunction

Tail logs for all supported resources in your application.

$ sam logs --stack-name sam-app --tail

Fetch logs for a specific Lambda function and API Gateway API in your application.

$ sam logs --stack-name sam-app --name HelloWorldFunction --name HelloWorldRestApi

Fetch logs for all supported resources in your application, and additionally from the specified log groups.

$ sam logs --cw-log-group /aws/lambda/myfunction-123 --cw-log-group /aws/lambda/myfunction-456