設定 Lambda 函數的進階記錄控制項 - AWS Lambda
設定JSON和純文字記錄格式日誌層級篩選設定 CloudWatch 記錄群組

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

設定 Lambda 函數的進階記錄控制項

為了讓您更妥善地控制您擷取、處理和使用函數日誌的方式，Lambda 提供下列日誌組態選項：

  • 日誌格式-在純文本和結構化JSON格式之間進行選擇

  • 記錄層級-針對JSON結構化記錄，選擇 Lambda 傳送至的記錄詳細資料層級 CloudWatchERROR，例如DEBUG、或 INFO

  • 日誌組-選擇您的功能發送日誌的日誌組 CloudWatch

若要深入了解如何設定進階記錄控制項，請參閱下列各節：

設定JSON和純文字記錄格式

將日誌輸出捕獲為JSON鍵值對可以更輕鬆地在調試函數時進行搜索和過濾。使用JSON格式化日誌，您還可以將標籤和上下文信息添加到日誌中。這可以幫助您對大量日誌資料執行自動分析。除非您的開發工作流程依賴使JSON用純文字 Lambda 記錄的現有工具，否則建議您選取記錄格式。

對於所有 Lambda 受管執行階段，您可以選擇是否以非結構化純文字或JSON格式將函數的系統 CloudWatch 日誌傳送至 Logs。系統日誌是 Lambda 產生的日誌，有時也稱為平台事件日誌。

對於支援的執行階段，當您使用其中一種支援的內建記錄方法時，Lambda 也可以以結構化JSON格式輸出函數的應用程式記錄 (函數程式碼產生的記錄)。當您針對這些執行期設定函數的日誌格式時，您選擇的組態會同時套用至系統和應用程式日誌。

對於支援的執行階段，如果您的函數使用支援的記錄程式庫或方法，則不需要變更 Lambda 現有程式碼，即可擷取結構化JSON的記錄。

注意

使用JSON記錄格式可新增其他中繼資料，並將記錄訊息編碼為包含一系列索引鍵值配對的JSON物件。因此，函數日誌訊息的大小可能會增加。

支援的執行期和記錄方法

Lambda 目前支援針對下列執行階段輸出JSON結構化應用程式記錄的選項。

執行期 支援的版本
Java 除了 Amazon Linux 1 上的 Java 8 以外的所有 Java 執行期
Node.js Node.js 16 及更高版本
Python Python 3.8 及更高版本

若要讓 Lambda 以結構化JSON格式傳送函數的應用程式記錄檔，您的函數必須使用下列內建記錄工具來輸出記錄： CloudWatch

  • Java - LambdaLogger 日誌或 Log4j2。

  • Node.js - 主控台的方法 console.trace、console.debug、console.log、console.info、console.error 和 console.warn

  • Python - 標準的 Python logging 程式庫

如需關於將進階日誌控制項與支援的執行期搭配使用的詳細資訊，請參閱 記錄和監控 Java Lambda 數、記錄和監控 Node.js Lambda 數 和 記錄和監 Python Lambda 數。

對於其他受管 Lambda 執行階段，Lambda 目前僅支援以結構化JSON格式擷取系統記錄。但是，您仍然可以在任何運行時捕獲結構化JSON格式的應用程序日誌記錄，通過使用日誌記錄工具，例如 Powertools 用於 AWS Lambda 該輸出JSON格式的日誌輸出。

預設日誌格式

目前，所有 Lambda 執行期的預設日誌格式都是純文字。

如果您已經使用 Powertools 等日誌庫 AWS Lambda 來生成JSON結構化格式的函數日誌，則不需要更改代碼，如果您選擇日JSON誌格式。Lambda 不會對任何已經JSON編碼的日誌進行雙重編碼，因此函數的應用程式日誌將繼續像以前一樣被捕獲。

JSON系統記錄的格式

當您將函數的日誌格式配置為時JSON，每個系統日誌項目（平台事件）都會被捕獲為一個包含鍵值對的對JSON象，其中包含具有以下鍵的鍵值對：

  • "time" - 產生日誌訊息的時間

  • "type" - 記錄的事件類型

  • "record" - 日誌輸出的內容

"record" 值的格式會根據日誌的事件類型而有所不同。如需詳細資訊，請參閱 遙測APIEvent物件類型。如需有關指派給系統日誌事件的日誌層級的詳細資訊，請參閱 系統日誌層級事件映射。

為了進行比較，下列兩個範例會以純文字和結構化JSON格式顯示相同的記錄輸出。請注意，在大多數情況下，系統日誌事件在輸出JSON格式時包含的信息比以純文本輸出時更多。

範例 純文字：
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
範例 結構化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始終以JSON格式發出平台事件，例如START和REPORT。設定 Lambda 傳送的系統記錄檔格式 CloudWatch 不會影響 Lambda 遙測API行為。

JSON應用程式記錄的格式

當您將函數的日誌格式配置為時JSON，使用支持的日誌庫和方法寫入的應用程序日誌輸出被捕獲為一個對JSON象，其中包含具有以下鍵的鍵值對。

  • "timestamp" - 產生日誌訊息的時間

  • "level" - 指派給訊息的日誌層級

  • "message" - 日誌訊息的內容

  • "requestId" (Python 和 Node.js) 或 "AWSrequestId" (Java) - 函數調用的唯一請求 ID

根據函數使用的執行階段和記錄方法而定，此JSON物件也可能包含其他索引鍵組。例如，在 Node.js 中，如果您的函數使用console方法使用多個參數記錄錯誤對JSON象，則該對象將包含額外的鍵值對和鍵 errorMessageerrorType，和stackTrace。若要進一步了解在不同 Lambda 執行階段中JSON格式化日誌的相關資訊記錄和監 Python Lambda 數，請參閱記錄和監控 Node.js Lambda 數、和記錄和監控 Java Lambda 數。

注意

Lambda 用於時間戳記值的關鍵對於系統日誌和應用程式日誌而言不同。對於系統記錄，Lambda 會使用金鑰"time"來維持遙測的一致性API。對於應用程式日誌，Lambda 會遵循支援的執行期和使用 "timestamp" 的慣例。

為了進行比較，下列兩個範例會以純文字和結構化JSON格式顯示相同的記錄輸出。

範例 純文字：
2024-10-27T19:17:45.586Z 79b4f56e-95b1-4643-9700-2807f4e68189 INFO some log message
範例 結構化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和 UpdateFunctionConfigurationLambda API 命令、 AWS Serverless Application Model (AWS SAM):: 無伺服器:: 函數資源和:AWS: L amb da:: 函數資源來設定函數的 AWS CloudFormation AWS記錄格式。

更改函數的日誌格式不會影響存儲在日誌中的現有 CloudWatch 日誌。只有新的日誌檔會使用更新的格式。

如果您將函數的日誌格式更改為JSON且未設置日誌級別，則 Lambda 會自動將函數的應用程序日誌級別和系統日誌級別設置為INFO。這表示 Lambda 只會將層級INFO和更低層級的記錄輸出傳送至 CloudWatch 記錄。若要進一步了解應用程式和系統日誌層級篩選，請參閱 日誌層級篩選

注意

對於 Python 運行時，當函數的日誌格式設置為純文本時，默認的日誌級別設置是。WARN這表示 Lambda 只會將層級WARN和較低層級的記錄輸出傳送至 CloudWatch 記錄。將函數的日誌格式更改為JSON更改此默認行為。若要進一步了解以 Python 記錄日誌，請參閱 記錄和監 Python Lambda 數。

對於發出內嵌指標格式 (EMF) 日誌的 Node.js 函數，將函數的日誌格式更改為JSON可能導 CloudWatch 致無法識別您的指標。

重要

如果您的函數使用 Powertools in AWS Lambda (TypeScript) 或開源EMF客戶端庫發出EMF日誌，請將您的 Powertools 和EMF庫更新為最新版本，以確保 CloudWatch 可以繼續正確解析日誌。如果您切換到JSON日誌格式，我們還建議您進行測試，以確保與函數的嵌入指標的兼容性。如需有關發出EMF記錄之 node.js 函式的進一步建議，請參閱搭配結構化 JSON 日誌使用內嵌指標格式 (EMF) 用戶端程式庫。

若要設定函數的日誌格式 (主控台)

  1. 開啟 Lambda 主控台中的函數頁面。

  2. 選擇一個函數。

  3. 在函數組態頁面上，選擇監視和操作工具。

  4. 在日誌組態窗格中，選擇編輯。

  5. 在防護記錄內容下，針對記錄格式選取文字或JSON。

  6. 選擇 Save (儲存)。

若要變更現有函數的日誌格式 (AWS CLI)

  • 若要變更現有函數的記錄格式，請使用update-function-configuration指令。將 LoggingConfig 中 LogFormat 選項設定為 JSON 或 Text。

    aws lambda update-function-configuration \
  --function-name myFunction \
  --logging-config LogFormat=JSON
若要在建立函數 (AWS CLI) 時設定記錄格式

  • 若要在建立新函數時設定記錄格式，請使用 Create- function 指令中的--logging-config選項。將 LogFormat 設定為 JSON 或 Text。下列範例命令會建立 Node.js 函數，以結構化方式輸出記錄檔JSON。

    如果您在建立函數時未指定日誌格式，Lambda 會針對您選取的執行期版本使用預設日誌格式。如需有關預設記錄格式的資訊，請參閱 預設日誌格式。

    aws lambda create-function \ 
  --function-name myFunction \ 
  --runtime nodejs20.x \
  --handler index.handler \
  --zip-file fileb://function.zip \
  --role arn:aws:iam::123456789012:role/LambdaRole \
  --logging-config LogFormat=JSON

日誌層級篩選

Lambda 可以篩選函數的記錄，以便只將特定詳細資料層級或更低層級的記錄傳送至 CloudWatch 記錄。您可以針對函數的系統日誌 (Lambda 產生的日誌) 和應用程式日誌 (函數程式碼產生的日誌) 分別設定日誌層級篩選。

對於 支援的執行期和記錄方法，您無需對函數程式碼進行任何變更，Lambda 即可篩選函數的應用程式日誌。

對於所有其他執行階段和記錄方法，您的函數程式碼必須將記錄事件輸出至包含索引鍵值配對的JSON格式化物件，stdout或將記錄事件輸出stderr為包含索引鍵"level"值 例如，Lambda 會將下列輸出解譯stdout為DEBUG層級記錄。

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

如果"level"值欄位無效或遺失，Lambda 會將記錄輸出指派層級INFO。若要讓 Lambda 使用時間戳記欄位，您必須以有效的 RFC3339 時間戳記格式指定時間。如果您沒有提供有效的時間戳記，Lambda 會為記錄指派層級，INFO並為您新增時間戳記。

命名時間戳記索引鍵時，請遵循您使用的執行期慣例。Lambda 支援受管理執行期使用的大多數通用命名慣例。例如，在使用. NET運行時，Lambda 識別密鑰"Timestamp"。

注意

若要使用記錄層級篩選，您的函數必須設定為使用記JSON錄格式。所有 Lambda 受管執行期的預設日誌格式目前都是純文字。若要瞭解如何將函數的記錄格式設定為JSON，請參閱設定函數的日誌格式。

對於應用程式日誌 (由函數程式碼生成的日誌)，您可以在以下日誌層級之間進行選擇。

日誌層級 標準用量
TRACE（最詳細） 用於追蹤程式碼執行路徑的最精細資訊
DEBUG 系統偵錯的詳細資訊
INFO 記錄函數正常操作的訊息
WARN 有關可能導致未解決意外行為的潛在錯誤的消息
ERROR 有關阻止程式碼按預期執行的問題的訊息
FATAL(最少細節) 有關導致應用程式停止運作的嚴重錯誤訊息

當您選取記錄層級時，Lambda 會將該層級或更低層級的記錄傳送至 CloudWatch 記錄檔。例如，如果您將函數的應用程式記錄層級設定為WARN，Lambda 不會在INFO和層DEBUG級傳送記錄輸出。防護記錄篩選的預設應用程式記錄層級為INFO。

當 Lambda 篩選函數的應用程式記錄時，系統會將無層級的記錄訊息指派給記錄層級INFO。

對於系統日誌檔 (Lambda 服務產生的日誌檔)，您可以在下列日誌層級進行選擇。

日誌層級 用量
DEBUG（最詳細） 系統偵錯的詳細資訊
INFO 記錄函數正常操作的訊息
WARN(最少細節) 有關可能導致未解決意外行為的潛在錯誤的消息

當您選取日誌層級時，Lambda 會在該層級 (含) 或更低層級傳送日誌。例如，如果您將函數的系統日誌級別設置為INFO，Lambda 不會在該DEBUG級別發送日誌輸出。

根據預設，Lambda 會將系統記錄層級設定為INFO。透過此設定，Lambda 會自動將訊息傳送"start"並"report"記錄到 CloudWatch。若要接收或多或少詳細的系統記錄，請將記錄層級變更為DEBUG或WARN。若要查看 Lambda 映射不同系統日誌事件的記錄層級清單，請參閱 系統日誌層級事件映射。

設定日誌層級篩選

若要為您的函數設定應用程式和系統記錄層級篩選，您可以使用 Lambda 主控台或 AWS Command Line Interface (AWS CLI)。您也可以使用CreateFunction和 UpdateFunctionConfigurationLambda API 命令、 AWS Serverless Application Model (AWS SAM):: 無伺服器:: 函數資源和:AWS: L amb da:: 函數資源來設定函數的 AWS CloudFormation AWS記錄層級。

請注意，如果您在程式碼中設定函數的日誌層級，此設定會優先於您的任何其他日誌層級設定。例如，如果您使用 Python logging setLevel() 方法將函數的記錄層級設定為INFO，則此設定優先於您使用 Lambda 主控台設定的設定。WARN

若要設定現有函數的應用程式或系統日誌層級 (主控台)

  1. 開啟 Lambda 主控台中的 函數頁面。

  2. 選擇一個函數。

  3. 在函數組態頁面上，選擇監視和操作工具。

  4. 在日誌組態窗格中，選擇編輯。

  5. 在 [防護記錄內容] 下，針對 [記錄格式]，請確JSON定

  6. 使用選項按鈕，為您的函數選擇所需的應用程式日誌層級和系統日誌層級。

  7. 選擇 Save (儲存)。

若要設定現有函數的應用程式或系統日誌層級 (AWS CLI)

  • 若要變更現有函數的應用程式或系統記錄層級，請使用update-function-configuration指令。設定 --system-log-level 為 DEBUG、INFO 或 WARN 之一。設定 --application-log-level 為 DEBUG、INFO、WARN、ERROR 或 FATAL 之一。

    aws lambda update-function-configuration \
  --function-name myFunction \
  --system-log-level WARN \
  --application-log-level ERROR
若要在建立函數時設定日誌層級篩選

  • 若要在建立新函數時設定記錄層級篩選，請使用 create-function 命令中的--system-log-level和--application-log-level選項。設定 --system-log-level 為 DEBUG、INFO 或 WARN 之一。設定 --application-log-level 為 DEBUG、INFO、WARN、WARN 或 FATAL 之一。

    aws lambda create-function \
  --function-name myFunction \
  --runtime nodejs20.x \
  --handler index.handler \
  --zip-file fileb://function.zip \
  --role arn:aws:iam::123456789012:role/LambdaRole \ 
  --system-log-level WARN \
  --application-log-level ERROR

系統日誌層級事件映射

對於 Lambda 產生的系統層級日誌事件，以下資料表定義指派給每個事件的日誌層級。若要進一步瞭解資料表中所列事件，請參閱 遙 Lambda API Event 結構描述參考

事件名稱 條件 指派的日誌層級
initStart runtimeVersion 被設置 INFO
initStart runtimeVersion 未設定 DEBUG
initRuntimeDone status=success DEBUG
initRuntimeDone status!=success WARN
initReport initializationType= 快照啟動 INFO
initReport initializationType! = 快照啟動 DEBUG
initReport status!=success WARN
restoreStart runtimeVersion 被設置 INFO
restoreStart runtimeVersion 未設定 DEBUG
restoreRuntimeDone status=success DEBUG
restoreRuntimeDone status!=success WARN
restoreReport status=success INFO
restoreReport status!=success WARN
入門 - INFO
runtimeDone status=success DEBUG
runtimeDone status!=success WARN
報告 status=success INFO
報告 status!=success WARN
副檔名 state=success INFO
副檔名 state!=success WARN
logSubscription - INFO
telemetrySubscription - INFO
logsDropped - WARN
注意

使用遙測存取擴充功能的即時遙測資料 API 始終發出一組完整的平台事件。設定 Lambda 傳送的系統記錄層級 CloudWatch 不會影響 Lambda 遙測API行為。

使用自訂執行期的應用程式日誌層級篩選

當您為函數設定應用程式日誌層級篩選時，Lambda 會在幕後使用 AWS_LAMBDA_LOG_LEVEL 環境變數在執行期設定應用程式日誌層級。Lambda 也會使用 AWS_LAMBDA_LOG_FORMAT 環境變數來設定函數的日誌格式。您可以使用這些變數，將 Lambda 進階日誌控制項整合至自訂執行期。

若要透過 Lambda 主控台和 Lambda 使用自訂執行階段來設定函數的記錄設定 AWS CLI，請設定您的自訂執行階段以檢查這些環境變數的值。APIs然後，您可以根據您選取的日誌格式和日誌層級來設定執行期的日誌程式。

設定 CloudWatch 記錄群組

根據預設， CloudWatch 會在第一次叫用函數時自動建立/aws/lambda/<function name>為函數命名的記錄群組。若要將函數設定為將日誌傳送到現有的日誌群組，或為您的函數建立新的日誌群組，您可以使用 Lambda 主控台或 AWS CLI. 您也可以使用CreateFunction和 UpdateFunctionConfigurationLambda API 命令和 AWS Serverless Application Model (AWS SAM):: 無伺服器:AWS: 函數資源來設定自訂記錄群組。

您可以設定多個 Lambda 函數，將記錄傳送至相同的記 CloudWatch 錄群組。例如，您可以使用單一日誌群組來儲存組成特定應用程式之所有 Lambda 函數的記錄。當您針對 Lambda 函數使用自訂日誌群組時，Lambda 建立的日誌串流會包含函數名稱和函數版本。如此可確保日誌訊息和函數之間的映射會被保留，即使您對多個函數使用相同的日誌群組也是如此。

自訂記錄群組的記錄資料流命名格式遵循下列慣例：

YYYY/MM/DD/<function_name>[<function_version>][<execution_environment_GUID>]

請注意，設定自訂記錄群組時，您為記錄群組選取的名稱必須遵循CloudWatch 記錄檔命名規則。此外，自訂日誌群組名稱不得以字串 aws/ 開頭。如果您以 aws/ 開頭建立自訂日誌群組，Lambda 將無法建立日誌群組。因此，您的函數的日誌將不會發送到 CloudWatch。

若要變更函數的日誌群組 (主控台)

  1. 開啟 Lambda 主控台中的 函數頁面。

  2. 選擇一個函數。

  3. 在函數組態頁面上，選擇監視和操作工具。

  4. 在日誌組態窗格中，選擇編輯。

  5. 在 [記錄群組] 窗格中，對於記CloudWatch 錄群組，選擇 [自訂]。

  6. 在 [自訂記錄群組] 下，輸入您希望函數傳送記錄的目標記錄群組名稱。 CloudWatch 如果您輸入現有日誌群組的名稱，則您的函數將使用該群組。如果沒有具有您輸入名稱的日誌群組，則 Lambda 會以該名稱為您的函數建立新的日誌群組。

若要變更函數的日誌群組 (AWS CLI)

  • 若要變更現有函數的記錄群組，請使用update-function-configuration指令。

    aws lambda update-function-configuration \
  --function-name myFunction \
  --logging-config LogGroup=myLogGroup
若要在建立函數 (AWS CLI) 時指定自訂日誌群組

  • 若要在使用建立新 Lambda 函數時指定自訂記錄群組 AWS CLI，請使用--logging-config選項。下列範例命令會建立 Node.js Lambda 函數，該函數會將日誌檔傳送至名為 myLogGroup 的日誌群組。

    aws lambda create-function \
  --function-name myFunction \
  --runtime nodejs20.x \
  --handler index.handler \
  --zip-file fileb://function.zip \
  --role arn:aws:iam::123456789012:role/LambdaRole \
  --logging-config LogGroup=myLogGroup

執行角色許可

為了讓您的功能將日誌發送到 CloudWatch 日誌，它必須具有 logs：PutLogEvents權限。使用 Lambda 主控台設定函數的日誌群組時，如果函數沒有此許可，Lambda 預設會將其新增至函數的執行角色。Lambda 新增此權限時，會授予函數將記錄傳送至任何日誌 CloudWatch 記錄群組的權限。

若要防止 Lambda 自動更新函數的執行角色並改為手動編輯，請展開許可，然後取消勾選新增所需許可。

使用設定函數的日誌群組時 AWS CLI，Lambda 不會自動新增logs:PutLogEvents權限。如果函數的執行角色尚不具備許可，請將其新增至函數的執行角色。此權限包含在AWSLambdaBasicExecutionRole受管理的策略中。