本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 設定 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 格式輸出函數的應用程式日誌 (函數程式碼產生的日誌)。當您針對這些執行期設定函數的日誌格式時，您選擇的組態會同時套用至系統和應用程式日誌。 對於支援的執行期，如果您的函數使用支援的記錄程式庫或方法，則不需要變更 Lambda 現有程式碼，即可擷取結構化 JSON 中的記錄。 **注意** 使用 JSON 日誌格式新增其他中繼資料，並將日誌訊息編碼為包含一系列索引鍵值組的 JSON 物件。因此，函數日誌訊息的大小可能會增加。 ## 支援的執行期和記錄方法 Lambda 目前支援針對下列執行期輸出 JSON 結構化應用程式日誌的選項。 | Language | 支援的版本 | | --- | --- | | Java | 除了 Amazon Linux 1 上的 Java 8 以外的所有 Java 執行期 | | .NET | .NET 8 及更新版本 | | Node.js | Node.js 16 及更高版本 | | Python | Python 3.8 及更高版本 | | Rust | N/A | 若要讓 Lambda 以結構化 JSON 格式將函數的應用程式日誌傳送至 CloudWatch，您的函數必須使用下列內建記錄工具來輸出日誌檔： + **Java**：`LambdaLogger`記錄器或 Log4j2。如需詳細資訊，請參閱[記錄和監控 Java Lambda 函數](java-logging.md)。 + **.NET**：內容物件上的`ILambdaLogger`執行個體。如需詳細資訊，請參閱[記錄和監控 C\$1 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)。 + **Rust**：`tracing`木箱。如需詳細資訊，請參閱[記錄和監控 Rust Lambda 函數](rust-logging.md)。 對於其他受管的 Lambda 執行期，Lambda 目前僅支援以結構化 JSON 格式擷取系統記錄。不過，您仍然可以使用 Powertools 等記錄工具來擷取任何執行時間中結構式 JSON 格式的應用程式日誌，用於 AWS Lambda 輸出 JSON 格式的日誌輸出。 ## 預設日誌格式 目前，所有 Lambda 執行期的預設日誌格式都是純文字。對於 Lambda 受管執行個體，日誌格式一律為 JSON，且無法變更。 如果您已經使用 Powertools for 之類的日誌程式庫 AWS Lambda ，以 JSON 結構化格式產生函數日誌，則如果您選取 JSON 日誌格式，則不需要變更程式碼。Lambda 不會對任何已經進行 JSON 編碼的日誌進行雙重編碼，因此您函數的應用程式日誌將繼續像以前一樣被擷取。 ## 系統日誌的 JSON 格式 當您將函數的日誌檔格式設定為 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 格式 當您將函數的日誌格式設定為 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) 資源來設定函數的日誌格式。 變更函數的日誌格式不會影響儲存在 CloudWatch Logs 日誌中的現有記錄。只有新的日誌檔會使用更新的格式。 如果您將函數的日誌格式變更為 JSON 但未設定日誌層級，Lambda 會自動將函數的應用程序日誌層級和系統日誌層級設為 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 無法識別您的指標。 **重要** 如果您的函數使用 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 日誌格式，我們也建議您進行測試，以確保與函數的內嵌指標相容。如需有關發出 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 ```