Copy 活動中的工作階段記錄

適用於： Azure Data Factory Azure Synapse Analytics

提示

Data Factory in Microsoft Fabric 是下一代的 Azure Data Factory，擁有更簡單的架構、內建 AI 及新功能。 如果你是資料整合新手，建議先從 Fabric Data Factory 開始。 現有的 ADF 工作負載可升級至 Fabric，以存取資料科學、即時分析與報告等新能力。

你可以在 複製活動 中記錄你複製的檔案名稱。 這有助於確保資料不僅能從來源成功複製到目的地，還能驗證來源與目的地之間的一致性。

當你在 複製活動 啟用容錯設定以跳過錯誤資料時，跳過的檔案和跳過的列也會被記錄。 您可以從複製活動容錯取得更多詳細資料。

既然你有機會透過啟用會話日誌，讓 Azure Data Factory（ADF）複製活動 複製所有檔案名稱，這在以下情境下會很有幫助：

  • 使用 ADF 複製活動將檔案從一個儲存體複製到另一個儲存體之後，您會在目的地存放區中找到一些非預期的檔案。 你可以掃描 複製活動 的會話日誌，看看到底是哪個活動複製了檔案，以及何時複製。 使用這種方法，您可以輕鬆地找到根本原因，並修正 ADF 中的設定。
  • 使用 ADF 複製活動將檔案從一個儲存體複製到另一個儲存體之後，您會發現複製到目的地的檔案不是來源存放區預期的檔案。 你可以掃描 複製活動 的會話日誌，取得複製作業的時間戳記，以及 ADF Copy 活動從來源儲存讀取檔案時的中繼資料。 使用這種方法，您可以確認 ADF 複製之後，來源存放區上的其他應用程式是否已更新檔案。

使用 Azure Data Factory Studio 進行配置

要設定 Copy 活動紀錄，請先在管線中新增一個 Copy 活動，然後使用其「設定」分頁來設定紀錄及各種紀錄選項。 顯示如何在設定索引標籤中為 Copy 活動設定記錄。

之後若要監視記錄，您可以在 ADF Studio 的 Monitoring 索引標籤中，於管線執行下檢查管線執行的輸出。 在該處選取您想要監視的管線執行，然後將滑鼠停留在 [活動名稱] 旁的區域，您可以在其中找到顯示管線輸入、輸出 (完成之後) 以及其他詳細資料的連結圖示。

示範如何在 ADF Studio 中尋找 複製活動 的輸出。

選取輸出圖示 以查看作業記錄的詳細資料，並記下所選取儲存體帳戶中的記錄位置，您可以在其中查看所有記錄活動的詳細資料。

顯示已啟用記錄功能之複製活動輸出的畫面。

如需記錄輸出格式的詳細資訊，請參閱下方。

使用 JSON 進行設定

下列範例提供 JSON 定義，用以在 Copy Activity 中啟用工作階段記錄：

{
  "name": "CopyActivityLog",
  "type": "Copy",
  "typeProperties": {
    "source": {
      "type": "BinarySource",
      "storeSettings": {
        "type": "AzureDataLakeStoreReadSettings",
        "recursive": true
      },
      "formatSettings": {
        "type": "BinaryReadSettings"
      }
    },
    "sink": {
      "type": "BinarySink",
      "storeSettings": {
        "type": "AzureBlobFSWriteSettings"
      }
    },
    "skipErrorFile": {
      "fileForbidden": true,
      "dataInconsistency": true
    },
    "validateDataConsistency": true,
    "logSettings": {
      "enableCopyActivityLog": true,
      "copyActivityLogSettings": {
        "logLevel": "Warning",
        "enableReliableLogging": false
      },
      "logLocationSettings": {
        "linkedServiceName": {
          "referenceName": "ADLSGen2",
          "type": "LinkedServiceReference"
        },
        "path": "sessionlog/"
      }
    }
  }
}
屬性 說明 允許的值 必要
啟用複製活動日誌 將其設定為 true 時，您有機會記錄複製的檔案、略過的檔案或略過的資料列。 True
False (預設值)		 No
logLevel 「資訊」會記錄所有複製的檔案、略過的檔案和略過的資料列。 「警告」只會記錄略過的檔案和略過的資料列。 資訊
警告 (預設)		 No
啟用可靠記錄功能 當為真時，可靠模式下的 複製活動 會在每個檔案複製到目的地後立即清除日誌。 當在 複製活動 中啟用可靠日誌模式並複製大量檔案時，你應該預期到會影響到系統的吞吐量，因為每個複製的檔案都需要雙重寫入操作。 一個要求會移至目的地存放區，另一個要求則會移至日誌儲存區。 處於最佳努力模式的 Copy 活動，會在一段時間內以記錄批次的方式清除記錄，因此對複製輸送量的影響會小得多。 在此模式下，日誌的完整性和即時性無法保證，因為有幾種可能性是，當 複製活動 失敗時，最後一批日誌事件尚未被刷入日誌檔案。 在此案例中，您會看到一些複製到目的地的檔案未記錄。 True
False (預設值)		 No
記錄位置設定 一組屬性，可用來指定儲存工作階段記錄的位置。 No
linkedServiceName 連結服務 Azure Blob 儲存體 或 Azure Data Lake Storage Gen2 用於儲存會話日誌檔案。 AzureBlobStorage 或 AzureBlobFS 類型連結服務的名稱，指您用來儲存記錄檔的執行個體。 No
路徑 記錄檔的路徑。 指定您想要儲存記錄檔的路徑。 如果不提供路徑，服務會為您建立容器。 No

監視

複製活動的輸出

當 copy activity 完成後，你可以從每次 複製活動 執行的輸出中看到日誌檔案的路徑。 您可以從以下路徑找到記錄檔：https://[your-blob-account].blob.core.windows.net/[logFilePath]/copyactivity-logs/[copy-activity-name]/[copy-activity-run-id]/[auto-generated-GUID].txt。 產生的記錄檔具有 .txt 副檔名，且其資料是 CSV 格式。

"output": {
            "dataRead": 695,
            "dataWritten": 186,
            "filesRead": 3,  
            "filesWritten": 1, 
            "filesSkipped": 2, 
            "throughput": 297,
            "logFilePath": "myfolder/a84bf8d4-233f-4216-8cb5-45962831cd1b/",
            "dataConsistencyVerification": 
           { 
                "VerificationResult": "Verified", 
                "InconsistentData": "Skipped" 
           } 
        }

注意

當 enableCopyActivityLog 屬性設定為 Enabled 時，記錄檔名稱是由系統產生。

記錄檔的結構描述

下表顯示記錄檔的結構描述。

欄位 說明
時間戳記 ADF 讀取、寫入或略過物件時的時間戳記。
層級 此項目的記錄層級。 可以是「警告」或「資訊」。
操作名稱 ADF Copy 活動在每個物件上的作業行為。 可以是 'FileRead'、'FileWrite'、'FileSkip' 或 'TabularRowSkip'。
操作項目 檔案名稱或遭略過的資料列。
訊息 詳細資訊，顯示檔案是否已從來源存放區讀取，或寫入目的地存放區。 這可能是檔案或資料列被略過的原因。

以下是記錄檔的範例：

Timestamp, Level, OperationName, OperationItem, Message
2020-10-19 08:39:13.6688152,Info,FileRead,"sample1.csv","Start to read file: {""Path"":""sample1.csv"",""ItemType"":""File"",""Size"":104857620,""LastModified"":""2020-10-19T08:22:31Z"",""ETag"":""\""0x8D874081F80C01A\"""",""ContentMD5"":""dGKVP8BVIy6AoTtKnt+aYQ=="",""ObjectName"":null}"
2020-10-19 08:39:56.3190846, Warning, FileSkip, "sample1.csv", "File is skipped after read 548000000 bytes: ErrorCode=DataConsistencySourceDataChanged,'Type=Microsoft.DataTransfer.Common.Shared.HybridDeliveryException,Message=Source file 'sample1.csv' is changed by other clients during the copy activity run.,Source=,'." 
2020-10-19 08:40:13.6688152,Info,FileRead,"sample2.csv","Start to read file: {""Path"":""sample2.csv"",""ItemType"":""File"",""Size"":104857620,""LastModified"":""2020-10-19T08:22:31Z"",""ETag"":""\""0x8D874081F80C01A\"""",""ContentMD5"":""dGKVP8BVIy6AoTtKnt+aYQ=="",""ObjectName"":null}"
2020-10-19 08:40:13.9003981,Info,FileWrite,"sample2.csv","Start to write file from source file: sample2.csv."
2020-10-19 08:45:17.6508407,Info,FileRead,"sample2.csv","Complete reading file successfully. "
2020-10-19 08:45:28.7390083,Info,FileWrite,"sample2.csv","Complete writing file from source file: sample2.csv. File is successfully copied."

從上述記錄檔中，您可以看到 sample1.csv 已略過，因為無法驗證其在來源與目的地存放區之間是一致的。 你可以了解有關 sample1.csv 為何變得不一致的更多細節，這是因為當 ADF 複製活動在進行時，其他應用程式同時對它進行了更改。 您也可以看到已成功從來源將 sample2.csv 複製到目的地存放區。

您可以使用多個分析引擎來進一步分析記錄檔。 以下有一些範例可以藉由將 csv 記錄檔匯入到 SQL 資料庫 (其中資料表名稱可以是 SessionLogDemo)，使用 SQL 查詢來分析記錄檔。

  • 提供複製的檔案清單。
select OperationItem from SessionLogDemo where Message like '%File is successfully copied%'
  • 提供在特定時間範圍內複製的檔案清單。
select OperationItem from SessionLogDemo where TIMESTAMP >= '<start time>' and TIMESTAMP <= '<end time>' and Message like '%File is successfully copied%'
  • 提供特定檔案及其複製時間與中繼資料。
select * from SessionLogDemo where OperationItem='<file name>'
  • 請提供在特定時間範圍內被複製的檔案及其中繼資料清單。
select * from SessionLogDemo where OperationName='FileRead' and Message like 'Start to read%' and OperationItem in (select OperationItem from SessionLogDemo where TIMESTAMP >= '<start time>' and TIMESTAMP <= '<end time>' and Message like '%File is successfully copied%')
  • 提供略過的檔案清單。
select OperationItem from SessionLogDemo where OperationName='FileSkip'
  • 提供為何略過特定檔案的原因。
select TIMESTAMP, OperationItem, Message from SessionLogDemo where OperationName='FileSkip'
  • 提供因相同原因「Blob 檔案不存在」而遭略過的檔案清單。
select TIMESTAMP, OperationItem, Message from SessionLogDemo where OperationName='FileSkip' and Message like '%UserErrorSourceBlobNotExist%'
  • 提供需要最長複製時間的檔案名稱。
select top 1 OperationItem, CopyDuration=DATEDIFF(SECOND, min(TIMESTAMP), max(TIMESTAMP)) from SessionLogDemo group by OperationItem order by CopyDuration desc

相關內容

請參閱其他複製活動文章：

  • 上次更新時間：