本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 設定 JSON 和純文字日誌格式
將日誌輸出擷取為 JSON 鍵值對，可讓您在偵錯事件函數時更輕鬆地搜尋和篩選。使用 JSON 格式的日誌檔，您也可以在日誌檔中新增標籤和內容資訊。這可以幫助您對大量日誌資料執行自動分析。除非您的開發工作流程仰賴使用純文字 Lambda 日誌的現有工具，否則建議您為日誌格式選取 JSON。
**Lambda 受管執行個體**
Lambda 受管執行個體僅支援 JSON 日誌格式。當您建立受管執行個體函數時，Lambda 會自動將日誌格式設定為 JSON，您無法將其變更為純文字。如需受管執行個體的詳細資訊，請參閱 [Lambda 受管執行個體](lambda-managed-instances.md)。
對於所有 Lambda 受管執行時間，您可以選擇事件函數的系統日誌是以非結構化純文字或 JSON 格式傳送到 CloudWatch Logs。系統日誌是 Lambda 產生的日誌，有時也稱為平台事件日誌。
對於[支援的執行時間](#monitoring-cloudwatchlogs-logformat-supported)，當您使用其中一個支援的內建記錄方法時，Lambda 也可以以結構化 JSON 格式輸出 Event Function 的應用程式日誌 (Event Function 程式碼產生的日誌）。當您為這些執行時間設定 Event Function 的日誌格式時，您選擇的組態會同時套用至系統和應用程式日誌。
對於支援的執行時間，如果您的 Event Function 使用支援的日誌程式庫或方法，您不需要對 Lambda 的現有程式碼進行任何變更，即可擷取結構化 JSON 中的日誌。
**注意**
使用 JSON 日誌格式新增其他中繼資料，並將日誌訊息編碼為包含一系列索引鍵值組的 JSON 物件。因此，Event Function 日誌訊息的大小可能會增加。
## 支援的執行期和記錄方法
Lambda 目前支援針對下列執行期輸出 JSON 結構化應用程式日誌的選項。
| Language | 支援的版本 |
| --- | --- |
| Java | 除了 Amazon Linux 1 上的 Java 8 以外的所有 Java 執行期 |
| .NET | .NET 8 及更新版本 |
| Node.js | Node.js 16 及更高版本 |
| Python | Python 3.8 及更高版本 |
| Ruby | Ruby 4.0 和更新版本 |
| Rust | N/A |
若要讓 Lambda 以結構化 JSON 格式將 Event Function 的應用程式日誌傳送至 CloudWatch，您的 Event Function 必須使用下列內建記錄工具來輸出日誌：
+ **Java**：`LambdaLogger`記錄器或 Log4j2。如需詳細資訊，請參閱[記錄和監控 Java Lambda 事件函數](java-logging.md)。
+ **.NET**：內容物件上的`ILambdaLogger`執行個體。如需詳細資訊，請參閱[記錄和監控 C\# Lambda 事件函數](csharp-logging.md)。
+ **Node.js** - 主控台方法 `console.trace`、`console.debug`、`console.log``console.info`、`console.error`、 和 `console.warn`。如需詳細資訊，請參閱[記錄和監控 Node.js Lambda 事件函數](nodejs-logging.md)。
+ **Python**：標準 Python `logging`程式庫。如需詳細資訊，請參閱[記錄和監控 Python Lambda 事件函數](python-logging.md)。
+ **Ruby**：標準 Ruby `Logger`程式庫。如需詳細資訊，請參閱[記錄和監控 Ruby Lambda 事件函數](ruby-logging.md)。
+ **Rust**：`tracing`木箱。如需詳細資訊，請參閱[記錄和監控 Rust Lambda 事件函數](rust-logging.md)。
對於其他受管的 Lambda 執行期，Lambda 目前僅支援以結構化 JSON 格式擷取系統記錄。不過，您仍然可以使用 Powertools 等日誌工具，針對 AWS Lambda 該輸出 JSON 格式日誌輸出，以結構化 JSON 格式擷取任何執行時間的應用程式日誌。
## 預設日誌格式
目前，所有 Lambda 執行期的預設日誌格式都是純文字。對於 Lambda 受管執行個體，日誌格式一律為 JSON，且無法變更。
如果您已經使用 Powertools for 之類的日誌程式庫 AWS Lambda ，以 JSON 結構化格式產生事件函數日誌，則如果您選取 JSON 日誌格式，則不需要變更程式碼。Lambda 不會對已經 JSON 編碼的任何日誌進行雙重編碼，因此您的 Event Function 的應用程式日誌會繼續像以前一樣擷取。
## 系統日誌的 JSON 格式
當您將 Event Function 的日誌格式設定為 JSON 時，每個系統日誌項目 （平台事件） 都會擷取為 JSON 物件，其中包含具有下列索引鍵的索引鍵值對：
+ `"time"` - 產生日誌訊息的時間
+ `"type"` - 記錄的事件類型
+ `"record"` - 日誌輸出的內容
`"record"` 值的格式會根據日誌的事件類型而有所不同。如需更多資訊，請參閱[遙測 API `Event` 物件類型](telemetry-schema-reference.md#telemetry-api-events)。如需有關指派給系統日誌事件的日誌層級的詳細資訊，請參閱 [系統日誌層級事件映射](monitoring-cloudwatchlogs-log-level.md#monitoring-cloudwatchlogs-log-level-mapping)。
為了進行比較，下列兩個範例會以純文字和結構化 JSON 格式顯示相同的記錄輸出。請注意，在大多數情況下，系統日誌事件在 JSON 格式輸出時所包含的資訊會比以純文字輸出時更多。
**Example 純文字：**
```
2024-03-13 18:56:24.046000 fbe8c1 INIT_START Runtime Version: python:3.12.v18 Runtime Version ARN: arn:aws:lambda:eu-west-1::runtime:edb5a058bfa782cb9cedc6d534ac8b8c193bc28e9a9879d9f5ebaaf619cd0fc0
```
**Example 結構化的 JSON：**
```
{
"time": "2024-03-13T18:56:24.046Z",
"type": "platform.initStart",
"record": {
"initializationType": "on-demand",
"phase": "init",
"runtimeVersion": "python:3.12.v18",
"runtimeVersionArn": "arn:aws:lambda:eu-west-1::runtime:edb5a058bfa782cb9cedc6d534ac8b8c193bc28e9a9879d9f5ebaaf619cd0fc0"
}
}
```
**注意**
[使用遙測 API 即時存取延伸功能的遙測資料](telemetry-api.md) 始終以 JSON 格式發出平台事件，例如 `START` 和 `REPORT`。設定 Lambda 傳送至 CloudWatch 的系統日誌格式不會影響 Lambda 遙測 API 行為。
## 應用程式日誌的 JSON 格式
當您將 Event Function 的日誌格式設定為 JSON 時，使用支援的日誌程式庫和方法寫入的應用程式日誌輸出會擷取為 JSON 物件，其中包含具有下列金鑰的金鑰值對。
+ `"timestamp"` - 產生日誌訊息的時間
+ `"level"` - 指派給訊息的日誌層級
+ `"message"` - 日誌訊息的內容
+ `"requestId"` (Python、.NET 和 Node.js) 或 `"AWSrequestId"`(Java) - 事件函數調用的唯一請求 ID
根據函數使用的執行時間和記錄方法，此 JSON 物件也可能包含額外的金鑰對。例如，在 Node.js 中，如果您的函數使用`console`方法來記錄使用多個引數的錯誤物件，則 JSON 物件包含具有索引鍵 `errorMessage`、 `errorType`和 的額外索引鍵值對`stackTrace`。若要進一步了解不同 Lambda 執行期中的 JSON 格式的日誌，請參閱 [記錄和監控 Python Lambda 事件函數](python-logging.md)、[記錄和監控 Node.js Lambda 事件函數](nodejs-logging.md) 和 [記錄和監控 Java Lambda 事件函數](java-logging.md)。
**注意**
Lambda 用於時間戳記值的關鍵對於系統日誌和應用程式日誌而言不同。對於系統記錄，Lambda 會使用索引鍵 `"time"` 來維持遙測 API 的一致性。對於應用程式日誌，Lambda 會遵循支援的執行期和使用 `"timestamp"` 的慣例。
為了進行比較，下列兩個範例會以純文字和結構化 JSON 格式顯示相同的記錄輸出。
**Example 純文字：**
```
2024-10-27T19:17:45.586Z 79b4f56e-95b1-4643-9700-2807f4e68189 INFO some log message
```
**Example 結構化的 JSON：**
```
{
"timestamp":"2024-10-27T19:17:45.586Z",
"level":"INFO",
"message":"some log message",
"requestId":"79b4f56e-95b1-4643-9700-2807f4e68189"
}
```
## 設定事件函數的日誌格式
若要設定事件函數的日誌格式，您可以使用 Lambda 主控台或 AWS Command Line Interface (AWS CLI)。您也可以使用 [CreateFunction](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html) 和 [UpdateFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionConfiguration.html) Lambda API 命令、 AWS Serverless Application Model (AWS SAM) [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html) 資源和 CloudFormation [AWS::Lambda::Function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html) 資源來設定 Event Function 的日誌格式。
變更事件函數的日誌格式不會影響儲存在 CloudWatch Logs 中的現有日誌。只有新日誌會使用更新的格式。
如果您將 Event Function 的日誌格式變更為 JSON，但未設定日誌層級，則 Lambda 會自動將 Event Function 的應用程式日誌層級和系統日誌層級設定為 INFO。這意味著 Lambda 只會傳送 INFO 及更低層級的日誌輸出至 CloudWatch Logs。若要進一步了解應用程式和系統日誌層級篩選，請參閱 [日誌層級篩選](monitoring-cloudwatchlogs-log-level.md)
**注意**
對於 Python 執行時間，當您的事件函數的日誌格式設定為純文字時，預設日誌層級設定為 WARN。這意味著 Lambda 只會傳送 WARN 及更低層級的日誌輸出至 CloudWatch Logs。將事件函數的日誌格式變更為 JSON 會變更此預設行為。若要進一步了解以 Python 記錄日誌，請參閱 [記錄和監控 Python Lambda 事件函數](python-logging.md)。
對於發出內嵌指標格式 (EMF) 日誌的 Node.js 函數，將事件函數的日誌格式變更為 JSON 可能會導致 CloudWatch 無法辨識您的指標。
**重要**
如果您的 Event Function 使用 Powertools for AWS Lambda (TypeScript) 或開放原始碼 EMF 用戶端程式庫來發出 EMF 日誌，請將 [Powertools](https://github.com/aws-powertools/powertools-lambda-typescript) 和 [EMF](https://www.npmjs.com/package/aws-embedded-metrics) 程式庫更新為最新版本，以確保 CloudWatch 可以繼續正確剖析您的日誌。如果您切換至 JSON 日誌格式，我們也建議您進行測試，以確保與 Event Function 內嵌指標的相容性。如需有關發出 EMF 日誌檔之 node.js 函數的進一步建議，請參閱 [搭配結構化 JSON 日誌使用內嵌指標格式 (EMF) 用戶端程式庫](nodejs-logging.md#nodejs-logging-advanced-emf)。
**設定事件函數的日誌格式 （主控台）**
1. 開啟 Lambda [主控台的事件函數頁面](https://console.aws.amazon.com/lambda/home#/functions)。
1. 選擇事件函數
1. 在事件函數組態頁面上，選擇**監控和操作工具**。
1. 在**日誌組態**窗格中，選擇**編輯**。
1. 在**日誌內容**之下，針對**日誌檔格式**選取**文字**或 **JSON**。
1. 選擇**儲存**。
**若要變更現有函數的日誌格式 (AWS CLI)**
+ 若要變更現有函數的日誌格式，請使用 [update-function-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-configuration.html) 命令。將 `LoggingConfig` 中 `LogFormat` 選項設定為 `JSON` 或 `Text`。
```
aws lambda update-function-configuration \
--function-name myFunction \
--logging-config LogFormat=JSON
```
**若要在建立函數 (AWS CLI) 時設定記錄格式**
+ 若要在建立新函數時設定日誌格式，請使用 [create-function](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/create-function.html) 命令中的 `--logging-config` 選項。將 `LogFormat` 設定為 `JSON` 或 `Text`。下列範例命令會建立一個 Node.js 函數，以結構化 JSON 輸出日誌。
如果您在建立函數時未指定日誌格式，Lambda 會使用您選擇的執行時間版本的預設日誌格式。如需有關預設記錄格式的資訊，請參閱 [預設日誌格式](#monitoring-cloudwatchlogs-format-default)。
```
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
```