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

# 記錄 Amazon EventBridge 管道效能
<a name="eb-pipes-logs"></a>

EventBridge 管道記錄可讓您讓 EventBridge 管道將詳細說明管道效能的記錄傳送至支援 AWS 的服務。使用日誌來深入瞭解管道的執行效能，並協助進行疑難排解和偵錯。

您可以選擇下列 AWS 服務做為 EventBridge 管道交付記錄的*日誌目的地*：
+ CloudWatch Logs

  EventBridge 會將日誌記錄交付至指定的 CloudWatch Logs 日誌群組。

  CloudWatch Logs 可讓您將您使用的所有系統、應用程式和 AWS 服務的日誌，集中在可高度擴展的單一服務中。如需詳細資訊，請參閱《Amazon CloudWatch Logs 使用者指南》**中的[使用日誌群組和日誌串流](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)。
+ Firehose 串流日誌

  EventBridge 會將日誌記錄交付至 Firehose 交付串流。

  Amazon Data Firehose 是一項全受管服務，可將即時串流資料交付至特定 AWS 服務等目的地，以及任何自訂 HTTP 端點或受支援第三方服務供應商擁有的 HTTP 端點。如需詳細資訊，請參閱[《Amazon Data Firehose 使用者指南》中的建立 Amazon Data Firehose 交付串流](https://docs.aws.amazon.com/firehose/latest/dev/basic-create.html)。 **
+ Amazon S3 日誌

  EventBridge 將日誌記錄以 Amazon S3 物件的形式傳送到指定的儲存貯體。

  Amazon S3 是一項物件儲存服務，提供領先業界的可擴展性、資料可用性、安全性和效能。如需詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》**中的 Amazon S3 中的[上傳、下載和使用 Amazon S3 中的物件](https://docs.aws.amazon.com/AmazonS3/latest/userguide/uploading-downloading-objects.html)。

## Amazon EventBridge Pipes 記錄的方式
<a name="eb-pipes-logs-overview"></a>

管道接收到的每個事件或一批事件，而該事件傳遞到一個擴充和/或目標都被視為管道*執行*。如果啟用，EventBridge 會在處理事件批次時為其執行的每個執行步驟產生日誌。記錄中包含的資訊會套用至事件批次，無論是單一事件還是最多 10,000 個事件。

您可以在管道來源和目標上設定事件批次的大小。如需詳細資訊，請參閱[Amazon EventBridge 管道批次處理和並行](eb-pipes-batching-concurrency.md)。

傳送至每個日誌目的地的記錄資料相同。

如果已設定 Amazon CloudWatch Logs 目的地，則傳送到所有目的地的日誌記錄的限制為 256kb。欄位將視需要截斷。

您可以使用下列方式自訂 EventBridge 傳送至所選取日誌目的地的記錄：
+ 您可以指定*日誌層級*，以決定 EventBridge 將記錄傳送至所選取日誌目的地的執行步驟。如需詳細資訊，請參閱[指定 EventBridge 管道日誌層級](#eb-pipes-logs-level)。
+ 您可以指定 EventBridge 管道是否在相關執行步驟的記錄中包含執行資料。此資料包括：
  + 事件批次的裝載
  + 傳送至 AWS 擴充或目標服務的請求
  +  AWS 擴充或目標服務傳回的回應

  如需詳細資訊，請參閱[在 EventBridge 管道日誌中包含執行資料](#eb-pipes-logs-execution-data)。

## 指定 EventBridge 管道日誌層級
<a name="eb-pipes-logs-level"></a>

您可以指定 EventBridge 將記錄傳送至所選取日誌目的地的執行步驟。

請從下列詳細層次中選擇要包含在日誌記錄中的細節層次。日誌層級會套用至為管道指定的所有日誌目的地。每個日誌層級都包含先前日誌層級的執行步驟。
+ **關閉**：EventBridge 不會將任何記錄傳送到任何指定的日誌目的地。這是預設設定。
+ **ERROR**：EventBridge 會將任何與管道執行期間產生的錯誤相關的記錄傳送至指定的日誌目的地。
+ **資訊**：EventBridge 會傳送任何與錯誤相關的記錄，以及選取管道執行期間所執行的其他步驟至指定的日誌目的地。
+ **TRACE**：EventBridge 會將管道執行期間任何步驟產生的任何記錄傳送至指定的日誌目的地。

在 EventBridge 主控台中， CloudWatch 預設會選取日誌做為日誌目的地，日誌`ERROR`層級也是。因此，根據預設， EventBridge Pipes 會建立新的 CloudWatch 日誌群組，將包含詳細資訊`ERROR`層級的日誌記錄傳送到其中。以程式設計方式設定日誌記錄檔時，不會選取預設值。

下表列出了每個日誌層級中包含的執行步驟。


****  

| 步驟 | TRACE | INFO | ERROR | OFF | 
| --- | --- | --- | --- | --- | 
|  執行已失敗  | x | x | x |   | 
|  部分執行失敗  | x | x | x |  | 
|  執行已開始  | x | x |   |   | 
|  執行已成功  | x | x |   |   | 
|  限制執行  | x | x | x |   | 
|  執行逾時  | x | x | x |   | 
|  擴展調用失敗  | x | x | x |  | 
|  已跳過的擴充調用  | x | x |  |  | 
|  擴充調用已開始  | x |  |  |  | 
|  擴充調用已成功  | x |  |  |  | 
|  已進入擴充階段  | x | x |  |  | 
|  擴充階段失敗  | x | x | x |  | 
|  擴充階段成功  | x | x |  |  | 
|  擴充轉換失敗  | x | x | x |  | 
|  擴充轉換開始  | x |  |  |  | 
|  擴充轉換成功  | x |  |  |  | 
|  目標調用失敗  | x | x | x |  | 
|  目標調用部分失敗  | x | x | x |  | 
|  目標調用已跳過  | x |  |  |  | 
|  目標調用已開始  | x |  |  |  | 
|  目標調用成功  | x |  |  |  | 
|  已進入目標階段  | x | x |  |  | 
|  目標階段失敗  | x | x | x |  | 
|  目標階段部分失敗  | x | x | x |  | 
|  跳過的目標階段  | x |  |  |  | 
|  目標階段成功  | x | x |  |  | 
|  目標轉換失敗  | x | x | x |  | 
|  目標轉換已開始  | x |  |  |  | 
|  目標轉換成功  | x |  |  |  | 

## 在 EventBridge 管道日誌中包含執行資料
<a name="eb-pipes-logs-execution-data"></a>

您可以指定讓 EventBridge 在其產生的記錄中包含*執行資料*。執行資料包括代表事件批次裝載的欄位，以及傳送至的要求以及來自擴充和目標的回應的欄位。

執行資料對於疑難排解和偵錯很有用。該 `payload` 欄位包含批次中包含的每個事件的實際內容，可讓您將個別事件與特定管路執行相關聯。

如果您選擇包括執行資料，則會針對管道指定的所有日誌目的地加入該資料。

**重要**  
這些欄位可能包含敏感資訊。在記錄期間，EventBridge 不會嘗試編輯這些欄位的內容。

當包含執行資料時，EventBridge 會將下列欄位新增至相關記錄中：
+ **`payload`**

  表示管道正在處理的事件批次的內容。

  EventBridge 會在事件批次內容可能已更新的步驟所產生的記錄中包含 `payload` 欄位。這包括以下步驟︰
  + `EXECUTION_STARTED`
  + `ENRICHMENT_TRANSFORMATION_SUCCEEDED`
  + `ENRICHMENT_STAGE_SUCCEEDED`
  + `TARGET_TRANSFORMATION_SUCCEEDED`
  + `TARGET_STAGE_SUCCEEDED`
+ **`awsRequest`**

  代表傳送至擴充或目標做為 JSON 字串傳送的請求。對於傳送至 API 目的地的要求，這代表傳送至該端點的 HTTP 要求。

  EventBridge 會在擴充和鎖定目標的最後步驟所產生的記錄中包含 `awsRequest` 欄位；也就是說，在 EventBridge 執行或嘗試針對指定的擴充或目標服務執行要求之後。這包括以下步驟︰
  + `ENRICHMENT_INVOCATION_FAILED`
  + `ENRICHMENT_INVOCATION_SUCCEEDED`
  + `TARGET_INVOCATION_FAILED`
  + `TARGET_INVOCATION_PARTIALLY_FAILED`
  + `TARGET_INVOCATION_SUCCEEDED`
+ **`awsResponse`**

  以 JSON 格式表示擴充或目標傳回的回應。對於傳送至 API 目的地的要求，這代表傳送至該端點的 HTTP 要求。

  關於 `awsRequest`，EventBridge 會在擴充和鎖定目標的最後步驟所產生的記錄中包含 `awsResponse` 欄位；也就是說，在 EventBridge 執行或嘗試針對指定的擴充或目標服務執行要求之後。這包括以下步驟︰
  + `ENRICHMENT_INVOCATION_FAILED`
  + `ENRICHMENT_INVOCATION_SUCCEEDED`
  + `TARGET_INVOCATION_FAILED`
  + `TARGET_INVOCATION_PARTIALLY_FAILED`
  + `TARGET_INVOCATION_SUCCEEDED`

如需管道執行步驟的討論，請參閱 [EventBridge Pipes 執行步驟](eb-pipes-logs-execution-steps.md)。

### 截斷 EventBridge 管道日誌中的執行資料
<a name="eb-pipes-logs-execution-data-truncation"></a>

如果您選擇讓 EventBridge 在管道的記錄檔日誌中包含執行資料，則記錄可能會超過 256 KB 的大小限制。為了避免這種情況發生，EventBridge 會依照下列順序自動截斷執行資料欄位。EventBridge 會先完全截斷每個欄位，然後再進行截斷下一個欄位。EventBridge 只要移除資料字串結尾的字元，就會截斷欄位資料；系統不會根據資料重要性進行截斷，而截斷會使 JSON 格式無效。
+ `payload`
+ `awsRequest`
+ `awsResponse`

如果 EventBridge 不會截斷事件中的欄位，則該欄位會包含截斷資料 `truncatedFields` 欄位的清單。

## EventBridge 管道日誌中的錯誤報告
<a name="eb-pipes-logs-errors"></a>

EventBridge 也會在代表失敗狀態的管道執行步驟中包含錯誤資料 (如有)。這些步驟包括：
+ `ExecutionThrottled`
+ `ExecutionTimeout`
+ `ExecutionFailed`
+ `ExecutionPartiallyFailed`
+ `EnrichmentTransformationFailed`
+ `EnrichmentInvocationFailed`
+ `EnrichmentStageFailed`
+ `TargetTransformationFailed`
+ `TargetInvocationFailed`
+ `TargetInvocationPartiallyFailed`
+ `TargetStageFailed`
+ `TargetStagePartiallyFailed`

# EventBridge Pipes 執行步驟
<a name="eb-pipes-logs-execution-steps"></a>

瞭解管道執行步驟的流程可協助您使用日誌進行管道效能的疑難排解或偵錯。

管道接收到的每個事件或一批事件，而該事件傳遞到一個擴充或目標都被視為管道*執行*。如果啟用，EventBridge 會在處理事件批次時為其執行的每個執行步驟產生日誌。

在高層級，執行包含兩個*階段*或步驟集合：擴充和目標。這些階段中的每一個都包含轉換和調用步驟。

成功執行管道的主要步驟如下：
+ 管道執行開始。
+ 如果您已經為事件指定了擴充，則執行會進入擴充階段。如果您尚未指定擴充，執行會繼續到目標階段。

  在擴充階段中，管道會執行您指定的任何轉換，然後調用擴充。
+ 在目標階段中，管道會執行您指定的任何轉換，然後調用目標。

  如果您尚未指定轉換或目標，則執行會略過目標階段。
+ 管執行成功完成。

下圖演示了此流程。發散路徑會格式化為虛線。

![\[管道執行，包括擴充和目標階段，以及轉換和調用步驟。\]](http://docs.aws.amazon.com/zh_tw/eventbridge/latest/userguide/images/pipes-logging-overview_eventbridge_architecture.svg)


下圖顯示了管道執行流程的詳細視圖，並表示了所有可能的執行步驟。發散路徑會格式化為虛線。

如需管道執行步驟的完整清單，請參閱 [指定 EventBridge 管道日誌層級](eb-pipes-logs.md#eb-pipes-logs-level)。

![\[管道執行流程，包括具有所有可能結果的所有階段和步驟。\]](http://docs.aws.amazon.com/zh_tw/eventbridge/latest/userguide/images/pipes-logging-detailed_eventbridge_architecture.svg)


請注意，目標調用可能會導致批次發生部分失敗。如需詳細資訊，請參閱[批次處理行為](eb-pipes-batching-concurrency.md#pipes-batching)。

# EventBridge 管道日誌結構描述參考
<a name="eb-pipes-logs-schema"></a>

下列參考資料詳細說明 EventBridge 管道記錄檔日誌的結構描述。

每個日誌記錄代表一個管道執行步驟，如果管道來源和目標已設定為批次處理，則可能包含多達 10,000 個事件。

如需詳細資訊，請參閱[記錄 Amazon EventBridge 管道效能](eb-pipes-logs.md)。

```
{
    "executionId": "guid",
    "timestamp": "date_time",
    "messageType": "execution_step",
    "resourceArn": "arn:aws:pipes:region:account:pipe/pipe-name",
    "logLevel": "TRACE | INFO | ERROR",
    "payload": "{}",
    "awsRequest": "{}"
    "awsResponse":"{}"
    "truncatedFields": ["awsRequest","awsResponse","payload"],
    "error": {
        "httpStatusCode": code,
        "message": "error_message",
        "details": "",
        "awsService": "service_name",
        "requestId": "service_request_id"
    }
}
```

**executionId**  <a name="pipe-log-schema-execution-id"></a>
管道執行的識別碼。  
管道接收到的每個事件或一批事件，而該事件傳遞到一個擴充或目標都被視為管道執行。如需詳細資訊，請參閱[Amazon EventBridge Pipes 記錄的方式](eb-pipes-logs.md#eb-pipes-logs-overview)。

**timestamp**  <a name="pipe-log-schema-timestamp"></a>
發出日誌事件的日期和時間。  
單位：毫秒。

**messageType**  <a name="pipe-log-schema-message-type"></a>
為其產生記錄的管道執行步驟。  
如需執行步驟的詳細資訊，請參閱 [EventBridge Pipes 執行步驟](eb-pipes-logs-execution-steps.md)。

**resourceArn**  <a name="pipe-log-schema-resource-arn"></a>
管道的 Amazon Resource Name (ARN)。

**logLevel**  <a name="pipe-log-schema-loglevel"></a>
為管道日誌指定的詳細資料層級。  
*有效值*：`ERROR` \$1 `INFO` \$1 `TRACE`  
如需詳細資訊，請參閱[指定 EventBridge 管道日誌層級](eb-pipes-logs.md#eb-pipes-logs-level)。

**payload**  <a name="pipe-log-schema-payload"></a>
管道正在處理的事件批次的內容。  
只有當您指定在此管道的日誌中包含執行資料時，EventBridge 才會包含此欄位。如需詳細資訊，請參閱[在 EventBridge 管道日誌中包含執行資料](eb-pipes-logs.md#eb-pipes-logs-execution-data)  
這些欄位可能包含敏感資訊。在記錄期間，EventBridge 不會嘗試編輯這些欄位的內容。
如需詳細資訊，請參閱[在 EventBridge 管道日誌中包含執行資料](eb-pipes-logs.md#eb-pipes-logs-execution-data)。

**awsRequest**  <a name="pipe-log-schema-aws-request"></a>
以 JSON 格式傳送至擴充或目標服務的要求。對於傳送至 API 目的地的要求，這代表傳送至該端點的 HTTP 要求。  
只有當您指定在此管道的日誌中包含執行資料時，EventBridge 才會包含此欄位。如需詳細資訊，請參閱[在 EventBridge 管道日誌中包含執行資料](eb-pipes-logs.md#eb-pipes-logs-execution-data)  
這些欄位可能包含敏感資訊。在記錄期間，EventBridge 不會嘗試編輯這些欄位的內容。
如需詳細資訊，請參閱[在 EventBridge 管道日誌中包含執行資料](eb-pipes-logs.md#eb-pipes-logs-execution-data)。

**awsResponse**  <a name="pipe-log-schema-aws-response"></a>
以 JSON 格式表示擴充或目標傳回的回應。對於傳送至 API 目的地的要求，這代表從該端點傳回的 HTTP 回應，而不是 API 目的地服務本身傳回的回應。  
只有當您指定在此管道的日誌中包含執行資料時，EventBridge 才會包含此欄位。如需詳細資訊，請參閱[在 EventBridge 管道日誌中包含執行資料](eb-pipes-logs.md#eb-pipes-logs-execution-data)  
這些欄位可能包含敏感資訊。在記錄期間，EventBridge 不會嘗試編輯這些欄位的內容。
如需詳細資訊，請參閱[在 EventBridge 管道日誌中包含執行資料](eb-pipes-logs.md#eb-pipes-logs-execution-data)。

**truncatedFields**  <a name="pipe-log-schema-truncated-fields"></a>
EventBridge 已截斷任何執行資料欄位的清單，以使記錄保持在 256 KB 的大小限制之下。  
如果 EventBridge 不需要截斷任何執行資料欄位，則此欄位仍然存在，除了 `null`。  
如需詳細資訊，請參閱[截斷 EventBridge 管道日誌中的執行資料](eb-pipes-logs.md#eb-pipes-logs-execution-data-truncation)。

**error**  <a name="pipe-log-schema-error"></a>
包含在此管道執行步驟期間產生之任何錯誤的資訊。  
如果在此管道執行步驟期間未產生錯誤，則此欄位存在，除了 `null`。    
**httpStatusCode**  <a name="pipe-log-schema-http-status-code"></a>
被呼叫的服務傳回的 HTTP 狀態碼。  
**message**  <a name="pipe-log-schema-message"></a>
呼叫的服務傳回的錯誤訊息。  
**詳細資訊**  <a name="pipe-log-schema-details"></a>
被呼叫的服務傳回的任何詳細錯誤資訊。  
**awsService**  <a name="pipe-log-schema-aws-service"></a>
被呼叫的服務的名稱。  
**requestId**  <a name="pipe-log-schema-request-id"></a>
被呼叫的服務發出此請求的 ID。

# 使用 Amazon CloudWatch Logs 記錄和監控 Amazon EventBridge 管道
<a name="eb-pipes-monitoring"></a>

您可以使用 CloudTrail 記錄 EventBridge 管道調用，並使用 CloudWatch 指標監控管道的運作狀態。

## CloudWatch 指標
<a name="pipes-monitoring-cloudwatch"></a>

從限流的管道執行到成功調用的目標，EventBridge 管道每分鐘都會傳送指標到 Amazon CloudWatch。


| 指標 | Description | 維度 | 單位 | 
| --- | --- | --- | --- | 
|  `Concurrency`  |  一個管道並行執行的數目。  | AwsAccountId | 無 | 
| `Duration` |  管道執行所花費的時間長度。  | PipeName | 毫秒 | 
|  `EventCount`  |  管道已處理的事件數目。  | PipeName | 無 | 
|  `EventSize`  |  調用管道之事件的有效負載大小。  | PipeName | 位元組 | 
|  `ExecutionThrottled`  |  限流了多少次執行管道。  如果沒有限制執行，則此值將為 `0`。   | AwsAccountId、PipeName | 無 | 
|  `ExecutionTimeout`  |  在完成執行之前，管道的執行有多少次逾時。  如果沒有執行逾時，則此值為 `0`。   | PipeName | 無 | 
|  `ExecutionFailed`  |  有多少管道執行失敗。  如果沒有執行失敗，則此值為 `0`。   | PipeName | 無 | 
|  `ExecutionPartiallyFailed`  |  多少管道執行部分失敗。  如果沒有部分執行失敗，則此值為 `0`。   | PipeName | 無 | 
|  `EnrichmentStageDuration`  |  擴充階段花了多長時間才能完成。  | PipeName | 毫秒 | 
|  `EnrichmentStageFailed`  |  有多少個管道的擴充階段的執行失敗。  如果沒有執行失敗，則此值為 `0`。   | PipeName | 無 | 
| `Invocations` |  調用的總數目。  | AwsAccountId、PipeName | 無 | 
|  `TargetStageDuration`  |  目標階段需要多長時間才能完成。  | PipeName | 毫秒 | 
|  `TargetStageFailed`  |  管道的目標階段執行失敗了多少次。  如果沒有執行失敗，則此值為 `0`。   | PipeName | 無 | 
| `TargetStagePartiallyFailed` | 有多少管道目標階段的執行部分失敗。  如果沒有部分執行失敗，則此值為 `0`。   | PipeName | 無 | 
| `TargetStageSkipped` | 有多少管道目標階段的執行被跳過 (例如，由於擴充返回空的有效負載)。  | PipeName | 計數 | 

## CloudWatch 指標的維度
<a name="pipes-monitoring-cloudwatch-dimensions"></a>

CloudWatch 指標具有*維度*或可排序屬性，如下所示。


|  維度  |  Description  | 
| --- | --- | 
|  AwsAccountId  |  依用戶身分篩選可用的指標。  | 
|  PipeName  |  依管道名稱篩選可用的指標。  |