本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用遙測 API 即時存取延伸功能的遙測資料 遙測 API 可讓您的延伸項目直接從 Lambda 接收遙測資料。在函數初始化和調用期間，Lambda 會自動擷取遙測資料，包括日誌、平台指標和平台追蹤。遙測 API 使延伸項目可以近乎即時地從 Lambda 直接存取這些遙測資料。 在 Lambda 執行環境中，您可以讓 Lambda 延伸項目訂閱遙測串流。訂閱後，Lambda 會自動將所有遙測資料傳送至您的延伸項目。隨後，您便能靈活地處理、篩選資料，並將資料傳送至偏好的目的地，例如 Amazon Simple Storage Service (Amazon S3) 儲存貯體或第三方可觀測性工具提供者。 下圖顯示延伸 API 和遙測 API 如何從執行環境中將延伸項目連結至 Lambda。另外，執行期 API 也會將執行期和函數連接至 Lambda。 ![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/telemetry-api-concept-diagram.png) **重要** Lambda 遙測 API 優先於 Lambda 日誌 API。**雖然日誌 API 仍然正常運作，但我們建議您未來只使用遙測 API。**您可以使用遙測 API 或日誌 API 訂閱遙測串流的延伸項目。使用其中一個 API 進行訂閱後，若嘗試使用其他 API 進行任何訂閱，都會傳回錯誤。 **Lambda 受管執行個體結構描述版本需求** Lambda 受管執行個體僅支援遙測 API `2025-01-29` 的結構描述版本。訂閱受管執行個體函數的遙測串流時，**您必須在**訂閱請求`"schemaVersion": "2025-01-29"`中使用 。使用先前的結構描述版本會導致 Lambda 拒絕事件。 `2025-01-29` 結構描述版本回溯相容，可與 Lambda 受管執行個體和 Lambda （預設） 函數搭配使用。我們建議將此版本用於所有新的延伸，以確保兩種部署模型的相容性。 延伸項目可使用遙測 API 來訂閱三個不同的遙測串流： + **平台遙測** – 日誌、指標和追蹤，描述與執行環境執行階段生命週期、延伸項目生命週期和函數調用相關的事件和錯誤。 + **函數日誌** – Lambda 函數程式碼產生的自訂日誌。 + **延伸項目日誌** - Lambda 延伸項目程式碼產生的自訂日誌。 **注意** Lambda 會將日誌和指標傳送到 CloudWatch，並將追蹤傳送至 X-Ray (如果您已啟動追蹤)，即使延伸項目有訂閱遙測串流也一樣。 **Topics** + [ ## 使用遙測 API 建立延伸項目 ](#telemetry-api-creating-extensions) + [ ## 註冊延伸項目 ](#telemetry-api-registration) + [ ## 建立遙測接聽程式 ](#telemetry-api-listener) + [ ## 指定目的地通訊協定 ](#telemetry-api-destination) + [ ## 設定記憶體使用量和緩衝 ](#telemetry-api-buffering) + [ ## 將訂閱請求傳送至遙測 API ](#telemetry-api-subscription) + [ ## 輸入遙測 API 訊息 ](#telemetry-api-messages) + [ # Lambda 遙測 API 參考 ](telemetry-api-reference.md) + [ # Lambda 遙測 API `Event` 結構描述參考 ](telemetry-schema-reference.md) + [ # 將 Lambda 遙測 API`Event` 物件轉換為 OpenTelemetry 跨度 ](telemetry-otel-spans.md) + [ # 使用 Lambda Logs API ](runtimes-logs-api.md) ## 使用遙測 API 建立延伸項目 Lambda 延伸項目會在執行環境中做為獨立的程序執行。延伸項目可以在函數調用完成後繼續執行。由於延伸項目為獨立的處理序，因此您可以使用與函數程式碼不同的語言來撰寫。我們建議您使用 Golang 或 Rust 等編譯語言編寫延伸項目。在這種情況下，延伸項目是獨立的二進位檔案，且與任何支援的執行階段相容。 下圖說明建立延伸項目的四步驟程序，讓延伸項目使用遙測 API 接收和處理遙測資料。 ![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/telemetry-api-creation-steps.png) 以下是各步驟的詳細說明： 1. 使用 [使用 Lambda 延伸 API 來建立延伸項目](runtimes-extensions-api.md) 註冊延伸項目。這會為您提供 `Lambda-Extension-Identifier`，接著需要在下列步驟中使用。如需有關如何註冊延伸項目的詳細資訊，請參閱：[註冊延伸項目](#telemetry-api-registration)。 1. 建立遙測接聽程式。這可以是基本的 HTTP 或 TCP 伺服器。Lambda 使用遙測接聽程式的 URI 來將遙測資料傳送至延伸項目。如需詳細資訊，請參閱[建立遙測接聽程式](#telemetry-api-listener)。 1. 使用遙測 API 中的訂閱 API，為您的延伸項目訂閱需要的遙測串流。在此步驟中，您需要遙測接聽程式的 URI。如需詳細資訊，請參閱[將訂閱請求傳送至遙測 API](#telemetry-api-subscription)。 1. 透過遙測接聽程式從 Lambda 取得遙測資料。您可以對這些資料執行任何自訂處理，例如將資料分派到 Amazon S3 或外部可檢視性服務。 **注意** Lambda 函數的執行環境可以在其[生命週期](runtimes-extensions-api.md#runtimes-extensions-api-lifecycle)中多次啟動和停止。一般來說，延伸項目程式碼會在函數調用期間執行，並且在關閉階段執行最多 2 秒。我們建議在遙測傳送到您的接聽程式時進行批次處理。然後，使用 `Invoke` 和 `Shutdown` 生命週期事件將每個批次傳送到所需的目的地。 ## 註冊延伸項目 您必須先註冊 Lambda 延伸項目，才能訂閱遙測資料。註冊會在[延伸功能初始化階段](runtimes-extensions-api.md#runtimes-extensions-api-reg)進行。下列範例顯示註冊延伸項目的 HTTP 請求。 ``` POST http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register Lambda-Extension-Name: lambda_extension_name { 'events': [ 'INVOKE', 'SHUTDOWN'] } ``` 如果請求成功，訂閱者會收到 HTTP 200 成功回應。回應標頭包含 `Lambda-Extension-Identifier`。回應內文包含函數的其他屬性。 ``` HTTP/1.1 200 OK Lambda-Extension-Identifier: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 { "functionName": "lambda_function", "functionVersion": "$LATEST", "handler": "lambda_handler", "accountId": "123456789012" } ``` 如需更多資訊，請參閱[Extensions API 參考](runtimes-extensions-api.md#runtimes-extensions-registration-api)。 ## 建立遙測接聽程式 Lambda 延伸項目必須具有可處理遙測 API 所傳入請求的接聽程式。下列程式碼顯示以 Golang 實作的遙測接聽程式實作範例： ``` // Starts the server in a goroutine where the log events will be sent func (s *TelemetryApiListener) Start() (string, error) { address := listenOnAddress() l.Info("[listener:Start] Starting on address", address) s.httpServer = &http.Server{Addr: address} http.HandleFunc("/", s.http_handler) go func() { err := s.httpServer.ListenAndServe() if err != http.ErrServerClosed { l.Error("[listener:goroutine] Unexpected stop on Http Server:", err) s.Shutdown() } else { l.Info("[listener:goroutine] Http Server closed:", err) } }() return fmt.Sprintf("http://%s/", address), nil } // http_handler handles the requests coming from the Telemetry API. // Everytime Telemetry API sends log events, this function will read them from the response body // and put into a synchronous queue to be dispatched later. // Logging or printing besides the error cases below is not recommended if you have subscribed to // receive extension logs. Otherwise, logging here will cause Telemetry API to send new logs for // the printed lines which may create an infinite loop. func (s *TelemetryApiListener) http_handler(w http.ResponseWriter, r *http.Request) { body, err := ioutil.ReadAll(r.Body) if err != nil { l.Error("[listener:http_handler] Error reading body:", err) return } // Parse and put the log messages into the queue var slice []interface{} _ = json.Unmarshal(body, &slice) for _, el := range slice { s.LogEventsQueue.Put(el) } l.Info("[listener:http_handler] logEvents received:", len(slice), " LogEventsQueue length:", s.LogEventsQueue.Len()) slice = nil } ``` ## 指定目的地通訊協定 使用遙測 API 訂閱以接收遙測資料時，除了目的地 URI 之外，您還可以指定目的地通訊協定： ``` { "destination": { "protocol": "HTTP", "URI": "http://sandbox.localdomain:8080" } } ``` Lambda 接受兩種通訊協定用於接收遙測資料： + **HTTP (建議)** - Lambda 會以 JSON 格式的記錄陣列將遙測資料傳遞至本機 HTTP 端點 (`http://sandbox.localdomain:${PORT}/${PATH}`)。`$PATH` 為選用參數。Lambda 僅支援 HTTP，不支援 HTTPS。Lambda 會透過 POST 請求傳遞遙測資料。 + **TCP** - Lambda 使用[以換行分隔的 JSON (NDJSON) 格式](https://github.com/ndjson/ndjson-spec)將遙測資料傳遞至 TCP 連接埠。 **注意** 強烈建議使用 HTTP，而不是使用 TCP。若使用 TCP，Lambda 平台無法確認何時將遙測資料傳遞至應用程式層。因此，如果您的延伸項目損毀，遙測資料可能會遺失。HTTP 沒有此限制。 訂閱以接收遙測資料之前，需先建立本機 HTTP 接聽程式或 TCP 連接埠。在設定期間，請注意下列事項： + Lambda 只會將遙測資料傳送至執行環境內的目的地。 + 如果沒有接聽程式，或者如果 POST 請求遇到錯誤，則 Lambda 會重新嘗試傳送遙測資料 (使用回詢)。如果遙測接聽程式損毀，會在 Lambda 重新啟動執行環境之後繼續接收遙測資料。 + Lambda 保留連接埠 9001。沒有其他連接埠編號限制或建議。 ## 設定記憶體使用量和緩衝 隨著訂閱用戶數量增加，執行環境的記憶體使用量會線性增加。訂閱會耗用記憶體資源，因為每個訂閱都會開啟新的記憶體緩衝區來存放遙測資料。緩衝區記憶體用量會計入執行環境中的整體記憶體耗用量。 透過遙測 API 來訂閱以接收遙測資料時，您可以選擇先緩衝遙測資料再批次傳遞給訂閱用戶。若要最佳化記憶體用量，您可以指定緩衝組態： ``` { "buffering": { "maxBytes": 256*1024, "maxItems": 1000, "timeoutMs": 100 } } ``` | 參數 | Description | 預設值和限制 | | --- | --- | --- | | `maxBytes` | 記憶體中要緩衝的遙測資料量上限 (位元組)。 | 預設：262,144 下限：262,144 上限：1,048,576 | | `maxItems` | 記憶體中要緩衝的事件數目上限。 | 預設：10,000 下限：1,000 上限：10,000 | | `timeoutMs` | 緩衝一個批次的時間上限 (毫秒)。 | 預設：1,000 下限：25 上限：30,000 | 當設定緩衝時，請記住以下幾點： + 如果有任何輸入串流關閉，則 Lambda 會排清日誌。例如，如果執行期損毀，就可能會發生這種情況。 + 每個訂閱用戶可以在訂閱請求中自訂其緩衝組態。 + 決定讀取資料的緩衝區大小時，請預期接收的有效負載大小為 `2 * maxBytes + metadataBytes` (其中 `maxBytes` 是緩衝設定的元件)。若要評估要考量的 `metadataBytes` 數量，請檢閱下列中繼資料。Lambda 會將類似的中繼資料新增至每筆記錄： ``` { "time": "2022-08-20T12:31:32.123Z", "type": "function", "record": "Hello World" } ``` + 如果訂閱者處理傳入遙測資料的速度不夠快，或是函數程式碼產生了極大量的日誌，Lambda 可能會捨棄記錄，以確保記憶體使用率維持在限制範圍內。發生這種情況時，Lambda 會傳送 `platform.logsDropped` 事件。 ## 將訂閱請求傳送至遙測 API Lambda 延伸項目可透過將訂閱請求傳送至遙測 API 來訂閱以接收遙測資料。訂閱請求應包含您希望延伸項目訂閱的事件類型相關資訊。此外，請求可以包含[傳遞目的地資訊](#telemetry-api-destination)和[緩衝組態](#telemetry-api-buffering)。 傳送訂閱請求之前，您必須有延伸功能 ID (`Lambda-Extension-Identifier`)。[向延伸 API 註冊您的延伸項目](#telemetry-api-registration)時，您可從 API 回應中取得延伸項目 ID。 訂閱會在[延伸項目初始化階段](runtimes-extensions-api.md#runtimes-extensions-api-reg)進行。下列範例顯示訂閱全部三個遙測串流的 HTTP 請求：平台遙測、函數日誌和延伸項目日誌。 ``` PUT http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry HTTP/1.1 { "schemaVersion": "2025-01-29", "types": [ "platform", "function", "extension" ], "buffering": { "maxItems": 1000, "maxBytes": 256*1024, "timeoutMs": 100 }, "destination": { "protocol": "HTTP", "URI": "http://sandbox.localdomain:8080" } } ``` 如果請求成功，訂閱者會收到 HTTP 200 成功回應。 ``` HTTP/1.1 200 OK "OK" ``` ## 輸入遙測 API 訊息 使用遙測 API 訂閱之後，延伸項目會自動透過 POST 請求開始接收來自 Lambda 的遙測資料。每個 POST 請求主體包含 `Event` 對象的數組。每個 `Event` 項目都有以下結構描述： ``` { time: String, type: String, record: Object } ``` + `time` 屬性定義了 Lambda 平台產生事件的時間。這與事件實際發生的時間不同。`time` 的字串值是 ISO 8601 格式的時間戳記。 + `type` 屬性定義了事件類型。下表說明所有可能的值。 + `record` 屬性定義了包含遙測資料的 JSON 物件。此 JSON 物件的結構描述取決於 `type`。 **使用並行調用的事件排序** 對於 [Lambda 受管執行個體](lambda-managed-instances.md)，多個函數調用可以在相同的執行環境中同時執行。在此情況下，不同並行調用之間無法保證 `platform.start`和 `platform.report`事件的順序。延伸模組必須處理平行執行的多個調用的事件，不應採用循序排序。 為了將事件適當地歸因於特定調用，延伸模組應使用這些平台事件中存在`requestId`的欄位。每個調用都有唯一的請求 ID，該請求 ID 在該調用的所有事件中都保持一致，允許延伸項目即使在不按順序到達時也能正確地關聯事件。 下表摘要說明 `Event` 物件的所有類型，以及每個事件類型之[遙測 API `Event` 結構描述參考](telemetry-schema-reference.md)的連結。 | Category | 事件類型 | Description | 事件記錄結構描述 | | --- | --- | --- | --- | | 平台事件 | `platform.initStart` | 函數初始化已開始。 | [`platform.initStart`](telemetry-schema-reference.md#platform-initStart) 結構描述 | | 平台事件 | `platform.initRuntimeDone` | 函數初始化已完成。 | [`platform.initRuntimeDone`](telemetry-schema-reference.md#platform-initRuntimeDone) 結構描述 | | 平台事件 | `platform.initReport` | 函數初始化報告。 | [`platform.initReport`](telemetry-schema-reference.md#platform-initReport) 結構描述 | | 平台事件 | `platform.start` | 函數調用已開始。 | [`platform.start`](telemetry-schema-reference.md#platform-start) 結構描述 | | 平台事件 | `platform.runtimeDone` | 執行階段已完成處理的事件，結果為成功或失敗。 | [`platform.runtimeDone`](telemetry-schema-reference.md#platform-runtimeDone) 結構描述 | | 平台事件 | `platform.report` | 函數調用報告。 | [`platform.report`](telemetry-schema-reference.md#platform-report) 結構描述 | | 平台事件 | `platform.restoreStart` | 執行時間還原已開始。 | [`platform.restoreStart`](telemetry-schema-reference.md#platform-restoreStart) 結構描述 | | 平台事件 | `platform.restoreRuntimeDone` | 執行時間還原已完成。 | [`platform.restoreRuntimeDone`](telemetry-schema-reference.md#platform-restoreRuntimeDone) 結構描述 | | 平台事件 | `platform.restoreReport` | 執行時間還原報告。 | [`platform.restoreReport`](telemetry-schema-reference.md#platform-restoreReport) 結構描述 | | 平台事件 | `platform.telemetrySubscription` | 延伸項目已訂閱遙測 API。 | [`platform.telemetrySubscription`](telemetry-schema-reference.md#platform-telemetrySubscription) 結構描述 | | 平台事件 | `platform.logsDropped` | Lambda 已捨棄日誌項目。 | [`platform.logsDropped`](telemetry-schema-reference.md#platform-logsDropped) 結構描述 | | 函數日誌 | `function` | 函數程式碼的日誌行。 | [`function`](telemetry-schema-reference.md#telemetry-api-function) 結構描述 | | 延伸項目日誌 | `extension` | 延伸項目程式碼的日誌行。 | [`extension`](telemetry-schema-reference.md#telemetry-api-extension) 結構描述 | # Lambda 遙測 API 參考 使用 Lambda 遙測 API 端點來讓延伸項目訂閱遙測串流。您可以從 `AWS_LAMBDA_RUNTIME_API` 環境變數中擷取遙測 API 端點。若要傳送 API 請求，請附加 API 版本 (`2022-07-01/`) 和`telemetry/`。例如： ``` http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry/ ``` 如需訂閱回應版本 `2025-01-29` 的 OpenAPI 規格 (OAS) 定義，請參閱： + **HTTP** – [telemetry-api-http-schema.zip](samples/events_http_schema_v2025_01_29.zip) + **TCP** – [telemetry-api-tcp-schema.zip](samples/events_tcp_schema_v2025_01_29.zip) **Topics** + [ ## 訂閱 ](#telemetry-subscribe-api) ## 訂閱 若要訂閱遙測串流，Lambda 延伸項目可以傳送訂閱 API 請求。 + **路徑** – `/telemetry` + **Method** – `PUT` + **標頭** + `Content-Type`: `application/json` + **請求內文參數** + **schemaVersion** + 必要：是 + 類型：字串 + 有效值：`"2025-01-29"`、`"2022-12-13"` 或 `"2022-07-01"` + **注意：**Lambda 受管執行個體需要 `"2025-01-29"`。此版本與 Lambda （預設） 函數回溯相容。 + **destination** – 定義遙測事件目的地和事件傳遞通訊協定的組態設定。 + 必要：是 + 類型：物件 ``` { "protocol": "HTTP", "URI": "http://sandbox.localdomain:8080" } ``` + **protocol** – Lambda 用來傳送遙測資料的通訊協定。 + 必要：是 + 類型：字串 + 有效值：`"HTTP"`\$1`"TCP"` + **URI** – 要傳送遙測資料的目的地 URI。 + 必要：是 + 類型：字串 + 如需詳細資訊，請參閱[指定目的地通訊協定](telemetry-api.md#telemetry-api-destination)。 + **types** – 您希望延伸項目訂閱的遙測類型。 + 必要：是 + 類型：字串陣列 + 有效值：`"platform"`\$1`"function"`\$1`"extension"` + **buffering** – 事件緩衝的組態設定。 + 必要：否 + 類型：物件 ``` { "buffering": { "maxItems": 1000, "maxBytes": 256*1024, "timeoutMs": 100 } } ``` + **maxItems** – 記憶體中要緩衝的事件數目上限。 + 必要：否 + 類型：整數 + 預設：1,000 + 下限：1,000 + 上限：10,000 + **maxBytes** – 記憶體中要緩衝的遙測資料量上限 (位元組)。 + 必要：否 + 類型：整數 + 預設：262,144 + 下限：262,144 + 上限：1,048,576 + **timeoutMs** - 緩衝批次處理的時間上限 (毫秒)。 + 必要：否 + 類型：整數 + 預設：1,000 + 下限：25 + 上限：30,000 + 如需詳細資訊，請參閱[設定記憶體使用量和緩衝](telemetry-api.md#telemetry-api-buffering)。 ### 訂閱 API 請求範例 ``` PUT http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry HTTP/1.1 { "schemaVersion": "2025-01-29", "types": [ "platform", "function", "extension" ], "buffering": { "maxItems": 1000, "maxBytes": 256*1024, "timeoutMs": 100 }, "destination": { "protocol": "HTTP", "URI": "http://sandbox.localdomain:8080" } } ``` 如果請求成功，延伸項目會收到 HTTP 200 成功回應： ``` HTTP/1.1 200 OK "OK" ``` 如果訂閱請求失敗，延伸項目會收到錯誤回應。例如： ``` HTTP/1.1 400 OK { "errorType": "ValidationError", "errorMessage": "URI port is not provided; types should not be empty" } ``` 以下是延伸項目可能收到的其他幾個回應代碼： + 200 - 請求已成功完成 + 202 - 已接受請求。本機測試環境中的訂閱請求回應 + 400 - 錯誤的請求 + 500 - 服務錯誤 # Lambda 遙測 API `Event` 結構描述參考 使用 Lambda 遙測 API 端點來讓延伸項目訂閱遙測串流。您可以從 `AWS_LAMBDA_RUNTIME_API` 環境變數中擷取遙測 API 端點。若要傳送 API 請求，請附加 API 版本 (`2022-07-01/`) 和`telemetry/`。例如： ``` http://${AWS_LAMBDA_RUNTIME_API}/2022-07-01/telemetry/ ``` 如需訂閱回應版本 `2025-01-29` 的 OpenAPI 規格 (OAS) 定義，請參閱： + **HTTP** – [telemetry-api-http-schema.zip](samples/events_http_schema_v2025_01_29.zip) + **TCP** – [telemetry-api-tcp-schema.zip](samples/events_tcp_schema_v2025_01_29.zip) 下表摘要說明遙測 API 支援的所有 `Event` 物件類型。 | Category | 事件類型 | Description | 事件記錄結構描述 | | --- | --- | --- | --- | | 平台事件 | `platform.initStart` | 函數初始化已開始。 | [`platform.initStart`](#platform-initStart) 結構描述 | | 平台事件 | `platform.initRuntimeDone` | 函數初始化已完成。 | [`platform.initRuntimeDone`](#platform-initRuntimeDone) 結構描述 | | 平台事件 | `platform.initReport` | 函數初始化報告。 | [`platform.initReport`](#platform-initReport) 結構描述 | | 平台事件 | `platform.start` | 函數調用已開始。 | [`platform.start`](#platform-start) 結構描述 | | 平台事件 | `platform.runtimeDone` | 執行階段已完成處理的事件，結果為成功或失敗。 | [`platform.runtimeDone`](#platform-runtimeDone) 結構描述 | | 平台事件 | `platform.report` | 函數調用報告。 | [`platform.report`](#platform-report) 結構描述 | | 平台事件 | `platform.restoreStart` | 執行時間還原已開始。 | [`platform.restoreStart`](#platform-restoreStart) 結構描述 | | 平台事件 | `platform.restoreRuntimeDone` | 執行時間還原已完成。 | [`platform.restoreRuntimeDone`](#platform-restoreRuntimeDone) 結構描述 | | 平台事件 | `platform.restoreReport` | 執行時間還原報告。 | [`platform.restoreReport`](#platform-restoreReport) 結構描述 | | 平台事件 | `platform.telemetrySubscription` | 延伸項目已訂閱遙測 API。 | [`platform.telemetrySubscription`](#platform-telemetrySubscription) 結構描述 | | 平台事件 | `platform.logsDropped` | Lambda 已捨棄日誌項目。 | [`platform.logsDropped`](#platform-logsDropped) 結構描述 | | 函數日誌 | `function` | 函數程式碼的日誌行。 | [`function`](#telemetry-api-function) 結構描述 | | 延伸項目日誌 | `extension` | 延伸項目程式碼的日誌行。 | [`extension`](#telemetry-api-extension) 結構描述 | **Contents** + [ ## 遙測 API `Event` 物件類型 ](#telemetry-api-events) + [ ### `platform.initStart` ](#platform-initStart) + [ ### `platform.initRuntimeDone` ](#platform-initRuntimeDone) + [ ### `platform.initReport` ](#platform-initReport) + [ ### `platform.start` ](#platform-start) + [ ### `platform.runtimeDone` ](#platform-runtimeDone) + [ ### `platform.report` ](#platform-report) + [ ### `platform.restoreStart` ](#platform-restoreStart) + [ ### `platform.restoreRuntimeDone` ](#platform-restoreRuntimeDone) + [ ### `platform.restoreReport` ](#platform-restoreReport) + [ ### `platform.extension` ](#platform-extension) + [ ### `platform.telemetrySubscription` ](#platform-telemetrySubscription) + [ ### `platform.logsDropped` ](#platform-logsDropped) + [ ### `function` ](#telemetry-api-function) + [ ### `extension` ](#telemetry-api-extension) + [ ## 共用物件類型 ](#telemetry-api-objects) + [ ### `InitPhase` ](#InitPhase) + [ ### `InitReportMetrics` ](#InitReportMetrics) + [ ### `InitType` ](#InitType) + [ ### `ReportMetrics` ](#ReportMetrics) + [ ### `RestoreReportMetrics` ](#RestoreReportMetrics) + [ ### `RuntimeDoneMetrics` ](#RuntimeDoneMetrics) + [ ### `Span` ](#Span) + [ ### `Status` ](#Status) + [ ### `TraceContext` ](#TraceContext) + [ ### `TracingType` ](#TracingType) ## 遙測 API `Event` 物件類型 本節詳細說明 Lambda 遙測 API 支援的 `Event` 物件類型。在事件描述中，問號 (`?`) 表示該屬性可能不存在於物件中。 ### `platform.initStart` `platform.initStart` 事件表示函數初始化階段已開始。`platform.initStart` `Event` 物件的結構如下： ``` Event: Object - time: String - type: String = platform.initStart - record: PlatformInitStart ``` `PlatformInitStart` 物件具有下列屬性： + **functionName** – `String` + **functionVersion** – `String` + **initializationType** – ``InitType`` 物件 + **instanceId?** – `String` + **instanceMaxMemory?** – `Integer` + **phase** – ``InitPhase`` 物件 + **runtimeVersion?** – `String` + **runtimeVersionArn?** – `String` 以下是 `platform.initStart` 類型 `Event` 的範例： ``` { "time": "2022-10-12T00:00:15.064Z", "type": "platform.initStart", "record": { "initializationType": "on-demand", "phase": "init", "runtimeVersion": "nodejs-14.v3", "runtimeVersionArn": "arn", "functionName": "myFunction", "functionVersion": "$LATEST", "instanceId": "82561ce0-53dd-47d1-90e0-c8f5e063e62e", "instanceMaxMemory": 256 } } ``` ### `platform.initRuntimeDone` `platform.initRuntimeDone` 事件表示函數初始化階段已完成。`platform.initRuntimeDone` `Event` 物件的結構如下： ``` Event: Object - time: String - type: String = platform.initRuntimeDone - record: PlatformInitRuntimeDone ``` `PlatformInitRuntimeDone` 物件具有下列屬性： + **initializationType** – ``InitType`` 物件 + **phase** – ``InitPhase`` 物件 + **status** – ``Status`` 物件 + **spans?** – ``Span`` 物件的清單 以下是 `platform.initRuntimeDone` 類型 `Event` 的範例： ``` { "time": "2022-10-12T00:01:15.000Z", "type": "platform.initRuntimeDone", "record": { "initializationType": "on-demand" "status": "success", "spans": [ { "name": "someTimeSpan", "start": "2022-06-02T12:02:33.913Z", "durationMs": 70.5 } ] } } ``` ### `platform.initReport` `platform.initReport` 事件包含函數初始化階段的整體報告。`platform.initReport` `Event` 物件的結構如下： ``` Event: Object - time: String - type: String = platform.initReport - record: PlatformInitReport ``` `PlatformInitReport` 物件具有下列屬性： + **errorType?** - 字串 + **initializationType** – ``InitType`` 物件 + **phase** – ``InitPhase`` 物件 + **metrics** – ``InitReportMetrics`` 物件 + **spans?** – ``Span`` 物件的清單 + **status** – ``Status`` 物件 以下是 `platform.initReport` 類型 `Event` 的範例： ``` { "time": "2022-10-12T00:01:15.000Z", "type": "platform.initReport", "record": { "initializationType": "on-demand", "status": "success", "phase": "init", "metrics": { "durationMs": 125.33 }, "spans": [ { "name": "someTimeSpan", "start": "2022-06-02T12:02:33.913Z", "durationMs": 90.1 } ] } } ``` ### `platform.start` `platform.start` 事件表示函數調用階段已開始。`platform.start` `Event` 物件的結構如下： ``` Event: Object - time: String - type: String = platform.start - record: PlatformStart ``` `PlatformStart` 物件具有下列屬性： + **requestId** – `String` + **version?** – `String` + **tracing?** – ``TraceContext`` 以下是 `platform.start` 類型 `Event` 的範例： ``` { "time": "2022-10-12T00:00:15.064Z", "type": "platform.start", "record": { "requestId": "6d68ca91-49c9-448d-89b8-7ca3e6dc66aa", "version": "$LATEST", "tracing": { "spanId": "54565fb41ac79632", "type": "X-Amzn-Trace-Id", "value": "Root=1-62e900b2-710d76f009d6e7785905449a;Parent=0efbd19962d95b05;Sampled=1" } } } ``` ### `platform.runtimeDone` `platform.runtimeDone` 事件表示函數調用階段已完成。`platform.runtimeDone` `Event` 物件的結構如下： **Lambda 受管執行個體** Lambda 受管執行個體不支援 `platform.runtimeDone`事件。在受管執行個體上執行的延伸模組不會收到此事件，因為延伸模組無法訂閱受管執行個體上的`INVOKE`事件。由於並行執行模型可同時處理多個調用，延伸模組無法對個別調用執行調用後處理，因為它們通常在 Lambda （預設） 函數上執行。 對於受管執行個體，通常包含在 中的 `responseLatency`和 `responseDuration` 範圍`platform.runtimeDone`可改為在 `platform.report` 事件中使用。如需詳細資訊，請參閱 [`platform.report`](#platform-report)。 ``` Event: Object - time: String - type: String = platform.runtimeDone - record: PlatformRuntimeDone ``` `PlatformRuntimeDone` 物件具有下列屬性： + **errorType?** – `String` + **metrics?** – ``RuntimeDoneMetrics`` 物件 + **requestId** – `String` + **status** – ``Status`` 物件 + **spans?** – ``Span`` 物件的清單 + **tracing?** – ``TraceContext`` 物件 以下是 `platform.runtimeDone` 類型 `Event` 的範例： ``` { "time": "2022-10-12T00:01:15.000Z", "type": "platform.runtimeDone", "record": { "requestId": "6d68ca91-49c9-448d-89b8-7ca3e6dc66aa", "status": "success", "tracing": { "spanId": "54565fb41ac79632", "type": "X-Amzn-Trace-Id", "value": "Root=1-62e900b2-710d76f009d6e7785905449a;Parent=0efbd19962d95b05;Sampled=1" }, "spans": [ { "name": "someTimeSpan", "start": "2022-08-02T12:01:23:521Z", "durationMs": 80.0 } ], "metrics": { "durationMs": 140.0, "producedBytes": 16 } } } ``` ### `platform.report` `platform.report` 事件包含函數調用階段的整體報告。`platform.report` `Event` 物件的結構如下： **Lambda 受管執行個體** 與 Lambda （預設） 函數相比，Lambda 受管執行個體`platform.report`的事件具有不同的指標和範圍。對於受管執行個體： **範圍**：包含 `responseLatency`和 `responseDuration`而非 `extensionOverhead`。`extensionOverhead` 範圍不可用，因為由於並行執行模型，延伸模組無法訂閱受管執行個體上的`INVOKE`事件。 **指標**：僅包含 `durationMs`。不包含下列指標：`billedDurationMs`、`maxMemoryUsedMB`、 `initDurationMs`和 `memorySizeMB`。這些每次調用指標不適用於並行執行環境。如需資源使用率指標，請使用 [監控 Lambda 受管執行個體](lambda-managed-instances-monitoring.md)或 [Lambda Insights](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-insights.html)。 ``` Event: Object - time: String - type: String = platform.report - record: PlatformReport ``` `PlatformReport` 物件具有下列屬性： + **metrics** – ``ReportMetrics`` 物件 + **requestId** – `String` + **spans?** – ``Span`` 物件的清單 + **status** – ``Status`` 物件 + **tracing?** – ``TraceContext`` 物件 以下是 `platform.report` 類型 `Event` 的範例： ``` { "time": "2022-10-12T00:01:15.000Z", "type": "platform.report", "record": { "metrics": { "billedDurationMs": 694, "durationMs": 693.92, "initDurationMs": 397.68, "maxMemoryUsedMB": 84, "memorySizeMB": 128 }, "requestId": "6d68ca91-49c9-448d-89b8-7ca3e6dc66aa", } } ``` ### `platform.restoreStart` `platform.restoreStart` 事件表示函數環境還原事件已開始。在環境還原事件中，Lambda 會從快取的快照建立環境，而不是從頭開始初始化。如需詳細資訊，請參閱[Lambda SnapStart](snapstart.md)。`platform.restoreStart` `Event` 物件的結構如下： ``` Event: Object - time: String - type: String = platform.restoreStart - record: PlatformRestoreStart ``` `PlatformRestoreStart` 物件具有下列屬性： + **functionName** – `String` + **functionVersion** – `String` + **instanceId?** – `String` + **instanceMaxMemory?** – `String` + **runtimeVersion?** – `String` + **runtimeVersionArn?** – `String` 以下是 `platform.restoreStart` 類型 `Event` 的範例： ``` { "time": "2022-10-12T00:00:15.064Z", "type": "platform.restoreStart", "record": { "runtimeVersion": "nodejs-14.v3", "runtimeVersionArn": "arn", "functionName": "myFunction", "functionVersion": "$LATEST", "instanceId": "82561ce0-53dd-47d1-90e0-c8f5e063e62e", "instanceMaxMemory": 256 } } ``` ### `platform.restoreRuntimeDone` `platform.restoreRuntimeDone` 事件表示函數環境還原事件已完成。在環境還原事件中，Lambda 會從快取的快照建立環境，而不是從頭開始初始化。如需詳細資訊，請參閱[Lambda SnapStart](snapstart.md)。`platform.restoreRuntimeDone` `Event` 物件的結構如下： ``` Event: Object - time: String - type: String = platform.restoreRuntimeDone - record: PlatformRestoreRuntimeDone ``` `PlatformRestoreRuntimeDone` 物件具有下列屬性： + **errorType?** – `String` + **spans?** – ``Span`` 物件的清單 + **status** – ``Status`` 物件 以下是 `platform.restoreRuntimeDone` 類型 `Event` 的範例： ``` { "time": "2022-10-12T00:00:15.064Z", "type": "platform.restoreRuntimeDone", "record": { "status": "success", "spans": [ { "name": "someTimeSpan", "start": "2022-08-02T12:01:23:521Z", "durationMs": 80.0 } ] } } ``` ### `platform.restoreReport` `platform.restoreReport` 事件包含函數還原事件的整體報告。`platform.restoreReport` `Event` 物件的結構如下： ``` Event: Object - time: String - type: String = platform.restoreReport - record: PlatformRestoreReport ``` `PlatformRestoreReport` 物件具有下列屬性： + **errorType?** - 字串 + **metrics?** – ``RestoreReportMetrics`` 物件 + **spans?** – ``Span`` 物件的清單 + **status** – ``Status`` 物件 以下是 `platform.restoreReport` 類型 `Event` 的範例： ``` { "time": "2022-10-12T00:00:15.064Z", "type": "platform.restoreReport", "record": { "status": "success", "metrics": { "durationMs": 15.19 }, "spans": [ { "name": "someTimeSpan", "start": "2022-08-02T12:01:23:521Z", "durationMs": 30.0 } ] } } ``` ### `platform.extension` `extension` 事件包含延伸項目程式碼的日誌。`extension` `Event` 物件的結構如下： ``` Event: Object - time: String - type: String = extension - record: {} ``` `PlatformExtension` 物件具有下列屬性： + **events** – `String` 清單 + **name** – `String` + **state** – `String` 以下是 `platform.extension` 類型 `Event` 的範例： ``` { "time": "2022-10-12T00:02:15.000Z", "type": "platform.extension", "record": { "events": [ "INVOKE", "SHUTDOWN" ], "name": "my-telemetry-extension", "state": "Ready" } } ``` ### `platform.telemetrySubscription` `platform.telemetrySubscription` 事件包含延伸項目訂閱的相關資訊。`platform.telemetrySubscription` `Event` 物件的結構如下： ``` Event: Object - time: String - type: String = platform.telemetrySubscription - record: PlatformTelemetrySubscription ``` `PlatformTelemetrySubscription` 物件具有下列屬性： + **name** – `String` + **state** – `String` + **types** – `String` 清單 以下是 `platform.telemetrySubscription` 類型 `Event` 的範例： ``` { "time": "2022-10-12T00:02:35.000Z", "type": "platform.telemetrySubscription", "record": { "name": "my-telemetry-extension", "state": "Subscribed", "types": [ "platform", "function" ] } } ``` ### `platform.logsDropped` `platform.logsDropped` 事件包含已捨棄事件的相關資訊。當函數以過高速率輸出日誌，使得 Lambda 無法及時處理時，Lambda 會發出 `platform.logsDropped` 事件。當 Lambda 無法以函數產生日誌的速度將它們傳送到 CloudWatch 或訂閱了遙測 API 的延伸時，它會捨棄日誌以防止函數的執行速度變慢。`platform.logsDropped` `Event` 物件的結構如下： ``` Event: Object - time: String - type: String = platform.logsDropped - record: PlatformLogsDropped ``` `PlatformLogsDropped` 物件具有下列屬性： + **droppedBytes** – `Integer` + **droppedRecords** – `Integer` + **reason** – `String` 以下是 `platform.logsDropped` 類型 `Event` 的範例： ``` { "time": "2022-10-12T00:02:35.000Z", "type": "platform.logsDropped", "record": { "droppedBytes": 12345, "droppedRecords": 123, "reason": "Some logs were dropped because the downstream consumer is slower than the logs production rate" } } ``` ### `function` `function` 事件包含函數程式碼的日誌。`function` `Event` 物件的結構如下： ``` Event: Object - time: String - type: String = function - record: {} ``` `record` 欄位的格式取決於函數的日誌檔是以純文字格式還是 JSON 格式而定。若要進一步瞭解日誌格式設定選項，請參閱 [設定 JSON 和純文字日誌格式](monitoring-cloudwatchlogs-logformat.md) 以下是日誌格式為純文字時類型 `function` 的範例 `Event`。 ``` { "time": "2022-10-12T00:03:50.000Z", "type": "function", "record": "[INFO] Hello world, I am a function!" } ``` 以下是日誌格式為 JSON 時的類型 `function` 的範例 `Event`。 ``` { "time": "2022-10-12T00:03:50.000Z", "type": "function", "record": { "timestamp": "2022-10-12T00:03:50.000Z", "level": "INFO", "requestId": "79b4f56e-95b1-4643-9700-2807f4e68189", "message": "Hello world, I am a function!" } } ``` **注意** 如果您使用的描述版本比 `2022-12-13` 版本舊，則即使函數的 `"record"` 日誌格式配置為 JSON，也始終將其呈現為字串。對於 Lambda 受管執行個體，您必須使用結構描述版本 `2025-01-29`。 ### `extension` `extension` 事件包含延伸項目程式碼的日誌。`extension` `Event` 物件的結構如下： ``` Event: Object - time: String - type: String = extension - record: {} ``` `record` 欄位的格式取決於函數的日誌檔是以純文字格式還是 JSON 格式而定。若要進一步瞭解日誌格式設定選項，請參閱 [設定 JSON 和純文字日誌格式](monitoring-cloudwatchlogs-logformat.md) 以下是日誌格式為純文字時類型 `extension` 的範例 `Event`。 ``` { "time": "2022-10-12T00:03:50.000Z", "type": "extension", "record": "[INFO] Hello world, I am an extension!" } ``` 以下是日誌格式為 JSON 時的類型 `extension` 的範例 `Event`。 ``` { "time": "2022-10-12T00:03:50.000Z", "type": "extension", "record": { "timestamp": "2022-10-12T00:03:50.000Z", "level": "INFO", "requestId": "79b4f56e-95b1-4643-9700-2807f4e68189", "message": "Hello world, I am an extension!" } } ``` **注意** 如果您使用的描述版本比 `2022-12-13` 版本舊，則即使函數的 `"record"` 日誌格式配置為 JSON，也始終將其呈現為字串。對於 Lambda 受管執行個體，您必須使用結構描述版本 `2025-01-29`。 ## 共用物件類型 本節詳細說明 Lambda 遙測 API 支援的共用物件類型。 ### `InitPhase` 字串列舉，描述初始化步驟發生時的階段。多數情況下，Lambda 會在 `init` 階段執行函數初始化程式碼。但是在某些錯誤情況下，Lambda 可能會在 `invoke` 階段重新執行函數初始化程式碼。(這稱為*隱藏的初始化*。) + **類型** – `String` + **有效值** – `init`\$1`invoke`\$1`snap-start` ### `InitReportMetrics` 包含初始化階段相關指標的物件。 + **類型** – `Object` `InitReportMetrics` 物件的結構如下： ``` InitReportMetrics: Object - durationMs: Double ``` 下列為 `InitReportMetrics` 物件的範例: ``` { "durationMs": 247.88 } ``` ### `InitType` 字串列舉，描述 Lambda 如何初始化環境。 + **類型** – `String` + **有效值** – `on-demand`\$1`provisioned-concurrency` ### `ReportMetrics` 包含已完成階段相關指標的物件。 + **類型** – `Object` `ReportMetrics` 物件的結構如下： ``` ReportMetrics: Object - billedDurationMs: Integer - durationMs: Double - initDurationMs?: Double - maxMemoryUsedMB: Integer - memorySizeMB: Integer - restoreDurationMs?: Double ``` 下列為 `ReportMetrics` 物件的範例: ``` { "billedDurationMs": 694, "durationMs": 693.92, "initDurationMs": 397.68, "maxMemoryUsedMB": 84, "memorySizeMB": 128 } ``` ### `RestoreReportMetrics` 包含已完成還原階段相關指標的物件。 + **類型** – `Object` `RestoreReportMetrics` 物件的結構如下： ``` RestoreReportMetrics: Object - durationMs: Double ``` 下列為 `RestoreReportMetrics` 物件的範例: ``` { "durationMs": 15.19 } ``` ### `RuntimeDoneMetrics` 包含調用階段相關指標的物件。 + **類型** – `Object` `RuntimeDoneMetrics` 物件的結構如下： ``` RuntimeDoneMetrics: Object - durationMs: Double - producedBytes?: Integer ``` 下列為 `RuntimeDoneMetrics` 物件的範例: ``` { "durationMs": 200.0, "producedBytes": 15 } ``` ### `Span` 包含跨度詳細資訊的物件。跨度表示追蹤中的工作或作業單位。如需跨度的詳細資訊，請參閱 OpenTelemetry 文件網站的**追蹤 API** 頁面上的[跨度](https://opentelemetry.io/docs/reference/specification/trace/api/#span)。 Lambda 針對 `platform.RuntimeDone` 事件支援下列跨度： + `responseLatency` 跨度描述 Lambda 函數開始傳送回應所花費的時間。 + `responseDuration` 跨度描述 Lambda 函數完成傳送整個回應所花費的時間。 + `runtimeOverhead` 跨度描述 Lambda 執行期表示已準備好處理下一個函數調用所花費的時間。這是執行期傳回函數回應後，呼叫[下一個調用](runtimes-api.md#runtimes-api-next) API 所花費的時間。 下列為 `responseLatency` 跨度物件的範例: ``` { "name": "responseLatency", "start": "2022-08-02T12:01:23.521Z", "durationMs": 23.02 } ``` ### `Status` 描述初始化或呼叫階段狀態的物件。如果狀態為 `failure` 或 `error`，則 `Status` 物件也會包含描述錯誤的 `errorType` 欄位。 + **類型** – `Object` + **有效狀態值** – `success`\$1`failure`\$1`error`\$1`timeout` ### `TraceContext` 描述追蹤屬性的物件。 + **類型** – `Object` `TraceContext` 物件的結構如下： ``` TraceContext: Object - spanId?: String - type: TracingType enum - value: String ``` 下列為 `TraceContext` 物件的範例: ``` { "spanId": "073a49012f3c312e", "type": "X-Amzn-Trace-Id", "value": "Root=1-62e900b2-710d76f009d6e7785905449a;Parent=0efbd19962d95b05;Sampled=1" } ``` ### `TracingType` 字串列舉，描述 ``TraceContext`` 物件中追蹤的類型。 + **類型** – `String` + **有效值** – `X-Amzn-Trace-Id` # 將 Lambda 遙測 API`Event` 物件轉換為 OpenTelemetry 跨度 AWS Lambda 遙測 API 結構描述在語義上與 OpenTelemetry (OTel) 相容。這表示您可以將 AWS Lambda 遙測 API `Event` 物件轉換為 OpenTelemetry (OTel) 範圍。轉換時，不應將單一 `Event` 物件映射到單一 oTel 跨度。而是應該在單一 oTel 跨度中顯示與生命週期階段相關的全部三個事件。例如，`start`、`runtimeDone` 和 `runtimeReport` 事件代表單一函數叫用。將這三個事件做為一個單一的 oTel 跨度呈現。 您可以使用跨度事件或子 (巢狀) 跨度轉換事件。此頁面上的表格針對這兩種做法，說明遙測 API 結構描述屬性與 oTel 跨度屬性之間的映射。如需 OTel 跨度的詳細資訊，請參閱 OpenTelemetry 文件網站的**追蹤 API** 頁面上的[跨度](https://opentelemetry.io/docs/reference/specification/trace/api/#span)。 **Topics** + [ ## 透過跨度事件映射到 OTel 跨度 ](#telemetry-otel-span-events) + [ ## 透過子跨度映射到 OTel 跨度 ](#telemetry-otel-child-spans) ## 透過跨度事件映射到 OTel 跨度 在下表中，`e` 代表來自遙測來源的事件。 **映射 \$1Start 事件** | OpenTelemetry | Lambda 遙測 API 結構描述 | | --- | --- | | `Span.Name` | 延伸項目會根據 `type` 欄位產生此值。 | | `Span.StartTime` | 請使用 `e.time`。 | | `Span.EndTime` | N/A，因為事件尚未完成。 | | `Span.Kind` | 設定為 `Server`。 | | `Span.Status` | 設定為 `Unset`。 | | `Span.TraceId` | 剖析 中找到的 AWS X-Ray 標頭`e.tracing.value`，然後使用 `TraceId`值。 | | `Span.ParentId` | 剖析 `e.tracing.value` 中找到的 X-Ray 標頭，然後使用 `Parent` 值。 | | `Span.SpanId` | 使用 `e.tracing.spanId` (如果可用)。若無法使用，請產生一個新的 `SpanId`。 | | `Span.SpanContext.TraceState` | X-Ray 追蹤內容則為 N/A。 | | `Span.SpanContext.TraceFlags` | 剖析 `e.tracing.value` 中找到的 X-Ray 標頭，然後使用 `Sampled` 值。 | | `Span.Attributes` | 延伸項目可以在此處新增任何自訂值。 | **映射 \$1RuntimeDone 事件** | OpenTelemetry | Lambda 遙測 API 結構描述 | | --- | --- | | `Span.Name` | 延伸項目會根據 `type` 欄位產生值。 | | `Span.StartTime` | 使用相符 `*Start` 事件中的 `e.time`。 或使用 `e.time - e.metrics.durationMs`。 | | `Span.EndTime` | N/A，因為事件尚未完成。 | | `Span.Kind` | 設定為 `Server`。 | | `Span.Status` | 如果 `e.status` 不等於 `success`，則設定為 `Error`。 否則，請設定為 `Ok`。 | | `Span.Events[]` | 請使用 `e.spans[]`。 | | `Span.Events[i].Name` | 請使用 `e.spans[i].name`。 | | `Span.Events[i].Time` | 請使用 `e.spans[i].start`。 | | `Span.TraceId` | 剖析 中找到的 AWS X-Ray 標頭`e.tracing.value`，然後使用 `TraceId`值。 | | `Span.ParentId` | 剖析 `e.tracing.value` 中找到的 X-Ray 標頭，然後使用 `Parent` 值。 | | `Span.SpanId` | 使用 `*Start` 事件的相同 `SpanId`。如果無法使用，則使用 `e.tracing.spanId` 或產生新的 `SpanId`。 | | `Span.SpanContext.TraceState` | X-Ray 追蹤內容則為 N/A。 | | `Span.SpanContext.TraceFlags` | 剖析 `e.tracing.value` 中找到的 X-Ray 標頭，然後使用 `Sampled` 值。 | | `Span.Attributes` | 延伸項目可以在此處新增任何自訂值。 | **映射 \$1Report 事件** | OpenTelemetry | Lambda 遙測 API 結構描述 | | --- | --- | | `Span.Name` | 延伸項目會根據 `type` 欄位產生值。 | | `Span.StartTime` | 使用相符 `*Start` 事件中的 `e.time`。 或使用 `e.time - e.metrics.durationMs`。 | | `Span.EndTime` | 請使用 `e.time`。 | | `Span.Kind` | 設定為 `Server`。 | | `Span.Status` | 使用與 `*RuntimeDone` 事件相同的值。 | | `Span.TraceId` | 剖析 中找到的 AWS X-Ray 標頭`e.tracing.value`，然後使用 `TraceId`值。 | | `Span.ParentId` | 剖析 `e.tracing.value` 中找到的 X-Ray 標頭，然後使用 `Parent` 值。 | | `Span.SpanId` | 使用 `*Start` 事件的相同 `SpanId`。如果無法使用，則使用 `e.tracing.spanId` 或產生新的 `SpanId`。 | | `Span.SpanContext.TraceState` | X-Ray 追蹤內容則為 N/A。 | | `Span.SpanContext.TraceFlags` | 剖析 `e.tracing.value` 中找到的 X-Ray 標頭，然後使用 `Sampled` 值。 | | `Span.Attributes` | 延伸項目可以在此處新增任何自訂值。 | ## 透過子跨度映射到 OTel 跨度 下表說明如何針對 `*RuntimeDone` 跨度，透過子 (巢狀) 跨度將 Lambda 遙測 API 事件轉換為 OTel 跨度。如需 `*Start` 和 `*Report` 映射，請參閱「[透過跨度事件映射到 OTel 跨度](#telemetry-otel-span-events)」中的表格，因為對子跨度來說是相同的。在本表中，`e` 代表來自遙測來源的事件。 **映射 \$1RuntimeDone 事件** | OpenTelemetry | Lambda 遙測 API 結構描述 | | --- | --- | | `Span.Name` | 延伸項目會根據 `type` 欄位產生值。 | | `Span.StartTime` | 使用相符 `*Start` 事件中的 `e.time`。 或使用 `e.time - e.metrics.durationMs`。 | | `Span.EndTime` | N/A，因為事件尚未完成。 | | `Span.Kind` | 設定為 `Server`。 | | `Span.Status` | 如果 `e.status` 不等於 `success`，則設定為 `Error`。 否則，請設定為 `Ok`。 | | `Span.TraceId` | 剖析 中找到的 AWS X-Ray 標頭`e.tracing.value`，然後使用 `TraceId`值。 | | `Span.ParentId` | 剖析 `e.tracing.value` 中找到的 X-Ray 標頭，然後使用 `Parent` 值。 | | `Span.SpanId` | 使用 `*Start` 事件的相同 `SpanId`。如果無法使用，則使用 `e.tracing.spanId` 或產生新的 `SpanId`。 | | `Span.SpanContext.TraceState` | X-Ray 追蹤內容則為 N/A。 | | `Span.SpanContext.TraceFlags` | 剖析 `e.tracing.value` 中找到的 X-Ray 標頭，然後使用 `Sampled` 值。 | | `Span.Attributes` | 延伸項目可以在此處新增任何自訂值。 | | `ChildSpan[i].Name` | 請使用 `e.spans[i].name`。 | | `ChildSpan[i].StartTime` | 請使用 `e.spans[i].start`。 | | `ChildSpan[i].EndTime` | 請使用 `e.spans[i].start + e.spans[i].durations`。 | | `ChildSpan[i].Kind` | 與父項 `Span.Kind` 相同。 | | `ChildSpan[i].Status` | 與父項 `Span.Status` 相同。 | | `ChildSpan[i].TraceId` | 與父項 `Span.TraceId` 相同。 | | `ChildSpan[i].ParentId` | 使用父項 `Span.SpanId`。 | | `ChildSpan[i].SpanId` | 產生新的 `SpanId`。 | | `ChildSpan[i].SpanContext.TraceState` | X-Ray 追蹤內容則為 N/A。 | | `ChildSpan[i].SpanContext.TraceFlags` | 與父項 `Span.SpanContext.TraceFlags` 相同。 | # 使用 Lambda Logs API **重要** Lambda 遙測 API 優先於 Lambda 日誌 API。**雖然日誌 API 仍然正常運作，但我們建議您未來只使用遙測 API。**您可以使用遙測 API 或日誌 API 訂閱遙測串流的延伸項目。使用其中一個 API 進行訂閱後，若嘗試使用其他 API 進行任何訂閱，都會傳回錯誤。 **Lambda 受管執行個體不支援 Logs API** Lambda 受管執行個體不支援 Logs API。如果您使用的是受管執行個體函數，請改用[遙測 API](telemetry-api.md)。遙測 API 提供從 Lambda 函數收集和處理遙測資料的增強功能。 Lambda 會自動擷取執行時間日誌並將其串流至 Amazon CloudWatch。此日誌串流包含函數程式碼和延伸項目產生的日誌，以及 Lambda 作為函數調用一部分產生的日誌。 [Lambda 延伸項目](runtimes-extensions-api.md)可以使用 Lambda Runtime Logs API，直接從 Lambda [執行環境](lambda-runtime-environment.md)中訂閱記錄串流。Lambda 會將日誌串流至延伸項目，延伸項目隨後可處理、篩選日誌並將其傳送至任何偏好目的地。 ![\[\]](http://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/logs-api-concept-diagram.png) Logs API 允許延伸項目訂閱三種不同的日誌串流： + Lambda 函數產生並寫入到 `stdout` 或 `stderr` 的函數日誌。 + 延伸項目程式碼產生的延伸項目日誌。 + Lambda 平台日誌，它記錄與調用和延伸項目相關的事件和錯誤。 **注意** 即便延伸項目訂閱一個或多個日誌串流，Lambda 也會將所有日誌傳送至 CloudWatch。 **Topics** + [ ## 訂閱接收日誌 ](#runtimes-logs-api-subscribing) + [ ## 記憶體用量 ](#runtimes-logs-api-memory) + [ ## 目的地協定 ](#runtimes-logs-api-dest) + [ ## 緩衝組態 ](#runtimes-logs-api-buffering) + [ ## 訂閱範例 ](#runtimes-logs-api-subs-example) + [ ## Logs API 的範本程式碼 ](#runtimes-logs-api-samples) + [ ## Logs API 參考 ](#runtimes-logs-api-ref) + [ ## 日誌訊息 ](#runtimes-logs-api-msg) ## 訂閱接收日誌 Lambda 延伸項目可透過傳送訂閱請求至 Logs API 來訂閱接收日誌。 若要訂閱接收日誌，您需要延伸項目識別符 (`Lambda-Extension-Identifier`)。首先[註冊延伸項目](runtimes-extensions-api.md#extensions-registration-api-a)以接收延伸項目識別符。然後在[初始化](lambda-runtime-environment.md#runtimes-lifecycle-ib)期間訂閱 Logs API。初始化階段完成後，Lambda 不會處理訂閱請求。 **注意** Logs API 訂閱為等冪操作。重複的訂閱請求不會導致重複訂閱。 ## 記憶體用量 隨著訂閱者數量的增加，記憶體用量會線性增加。訂閱會耗用記憶體資源，因為每個訂閱都會開啟新的記憶體緩衝區來存放日誌。為了協助最佳化記憶體用量，您可以調整[緩衝組態](#runtimes-logs-api-buffering)。緩衝區記憶體用量會計入執行環境中的整體記憶體耗用量。 ## 目的地協定 您可以選擇下列其中一個協定來接收日誌： 1. **HTTP** (建議) - Lambda 會以 JSON 格式的記錄陣列將日誌傳遞至本機 HTTP 端點 (`http://sandbox.localdomain:${PORT}/${PATH}`)。`$PATH` 為選用參數。請注意，僅支援 HTTP，而不是 HTTPS。您可以選擇透過 PUT 或 POST 接收日誌。 1. **TCP** - Lambda 以[換行分隔的 JSON (NDJSON) 格式](https://github.com/ndjson/ndjson-spec)將日誌傳遞至 TCP 連接埠。 建議使用 HTTP，而不是使用 TCP。使用 TCP，Lambda 平台無法確認何時將日誌傳遞至應用程式層。因此，如果您的延伸項目損毀，可能會遺失日誌。HTTP 不會共享此限制。 我們也建議您先設定本機 HTTP 接聽程式或 TCP 連接埠，然後再訂閱接收日誌。在設定期間，請注意下列事項： + Lambda 只會將日誌傳送至執行環境內的目的地。 + 如果沒有接聽程式，或者如果 POST 或 PUT 請求導致錯誤，則 Lambda 會重新嘗試傳送日誌 (使用輪詢)。如果日誌訂閱者當機，則在 Lambda 重新啟動執行環境之後會繼續接收日誌。 + Lambda 保留連接埠 9001。沒有其他連接埠編號限制或建議。 ## 緩衝組態 Lambda 可以緩衝日誌並將其提供給訂閱者。您可以透過指定下列選用欄位，在訂閱請求中設定此行為。請注意，Lambda 會對您未指定的任何欄位使用預設值。 + **timeoutMs** - 緩衝批次處理的時間上限 (毫秒)。預設：1,000。下限：25。上限：30,000。 + **maxBytes** - 記憶體中要緩衝的日誌大小上限 (位元組)。預設：262,144。下限：262,144。上限：1,048,576。 + **maxItems** – 記憶體中要緩衝的事件數目上限。預設：10,000。下限：1,000。上限：10,000。 在緩衝組態期間，請注意下列幾點： + 如果任何輸入串流被關閉，例如，如果執行時間崩潰，Lambda 會清除日誌。 + 每個訂閱者可以在訂閱請求中指定不同的緩衝組態。 + 考慮讀取資料所需的緩衝區大小。預計接收最大為 `2*maxBytes+metadata` 的承載，其中 `maxBytes` 在訂閱請求中進行設定。例如，Lambda 將下列中繼資料位元組新增至每個記錄： ``` { "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "Hello World" } ``` + 如果訂閱者無法足夠快速地處理傳入日誌，Lambda 可能會丟棄日誌，以確保記憶體使用率受到限制。若要指示丟棄的記錄數量，Lambda 會傳送 `platform.logsDropped` 日誌。如需詳細資訊，請參閱[Lambda：並非所有函數的日誌都會顯示](troubleshooting-execution.md#troubleshooting-execution-missinglogs)。 ## 訂閱範例 訂閱平台和函數日誌的請求如下列範例所示。 ``` PUT http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs HTTP/1.1 { "schemaVersion": "2020-08-15", "types": [ "platform", "function" ], "buffering": { "maxItems": 1000, "maxBytes": 262144, "timeoutMs": 100 }, "destination": { "protocol": "HTTP", "URI": "http://sandbox.localdomain:8080/lambda_logs" } } ``` 如果請求成功，訂閱者會收到 HTTP 200 成功回應。 ``` HTTP/1.1 200 OK "OK" ``` ## Logs API 的範本程式碼 如需示範如何將日誌傳送至自訂目的地的範例程式碼，請參閱 AWS 運算部落格上的[使用 AWS Lambda 擴充功能將日誌傳送至自訂目的地](https://aws.amazon.com/blogs/compute/using-aws-lambda-extensions-to-send-logs-to-custom-destinations/)。 對於顯示如何開發基本 Lambda 延伸及訂閱 Logs API 的 Python 和 Go 程式碼範例，請參閱 AWS Samples GitHub 儲存庫上的 [AWS Lambda Extensions](https://github.com/aws-samples/aws-lambda-extensions)。如需建置 Lambda 延伸項目的詳細資訊，請參閱 [使用 Lambda 延伸 API 來建立延伸項目](runtimes-extensions-api.md)。 ## Logs API 參考 您可以從 `AWS_LAMBDA_RUNTIME_API` 環境變數中擷取 Logs API 端點。若要傳送 API 請求，請在 API 路徑之前使用前綴 `2020-08-15/`。例如： ``` http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs ``` Logs API 的 OpenAPI 規範 (版本 **2020-08-15**) 可參閱此文件：[logs-api-request.zip](samples/logs-api-request.zip) ### 訂閱 若要訂閱 Lambda 執行環境中可用的一個或多個日誌串流，延伸項目會傳送 Subscribe API 請求。 **路徑** – `/logs` **方法** – **PUT** **主體參數** `destination` – 請參閱[目的地協定](#runtimes-logs-api-dest)。必要：是。類型：字串。 `buffering` – 請參閱[緩衝組態](#runtimes-logs-api-buffering)。必要：否。類型：字串。 `types` - 要接收的日誌類型陣列。必要：是。類型：字串陣列。有效值：「平台」、「函數」、「延伸項目」。 `schemaVersion` - 必要：否。預設值："2020-08-15"。將延伸項目設定為 "2021-03-18"，可接收 [`platform.runtimeDone`](#runtimes-logs-api-ref-done) 訊息。 ****回應參數**** 訂閱回應的 OpenAPI 規範 (版本 **2020-08-15**)，適用於 HTTP 和 TCP 通訊協定： + HTTP︰[logs-api-http-response.zip](samples/logs-api-http-response.zip) + TCP︰[logs-api-tcp-response.zip](samples/logs-api-tcp-response.zip) ****回應代碼**** + 200 - 請求已成功完成 + 202 - 已接受請求。在本機測試期間回應訂閱請求。 + 4XX - 錯誤請求 + 500 - 服務錯誤 如果請求成功，訂閱者會收到 HTTP 200 成功回應。 ``` HTTP/1.1 200 OK "OK" ``` 如果請求失敗，訂閱者會收到錯誤回應。例如： ``` HTTP/1.1 400 OK { "errorType": "Logs.ValidationError", "errorMessage": URI port is not provided; types should not be empty" } ``` ## 日誌訊息 Logs API 允許延伸項目訂閱三種不同的日誌串流： + 函數 - Lambda 函數產生並寫入到 `stdout` 或 `stderr` 的日誌。 + 延伸項目 - 延伸項目程式碼產生的日誌。 + 平台 - 執行時間平台產生的日誌，它們記錄與調用和延伸相關的事件和錯誤。 **Topics** + [ ### 函數日誌 ](#runtimes-logs-api-msg-function) + [ ### 延伸項目日誌 ](#runtimes-logs-api-msg-extension) + [ ### 平台日誌 ](#runtimes-logs-api-msg-platform) ### 函數日誌 Lambda 函數和內部延伸項目會產生函數日誌並將它們寫入 `stdout` 或 `stderr`。 下列範例顯示函數日誌訊息的格式。\$1 "time": "2020-08-20T12:31:32.123Z", "type": "function", "record": "ERROR encountered. Stack trace:\$1n\$1my-function (line 10)\$1n" \$1 ### 延伸項目日誌 延伸項目可產生延伸日誌。日誌格式與函數日誌的格式相同。 ### 平台日誌 Lambda 會產生平台事件 (例如 `platform.start`、`platform.end` 以及 `platform.fault`) 的日誌訊息。 或者，您可以訂閱包含 `platform.runtimeDone` 日誌訊息的 **2021-03-18** 版本的 Logs API 結構描述。 #### 平台日誌訊息範例 下面的範例顯示了平台開始和平台結束日誌。這些日誌指出 RequestID 所指定之調用的調用開始時間和調用結束時間。 ``` { "time": "2020-08-20T12:31:32.123Z", "type": "platform.start", "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"} } { "time": "2020-08-20T12:31:32.123Z", "type": "platform.end", "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"} } ``` **platform.initRuntimeDone** 日誌訊息顯示子階段 `Runtime init` 的狀態，該子階段是[初始化生命週期階段](lambda-runtime-environment.md#runtimes-lifecycle-ib)的一部分。`Runtime init` 成功時，執行階段會傳送 `/next` 執行階段 API 請求 (針對 `on-demand` 和 `provisioned-concurrency` 初始化類型) 或 `restore/next` (針對 `snap-start` 初始化類型)。下列範例顯示 `snap-start` 初始化類型的成功 **platform.initRuntimeDone** 日誌訊息。 ``` { "time":"2022-07-17T18:41:57.083Z", "type":"platform.initRuntimeDone", "record":{ "initializationType":"snap-start", "status":"success" } } ``` **platform.initReport** 日誌訊息會顯示 `Init` 階段持續的時間長度，以及您須為此階段支付的費用。當初始化類型為 `provisioned-concurrency`，Lambda 會在調用期間傳送此訊息。當初始化類型為 `snap-start`，Lambda 會在還原快照之後傳送此訊息。下列範例顯示 `snap-start` 初始化類型的 **platform.initReport** 日誌訊息。 ``` { "time":"2022-07-17T18:41:57.083Z", "type":"platform.initReport", "record":{ "initializationType":"snap-start", "metrics":{ "durationMs":731.79, "billedDurationMs":732 } } } ``` 平台報告日誌包含 RequestID 所指定之調用的相關指標。只有調用包含冷啟動時，`initDurationMs` 欄位才會包含在日誌中。如果 AWS X-Ray 追蹤處於作用中狀態，則日誌包含 X-Ray 中繼資料。下列範例顯示包含冷啟動之調用的平台報告日誌。 ``` { "time": "2020-08-20T12:31:32.123Z", "type": "platform.report", "record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56", "metrics": {"durationMs": 101.51, "billedDurationMs": 300, "memorySizeMB": 512, "maxMemoryUsedMB": 33, "initDurationMs": 116.67 } } } ``` 平台故障日誌會擷取執行時間或執行環境錯誤。平台錯誤日誌訊息如下列範例所示。 ``` { "time": "2020-08-20T12:31:32.123Z", "type": "platform.fault", "record": "RequestId: d783b35e-a91d-4251-af17-035953428a2c Process exited before completing request" } ``` **注意** AWS 目前正在對 Lambda 服務實作變更。由於這些變更，您可能會看到系統日誌訊息的結構和內容，與 AWS 帳戶中不同 Lambda 函數發出的追蹤區段之間存在細微差異。 受此變更影響的日誌輸出之一是平台故障日誌 `"record"` 欄位。下列範例顯示了舊格式和新格式的說明性 `"record"` 欄位。新式故障日誌包含更簡潔的訊息 這些變化將在未來幾週內實作，除中國和 GovCloud 區域以外，所有 AWS 區域 中的所有函數都會轉換至使用新格式的日誌訊息和追蹤區段。 **Example 平台故障日誌記錄 (舊式)** ``` "record":"RequestId: ...\tError: Runtime exited with error: exit status 255\nRuntime.ExitError" ``` **Example 平台故障日誌記錄 (新式)** ``` "record":"RequestId: ... Status: error\tErrorType: Runtime.ExitError" ``` 當延伸項目註冊延伸項目 API 時，Lambda 會產生平台延伸項目日誌。平台延伸項目訊息如下列範例所示。 ``` { "time": "2020-08-20T12:31:32.123Z", "type": "platform.extension", "record": {"name": "Foo.bar", "state": "Ready", "events": ["INVOKE", "SHUTDOWN"] } } ``` 當延伸項目訂閱日誌 API 時，Lambda 會產生平台日誌訂閱日誌。日誌訂閱訊息如下列範例所示。 ``` { "time": "2020-08-20T12:31:32.123Z", "type": "platform.logsSubscription", "record": {"name": "Foo.bar", "state": "Subscribed", "types": ["function", "platform"], } } ``` 當延伸項目無法處理正在接收的日誌數量時，Lambda 產生的日誌會捨棄平台日誌。`platform.logsDropped` 日誌訊息如下列範例所示。 ``` { "time": "2020-08-20T12:31:32.123Z", "type": "platform.logsDropped", "record": {"reason": "Consumer seems to have fallen behind as it has not acknowledged receipt of logs.", "droppedRecords": 123, "droppedBytes" 12345 } } ``` **platform.restoreStart** 日誌訊息會顯示 `Restore` 階段開始的時間 (僅限 `snap-start` 初始化類型)。範例： ``` { "time":"2022-07-17T18:43:44.782Z", "type":"platform.restoreStart", "record":{} } ``` **platform.restoreReport** 日誌訊息會顯示 `Restore` 階段持續的時間長度，以及您須為此階段付費的毫秒數 (僅限 `snap-start` 初始化類型)。範例： ``` { "time":"2022-07-17T18:43:45.936Z", "type":"platform.restoreReport", "record":{ "metrics":{ "durationMs":70.87, "billedDurationMs":13 } } } ``` #### 平台 `runtimeDone` 訊息 如果您在訂閱請求中將結構描述版本設定為 "2021-03-18"，在函數調用成功完成或發生錯誤之後，Lambda 會傳送 `platform.runtimeDone` 訊息。延伸項目可以使用此訊息停止此函數調用的所有遙測集合。 結構描述版本 **2021-03-18** 中的日誌事件類型的 OpenAPI 規範可參閱此文件：[schema-2021-03-18.zip](samples/schema-2021-03-18.zip) 當執行時間傳送 `Next` 或 `Error` 執行時間 API 請求時，Lambda 會產生 `platform.runtimeDone` 日誌訊息。`platform.runtimeDone` 日誌會通知 Logs API 的使用者，告知他們函數調用完成。延伸項目可以使用此資訊來決定何時傳送該調用期間收集的所有遙測。 ##### 範例 當函數調用完成時，在執行時間傳送 NEXT 請求之後，Lambda 會傳送 `platform.runtimeDone` 訊息。下列範例顯示每個狀態值的訊息：成功、失敗和逾時。 **Example 成功訊息範例** ``` { "time": "2021-02-04T20:00:05.123Z", "type": "platform.runtimeDone", "record": { "requestId":"6f7f0961f83442118a7af6fe80b88", "status": "success" } } ``` **Example 失敗訊息範例** ``` { "time": "2021-02-04T20:00:05.123Z", "type": "platform.runtimeDone", "record": { "requestId":"6f7f0961f83442118a7af6fe80b88", "status": "failure" } } ``` **Example 逾時訊息範例** ``` { "time": "2021-02-04T20:00:05.123Z", "type": "platform.runtimeDone", "record": { "requestId":"6f7f0961f83442118a7af6fe80b88", "status": "timeout" } } ``` **Example platform.restoreRuntimeDone 訊息範例 (僅限 `snap-start` 初始化類型)** **platform.restoreRuntimeDone** 日誌訊息會顯示 `Restore` 階段是否成功。執行階段傳送 `restore/next` 執行階段 API 請求時，Lambda 會產生此訊息。可能的狀態有三種：成功、失敗和逾時。成功的 **platform.restoreRuntimeDone** 日誌訊息如下列範例所示。 ``` { "time":"2022-07-17T18:43:45.936Z", "type":"platform.restoreRuntimeDone", "record":{ "status":"success" } } ```