# Log-level filtering


Lambda can filter your function's logs so that only logs of a certain detail level or lower are sent to CloudWatch Logs. You can configure log-level filtering separately for your function's system logs (the logs that Lambda generates) and application logs (the logs that your function code generates).

For [Supported runtimes and logging methods](monitoring-cloudwatchlogs-logformat.md#monitoring-cloudwatchlogs-logformat-supported), you don't need to make any changes to your function code for Lambda to filter your function's application logs.

For all other runtimes and logging methods , your function code must output log events to `stdout` or `stderr` as JSON formatted objects that contain a key value pair with the key `"level"`. For example, Lambda interprets the following output to `stdout` as a DEBUG level log.

```
print('{"level": "debug", "msg": "my debug log", "timestamp": "2024-11-02T16:51:31.587199Z"}')
```

If the `"level"` value field is invalid or missing, Lambda will assign the log output the level INFO. For Lambda to use the timestamp field, you must specify the time in valid [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp format. If you don't supply a valid timestamp, Lambda will assign the log the level INFO and add a timestamp for you.

When naming the timestamp key, follow the conventions of the runtime you are using. Lambda supports most common naming conventions used by the managed runtimes.

**Note**  
To use log-level filtering, your function must be configured to use the JSON log format. The default log format for all Lambda managed runtimes is currently plain text. To learn how to configure your function's log format to JSON, see [Setting your function's log format](monitoring-cloudwatchlogs-logformat.md#monitoring-cloudwatchlogs-set-format).

For application logs (the logs generated by your function code), you can choose between the following log levels.


| Log level | Standard usage | 
| --- | --- | 
| TRACE (most detail) | The most fine-grained information used to trace the path of your code's execution | 
| DEBUG | Detailed information for system debugging | 
| INFO | Messages that record the normal operation of your function | 
| WARN | Messages about potential errors that may lead to unexpected behavior if unaddressed | 
| ERROR | Messages about problems that prevent the code from performing as expected | 
| FATAL (least detail) | Messages about serious errors that cause the application to stop functioning | 

When you select a log level, Lambda sends logs at that level and lower to CloudWatch Logs. For example, if you set a function’s application log level to WARN, Lambda doesn’t send log outputs at the INFO and DEBUG levels. The default application log level for log filtering is INFO.

When Lambda filters your function’s application logs, log messages with no level will be assigned the log level INFO.

For system logs (the logs generated by the Lambda service), you can choose between the following log levels.


| Log level | Usage | 
| --- | --- | 
| DEBUG (most detail) | Detailed information for system debugging | 
| INFO | Messages that record the normal operation of your function | 
| WARN (least detail) | Messages about potential errors that may lead to unexpected behavior if unaddressed | 

When you select a log level, Lambda sends logs at that level and lower. For example, if you set a function’s system log level to INFO, Lambda doesn’t send log outputs at the DEBUG level.

By default, Lambda sets the system log level to INFO. With this setting, Lambda automatically sends `"start"` and `"report"` log messages to CloudWatch. To receive more or less detailed system logs, change the log level to DEBUG or WARN. To see a list of the log levels that Lambda maps different system log events to, see [System log level event mapping](#monitoring-cloudwatchlogs-log-level-mapping).

## Configuring log-level filtering


To configure application and system log-level filtering for your function, you can use the Lambda console or the AWS Command Line Interface (AWS CLI). You can also configure a function’s log level using the [CreateFunction](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html) and [UpdateFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionConfiguration.html) Lambda API commands, the AWS Serverless Application Model (AWS SAM) [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html) resource, and the CloudFormation [AWS::Lambda::Function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html) resource.

Note that if you set your function's log level in your code, this setting takes precedence over any other log level settings you configure. For example, if you use the Python `logging` `setLevel()` method to set your function's logging level to INFO, this setting takes precedence over a setting of WARN that you configure using the Lambda console.

**To configure an existing function’s application or system log level (console)**

1. Open the [Functions page](https://console.aws.amazon.com/lambda/home#/functions) of the Lambda console.

1. Choose a function.

1. On the function configuration page, choose **Monitoring and operations tools**.

1. In the **Logging configuration** pane, choose **Edit**.

1. Under **Log content**, for **Log format** ensure **JSON** is selected.

1. Using the radio buttons, select your desired **Application log level** and **System log level** for your function.

1. Choose **Save**.

**To configure an existing function’s application or system log level (AWS CLI)**
+ To change the application or system log level of an existing function, use the [update-function-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-configuration.html) command. Use `--logging-config` to set `SystemLogLevel` to one of `DEBUG`, `INFO`, or `WARN`. Set `ApplicationLogLevel` to one of `DEBUG`, `INFO`, `WARN`, `ERROR`, or `FATAL`. 

  ```
  aws lambda update-function-configuration \
    --function-name myFunction \
    --logging-config LogFormat=JSON,ApplicationLogLevel=ERROR,SystemLogLevel=WARN
  ```

**To configure log-level filtering when you create a function**
+ To configure log-level filtering when you create a new function, use `--logging-config` to set the `SystemLogLevel` and `ApplicationLogLevel` keys in the [create-function](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/create-function.html) command. Set `SystemLogLevel` to one of `DEBUG`, `INFO`, or `WARN`. Set `ApplicationLogLevel` to one of `DEBUG`, `INFO`, `WARN`, `ERROR`, or `FATAL`.

  ```
  aws lambda create-function \
    --function-name myFunction \
    --runtime nodejs24.x \
    --handler index.handler \
    --zip-file fileb://function.zip \
    --role arn:aws:iam::123456789012:role/LambdaRole \ 
    --logging-config LogFormat=JSON,ApplicationLogLevel=ERROR,SystemLogLevel=WARN
  ```

## System log level event mapping


For system level log events generated by Lambda, the following table defines the log level assigned to each event. To learn more about the events listed in the table, see [Lambda Telemetry API `Event` schema reference](telemetry-schema-reference.md)


| Event name | Condition | Assigned log level | 
| --- | --- | --- | 
| initStart | runtimeVersion is set | INFO | 
| initStart | runtimeVersion is not set | DEBUG | 
| initRuntimeDone | status=success | DEBUG | 
| initRuntimeDone | status\$1=success | WARN | 
| initReport | initializationType\$1=on-demand | INFO | 
| initReport | initializationType=on-demand | DEBUG | 
| initReport | status\$1=success | WARN | 
| restoreStart | runtimeVersion is set | INFO | 
| restoreStart | runtimeVersion is not set | DEBUG | 
| restoreRuntimeDone | status=success | DEBUG | 
| restoreRuntimeDone | status\$1=success | WARN | 
| restoreReport | status=success | INFO | 
| restoreReport | status\$1=success | WARN | 
| start | - | INFO | 
| runtimeDone | status=success | DEBUG | 
| runtimeDone | status\$1=success | WARN | 
| report | status=success | INFO | 
| report | status\$1=success | WARN | 
| extension | state=success | INFO | 
| extension | state\$1=success | WARN | 
| logSubscription | - | INFO | 
| telemetrySubscription | - | INFO | 
| logsDropped | - | WARN | 

**Note**  
The [Accessing real-time telemetry data for extensions using the Telemetry API](telemetry-api.md) always emits the complete set of platform events. Configuring the level of the system logs Lambda sends to CloudWatch doesn’t affect Lambda Telemetry API behavior.

## Application log-level filtering with custom runtimes


When you configure application log-level filtering for your function, behind the scenes Lambda sets the application log level in the runtime using the `AWS_LAMBDA_LOG_LEVEL` environment variable. Lambda also sets your function's log format using the `AWS_LAMBDA_LOG_FORMAT` environment variable. You can use these variables to integrate Lambda advanced logging controls into a [custom runtime](runtimes-custom.md).

For the ability to configure logging settings for a function using a custom runtime with the Lambda console, AWS CLI, and Lambda APIs, configure your custom runtime to check the value of these environment variables. You can then configure your runtime's loggers in accordance with the log format and log levels you select.