移行に関する問題のトラブルシューティング

このドキュメントでは、データ ウェアハウス(Teradata、Amazon Redshift、Oracle、Apache Hive など)を BigQuery に移行する際に発生する一般的な問題のトラブルシューティングについて説明します。移行評価、インタラクティブ SQL トランスレータとバッチ SQL トランスレータ、dwh-migration-dumper コマンドライン抽出ツールを使用したメタデータ生成に関する問題などについて説明します。

移行された クエリとジョブのジョブ実行の詳細、エラーコード、スロット使用状況を調べるには、 INFORMATION_SCHEMA.JOBSビューに対してクエリを実行することもできます。

移行評価

以降のセクションでは、データ ウェアハウスを BigQuery に移行する際の一般的な問題とトラブルシューティング方法について説明します。

dwh-migration-dumper ツールのエラー

メタデータまたはクエリログの抽出中に発生した dwh-migration-dumper ツールのターミナルに出力されるエラーと警告のトラブルシューティングについては、メタデータの生成に関するトラブルシューティングをご覧ください。

Hive 移行のエラー

以降のセクションでは、データ ウェアハウスを Hive から BigQuery に移行する際に発生する可能性のある一般的な問題について説明します。

hadoop-migration-assessment クエリログ抽出ロギングフックは、デバッグ ログメッセージを hive-server2 ログに書き込みます。問題が発生した場合は、MigrationAssessmentLoggingHook という文字列が含まれる、ロギングフックのデバッグログを確認します。

ClassNotFoundException エラーの処理

このエラーは、クエリのコンパイル中に hive-server2 プロセスが com.google.cloud.bigquery.dwhassessment.hooks.MigrationAssessmentLoggingHook を見つけられない場合に発生します。

ロギングフックの JAR ファイルを Hive クラスタの auxlib フォルダに追加したか、hive.aux.jars.path プロパティで JAR ファイルへのフルパスを指定したことを確認します(例: file://AUXLIB_PATH/HiveMigrationAssessmentQueryLogsHooks_deploy.jar)。

エラーが解決しない場合は、次の操作を行います。

  • Cloudera(CDP または CDH)で JAR の場所を確認する: Cloudera 環境では、補助 JAR プロパティ(hive.aux.jars.path)がルートクエリ コンパイル クラスローダーに確実に読み込まれないことがあります。この問題を解決するには、ロギングフックの JAR ファイルをすべての HiveServer2 ホストのコア Hive ライブラリ ディレクトリ(例: /opt/cloudera/parcels/CDH/lib/hive/lib/)に直接コピーします。

  • 構成スコープを確認する: Cloudera Manager を使用する場合は、ロギングフックの構成プロパティ(hive.exec.pre.hooks、hive.exec.post.hooks、hive.exec.failure.hooks、dwhassessment.hook.base-directory など)をアクティブな実行エンジン構成スニペットに配置します。たとえば、クラスタで Tez 実行を使用する場合は、スタンドアロンの HiveServer2 構成スニペットではなく、hive-site.xml の Hive on Tez Advanced Configuration Snippet(Safety Valve)フィールドまたはサービス全体の Hive Safety Valve に XML プロパティを追加します。変更を保存したら、HiveServer2 ロールと Hive Metastore ロールを含む Hive サービスを再起動します。

構成したフォルダにサブフォルダが表示されない

この問題は、構成ミスやロギングフックの初期化中の問題が原因で発生する可能性があります。

hive-server2 デバッグログで、次のロギングフック メッセージを検索します。

Unable to initialize logger, logging disabled
Log dir configuration key 'dwhassessment.hook.base-directory' is not set,
logging disabled.
Error while trying to set permission

問題の詳細を確認し、問題を解決するために修正が必要な点があるかどうかを確認します。

ファイルがフォルダに表示されない

この問題は、イベント処理中またはファイルへの書き込み中に発生した問題が原因で発生する可能性があります。

hive-server2 デバッグログで、次のロギングフック メッセージを検索します。

Failed to close writer for file
Got exception while processing event
Error writing record for query

問題の詳細を確認し、問題を解決するために修正が必要な点があるかどうかを確認します。

一部のクエリイベントが欠落している

この問題は、ロギングフックのスレッドキューのオーバーフローが原因で発生する可能性があります。

hive-server2 デバッグログで、次のロギングフック メッセージを検索します。

Writer queue is full. Ignoring event

このメッセージが表示された場合は、dwhassessment.hook.queue.capacity パラメータの値を増やすことを検討してください。

インタラクティブ SQL トランスレータ

以降のセクションでは、インタラクティブ SQL トランスレータの使用時によく発生するエラーについて説明します。

RelationNotFound または AttributeNotFound 変換の問題

インタラクティブ SQL トランスレータを使用してクエリを変換すると、 変換が失敗することがあります。 RelationNotFound または AttributeNotFound エラーが発生する可能性があります。

失敗した変換を確認するには、BigQuery の [変換の詳細] ページ に移動し、コンソールの Google Cloud [ログメッセージ] タブを開きます。

最も正確な変換ができるように、クエリ自体の前にクエリで使用されるテーブルのデータ定義言語(DDL)ステートメントを入力できます。たとえば、Amazon Redshift クエリ select table1.field1, table2.field1 from table1, table2 where table1.id = table2.id; を変換する場合は、次の SQL ステートメントをインタラクティブ SQL トランスレータに入力します。

create table schema1.table1 (id int, field1 int, field2 varchar(16));
create table schema1.table2 (id int, field1 varchar(30), field2 date);

select table1.field1, table2.field1
from table1, table2
where table1.id = table2.id;

Gemini を使用して変換の問題を修正する

RelationNotFound エラーまたは AttributeNotFound エラーで失敗した変換ジョブを修正するには、Gemini を使用して次の問題を解決します。

  1. コンソールの Google Cloud BigQuery で、 [変換の詳細] ページに移動し、[ログメッセージ] タブを開きます。
  2. [カテゴリ] 列に RelationNotFound または AttributeNotFound というメッセージが表示されているクエリをクリックします。
  3. [修正候補] をクリックします。
  4. [適用] をクリックします。
  5. クエリを再変換するには、[変換] をクリックします。

バッチ SQL トランスレータ

以降のセクションでは、バッチ SQL トランスレータの使用時によく発生するエラーについて説明します。

RelationNotFound または AttributeNotFound 変換の問題

バッチ SQL トランスレータを使用してクエリを変換すると、 変換が失敗し、 RelationNotFound または AttributeNotFound エラーが発生することがあります。

失敗した変換を確認するには、 Google Cloud コンソールの BigQuery の [変換の詳細] ページ に移動し、[ログメッセージ] タブを開きます。

変換はメタデータ DDL で最適に動作します。SQL オブジェクト定義が見つからない場合は、変換エンジンで RelationNotFound または AttributeNotFound の問題が発生します。メタデータ抽出を使用してメタデータ パッケージを生成し、すべてのオブジェクト定義が存在するようにすることをおすすめします。メタデータの追加は、ほとんどの変換エラーを解決するための推奨される最初の手順です。この手順では、メタデータの不足が間接的に原因となる他の多くのエラーが修正されることがよくあります。

詳細については、 変換と評価のためのメタデータを生成するをご覧ください。

Gemini を使用して変換の問題を修正する

RelationNotFound エラーまたは AttributeNotFound エラーで失敗した変換ジョブを修正するには、Gemini を使用して次の問題を解決します。

  1. [変換の詳細] ページに移動し、[ログメッセージ] タブを開きます。
  2. [カテゴリ] 列に RelationNotFound または AttributeNotFound というメッセージが表示されているクエリをクリックします。
  3. コードタブでエラーを含むファイルと行に移動するには、

    エラー メッセージをクリックします。

  4. [アクション] 列で [修正候補] をクリックします。

  5. 次のいずれかのオプションを選択します。[適用] または [適用して再実行]。

    • 生成されたスキーマ ファイルを出力ディレクトリから入力ディレクトリにコピーするには、[適用] をクリックします。
    • 生成されたスキーマ ファイルを出力ディレクトリから入力ディレクトリにコピーして再実行ウィンドウを開くには、[適用して再実行] をクリックします。

変換と評価のためのメタデータを生成する

以降のセクションでは、dwh-migration-dumper ツールの一般的な問題とトラブルシューティング方法について説明します。

メモリ不足エラー

dwh-migration-dumper ツールのターミナル出力での java.lang.OutOfMemoryError エラーは、多くの場合、取得したデータを処理するためのメモリ不足に関連しています。この問題に対処するには、使用可能なメモリを増やすか、処理スレッドの数を減らします。

JAVA_OPTS 環境変数をエクスポートすると、最大メモリを増やすことができます。

Linux

export JAVA_OPTS="-Xmx4G"

Windows

set JAVA_OPTS="-Xmx4G"

--thread-pool-size フラグの値を含めると、処理スレッドの数(デフォルトは 32)を減らすことができます。このオプションは、hiveql コネクタと redshift* コネクタでのみサポートされています。

dwh-migration-dumper --thread-pool-size=1

WARN...Task failed エラーの処理

dwh-migration-dumper ツールのターミナル出力に WARN [main] o.c.a.d.MetadataDumper [MetadataDumper.java:107] Task failed: … エラーが表示されることがあります。抽出ツールは複数のクエリをソースシステムに送信し、各クエリの出力が独自のファイルに書き込まれます。この問題は、これらのクエリのいずれかが失敗したことを示します。ただし、1 つのクエリが失敗しても、他のクエリの実行は妨げられません。WARN エラーが複数表示される場合は、問題の詳細を確認し、クエリが適切に実行されるように修正が必要な点があるかどうかを確認します。たとえば、抽出ツールを実行したときに指定したデータベース ユーザーにすべてのメタデータを読み取る権限がない場合は、適切な権限を持つユーザーで再試行してください。

破損した ZIP ファイル

dwh-migration-dumper ツールの ZIP ファイルを検証するには、 SHA256SUMS.txt ファイル をダウンロードして、次のコマンドを実行します。

Bash

sha256sum --check SHA256SUMS.txt

OK という結果は、チェックサムの検証が成功したことを示します。他のメッセージは検証エラーを示します。

  • FAILED: computed checksum did NOT match: ZIP ファイルが破損しているため、再度ダウンロードする必要があります。
  • FAILED: listed file could not be read: ZIP ファイルのバージョンが見つかりません。チェックサム ファイルと ZIP ファイルを同じリリース バージョンからダウンロードし、同じディレクトリに配置します。

Windows PowerShell

(Get-FileHash RELEASE_ZIP_FILENAME).Hash -eq ((Get-Content SHA256SUMS.txt) -Split " ")[0]

RELEASE_ZIP_FILENAME は、dwh-migration-dumper コマンドライン抽出ツールのリリースのダウンロード済み ZIP ファイル名に置き換えます(例: dwh-migration-tools-v1.0.52.zip)。

True という結果は、チェックサムの検証が成功したことを示します。

False という結果は検証エラーを示します。チェックサム ファイルと ZIP ファイルを同じリリース バージョンからダウンロードし、同じディレクトリに配置します。

Teradata のクエリログの抽出が遅い

-Dteradata-logs.query-logs-table フラグと -Dteradata-logs.sql-logs-table フラグで指定されたテーブルの結合のパフォーマンスを向上させるには、JOIN 条件に DATE 型の列を追加します。この列は両方のテーブルで定義する必要があり、パーティション プライマリ インデックスの一部である必要があります。この列を含めるには、-Dteradata-logs.log-date-column フラグを使用します。

次の例は、-Dteradata-logs.log-date-column フラグの使用方法を示しています。

Bash

dwh-migration-dumper \
  -Dteradata-logs.query-logs-table=historicdb.ArchivedQryLogV \
  -Dteradata-logs.sql-logs-table=historicdb.ArchivedDBQLSqlTbl \
  -Dteradata-logs.log-date-column=ArchiveLogDate

Windows PowerShell

dwh-migration-dumper `
  "-Dteradata-logs.query-logs-table=historicdb.ArchivedQryLogV" `
  "-Dteradata-logs.sql-logs-table=historicdb.ArchivedDBQLSqlTbl" `
  "-Dteradata-logs.log-date-column=ArchiveLogDate"

Teradata の行サイズの上限を超えている

Teradata バージョン 15 の行サイズの上限は 64 KB です。上限を超えると、抽出ツールが失敗し、次のメッセージが表示されます。

[Error 9804] [SQLState HY000] Response Row size or Constant Row size overflow

このエラーを解決するには、行の上限を 1 MB に拡張するか、行を複数行に分割します。

  • 1 MB Perm と Response Rows 機能および最新の TTU ソフトウェアをインストールして有効にします。詳細については、 Teradata Database Message 9804をご覧ください。
  • -Dteradata.metadata.max-text-length フラグと -Dteradata-logs.max-sql-length フラグを使用して、長いクエリテキストを複数の行に分割します。

次のコマンドは、-Dteradata.metadata.max-text-length フラグを使用して、長いクエリテキストを最大 10,000 文字の複数の行に分割する方法を示しています。

Bash

dwh-migration-dumper \
  --connector teradata \
  -Dteradata.metadata.max-text-length=10000

Windows PowerShell

dwh-migration-dumper `
  --connector teradata `
  "-Dteradata.metadata.max-text-length=10000"

次のコマンドは、-Dteradata-logs.max-sql-length フラグを使用して、長いクエリテキストを最大 10,000 文字の複数の行に分割する方法を示しています。

Bash

dwh-migration-dumper \
  --connector teradata-logs \
  -Dteradata-logs.max-sql-length=10000

Windows PowerShell

dwh-migration-dumper `
  --connector teradata-logs `
  "-Dteradata-logs.max-sql-length=10000"

Oracle への接続に関する問題

無効なパスワードやホスト名などのよくあるケースでは、dwh-migration-dumper ツールは根本的な問題について説明する有用なエラー メッセージを出力します。ただし、Oracle サーバーから返されるエラー メッセージが一般的な内容で、調査が困難な場合があります。

そのような問題の一つが IO Error: Got minus one from a read call です。このエラーは、Oracle サーバーへの接続が確立されたものの、サーバーがクライアントを受け入れずに接続を閉じたことを示します。 この問題は通常、サーバーが TCPS 接続のみを受け入れる場合に発生します。デフォルトでは、dwh-migration-dumper ツールは TCP プロトコルを使用します。この問題を解決するには、Oracle JDBC 接続 URL をオーバーライドする必要があります。

oracle-service、host、port フラグを指定する代わりに、 url フラグを次の形式で指定してこの問題を解決できます: jdbc:oracle:thin:@tcps://HOST_NAME:PORT/ORACLE_SERVICE。 通常、Oracle サーバーで使用される TCPS ポート番号は 2484 です。

次の例は、コマンドで接続 URL を指定する方法を示しています。

dwh-migration-dumper \
  --connector oracle-stats \
  --url "jdbc:oracle:thin:@tcps://HOST_NAME:PORT/ORACLE_SERVICE" \
  --assessment \
  --driver "JDBC_DRIVER_PATH" \
  --user "USER" \
  --password

接続プロトコルを TCPS に変更するだけでなく、Oracle サーバー証明書の検証に必要な trustStore SSL 構成を指定することが必要になる場合もあります。SSL 構成がない場合は、Unable to find valid certification path エラー メッセージが表示されます。この問題を解決するには、JAVA_OPTS 環境変数を設定します。

set JAVA_OPTS=-Djavax.net.ssl.trustStore="JKS_FILE_LOCATION" -Djavax.net.ssl.trustStoreType=JKS -Djavax.net.ssl.trustStorePassword="PASSWORD"

Oracle サーバー構成によっては、keyStore 構成も指定する必要がある場合があります。構成オプションの詳細については、 Oracle JDBC シンドライバを使用した SSLをご覧ください。

次のステップ