Copy アクティビティのセッション ログ

適用対象: Azure Data Factory Azure Synapse Analytics

コピーしたファイル名は、Copy アクティビティのログに記録できます。 これはデータがソースからコピー先に正常にコピーされるようにするだけでなく、ソースとコピー先の間の整合性を検証するためにも役立ちます。

Copy アクティビティでフォールト トレランス設定を有効にして、問題のあるデータをスキップした場合は、スキップされたファイルとスキップされた行もログに記録されます。 詳細については、コピー アクティビティのフォールト トレランスに関するページを参照してください。

セッション ログを有効にすることで、Azure Data Factory (ADF) Copy アクティビティによってコピーされたすべてのファイル名を取得する機会がある場合、これは次のシナリオで役立ちます。

  • ADF Copy アクティビティを使用してストレージ間でファイルをコピーしたら、コピー先ストアに予期しないファイルがいくつか見つかりました。 Copy アクティビティのセッション ログをスキャンすると、それらのファイルがどの Copy アクティビティによっていつ実際にコピーされたかを確認できます。 この方法により、ADF 内で簡単に根本原因を見つけて、構成を修正できます。
  • ADF Copy アクティビティを使用してストレージ間でファイルをコピーしたら、コピー先にコピーされたファイルが、予期されたソース ストアのファイルではないことがわかりました。 Copy アクティビティのセッション ログをスキャンすると、コピー ジョブのタイムスタンプと、ADF Copy アクティビティでソース ストアからファイルを読み取ったときのファイルのメタデータを取得できます。 この方法により、ADF によってコピーされた後に、ソース ストアで他のアプリケーションによってファイルが更新されたかどうかを確認できます。

Azure Data Factory Studio での構成

Copy アクティビティのログ記録を構成するには、最初に Copy アクティビティをパイプラインに追加し、その [設定] タブを使用してログ記録とさまざまなログ オプションを構成します。 Shows how to configure logging for a Copy activity in the settings tab.

その後、ログを監視するには、ADF Studio の [監視] タブの [パイプラインの実行] で、パイプラインの実行の出力を確認できます。 そこで、監視するパイプラインの実行を選択し、[アクティビティ名] の横の領域にマウス ポインターを合わせると、パイプラインの入力、出力 (完了した後)、その他の詳細が表示されるリンクへのアイコンが表示されます。

Shows how to find the output of a Copy activity in ADF Studio.

出力アイコン を選択してジョブのログ記録の詳細を表示し、選択したストレージ アカウント内のログの場所をメモします。ここで、ログに記録されたすべてのアクティビティの詳細を確認できます。

Shows the output of a Copy activity with logging enabled.

ログの出力形式の詳細については、以下を参照してください。

JSON を使用した構成

次の例では、コピー アクティビティでセッション ログを有効にする JSON 定義を示します。

"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/"
        }
    }
}
プロパティ 説明 使用できる値 必須
enableCopyActivityLog true に設定すると、コピーされたファイル、スキップされたファイル、またはスキップされた行をログに記録できます。 True
False (既定値)
いいえ
logLevel "Info" により、コピーされたファイル、スキップされたファイル、スキップされた行がすべてログに記録されます。 "Warning" により、スキップされたファイルおよびスキップされた行のみがログに記録されます。 Info
警告 (既定値)
いいえ
enableReliableLogging true の場合、各ファイルがコピー先にコピーされるとすぐに、リライアブル モードの Copy アクティビティによってログがフラッシュされます。 Copy アクティビティでリライアブル ログ モードを有効にして多数のファイルをコピーする場合は、ファイルをコピーするたびに二重書き込み操作が必要になるため、スループットが影響を受けることが予想されます。 1 つの要求はコピー先ストアに送られ、もう 1 つの要求はログ ストレージ ストアに送られます。 ベスト エフォート モードの Copy アクティビティでは、一定期間内のレコードのバッチのログがフラッシュされます。この場合、コピーのスループットへの影響ははるかに少なくなります。 Copy アクティビティが失敗した場合にログ イベントの最後のバッチがログ ファイルにフラッシュされていない可能性があるため、このモードではログ記録の完全性と適時性は保証されません。 このシナリオでは、コピー先にコピーされたいくつかのファイルがログに記録されません。 True
False (既定値)
いいえ
logLocationSettings セッション ログを格納する場所を指定するために使用できるプロパティのグループ。 いいえ
linkedServiceName セッション ログ ファイルを格納するための、Azure Blob Storage または Azure Data Lake Storage Gen2 のリンクされたサービスです。 AzureBlobStorage または AzureBlobFS 型のリンクされたサービスの名前。これは、ログ ファイルを格納するために使用するインスタンスを示します。 いいえ
path ログ ファイルのパス。 ログ ファイルを格納するパスを指定します。 パスを指定しないと、サービスによってコンテナーが作成されます。 いいえ

監視

Copy アクティビティからの出力

Copy アクティビティが完全に実行された後、各 Copy アクティビティの実行の出力からログ ファイルのパスを確認できます。 ログ ファイルは、パス: 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" 
           } 
        }

Note

enableCopyActivityLog プロパティが Enabled に設定されている場合、ログ ファイル名はシステムによって生成されます。

ログ ファイルのスキーマ

次の表は、ログ ファイルのスキーマを示しています。

説明
Timestamp ADF によってオブジェクトの読み取り、書き込み、またはスキップが行われるときのタイムスタンプ。
Level この項目のログ レベル。 "Warning" または "Info" を指定できます。
OperationName 各オブジェクトでの ADF Copy アクティビティの実行動作。 "FileRead"、"FileWrite"、"FileSkip"、または "TabularRowSkip" を指定できます。
OperationItem ファイル名またはスキップされた行。
Message ファイルがコピー元ストアから読み取られたか、またはコピー先ストアに書き込まれたかを示す詳細情報。 また、ファイルまたは行がスキップされている理由を示す場合もあります。

ログ ファイルの例を次に示します。

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 Copy アクティビティによってファイルがコピーされていたのと同時に、他のアプリケーションによってそれが変更されていたためであることがわかります。 また、sample2.csv がコピー元ストアからコピー先ストアに正常にコピーされたことも確認できます。

複数の分析エンジンを使用して、ログ ファイルをさらに分析できます。 次に、csv ログ ファイルを SQL データベースにインポートすることで、SQL クエリを使用してログ ファイルを分析する例をいくつか示します (テーブル名は SessionLogDemo とします)。

  • コピーされたファイル リストを表示する。
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

次のステップ

コピー アクティビティの他の記事を参照してください。