問題の診断

概要

ストリームでは、ランタイム中にエラーが発生することがあります。

  • エラーには、ソース データベースの不正なパスワードなど、回復可能なものもあります。つまり、エラーを修正してストリームを自動的に再開できます。
  • いくつかのエラーには、サポートされないデータ型を含むイベントなど、単一のオブジェクトに影響を与えるものがあります。それ以外のエラーは、Datastream がソース データベースに接続できない場合など、複数のオブジェクトやストリーム全体に影響する可能性があります。
  • DataStream UI の [ストリーム] ページや [ストリームの詳細] ページには、エラーに応じて情報が表示されます。また、データストリームの API を使用してエラーに関する情報を取得することもできます。

エラーのトラブルシューティングを行うには、ストリームに移動してエラーを確認し、エラー メッセージに記載されている手順を行います。

このページでは、構成、接続、Oracle、MySQL のエラーに関する情報と、エラーのトラブルシューティング手順を説明します。

構成エラーと接続エラー

エラー トラブルシューティングの手順
ソース データベースへの接続エラー（全般）。

これには、いくつかの要因が考えられます。このエラーのトラブルシューティングを実施するには、次の操作を行います。

  1. ソース データベースが稼働しており、アクセスできることを確認します。
  2. [ストリーム] ページまたは [接続プロファイル] ページからソースの接続プロファイルに移動します。
  3. 接続プロファイルの接続情報が正しいことを確認します。
  4. ユーザー名とパスワードが一致していることを確認します。
  5. データベースにユーザー名が存在し、必要な権限が付与されていることを確認します。
  6. [接続プロファイル] ページで行った変更を保存します。

ストリームは自動的に再開されます。
ソース データベースへの接続エラー（IP 許可リスト）。 これは、接続方法として IP 許可リストが選択されていても、ソース データベースで Datastream の送信 IP アドレスの 1 つ以上が正しく追加されていないため発生することがあります。Datastream の接続プロファイルに表示される送信 IP アドレスが、ソース データベース サーバーがこれらの IP アドレスからの接続を受け入れるようにネットワーク ファイアウォールで構成されていることを確認します。解決すると、ストリームは自動的に再開されます。
ソース データベースへの接続に失敗しました（フォワード SSH トンネル）。 これは、フォワード SSH トンネルに問題がある場合に発生することがあります。トンネルのステータスを確認してください。トンネルが停止している場合は、開始する必要があります。解決すると、ストリームは自動的に再開されます。
Datastream で、フォワード SSH トンネルを使用して踏み台インスタンスに接続できません。 ソースの接続プロファイルではフォワード SSH トンネル構成が正しく構成され、SSH トンネル サーバーではポートが開かれていることを確認してください。
証明書の問題によるソース データベースへの接続エラー。 これは、ソースの接続プロファイルを定義するときに指定された証明書に問題がある場合に発生することがあります。[接続プロファイル] ページに移動し、目的の接続プロファイルを選択します。証明書が正しく設定されていることを確認します。変更後、接続プロファイルを保存すると、ストリームが自動的に再開します。
プライベート接続を使用したソース データベースへの接続エラー。
  1. 始める前にの条件がすべて揃っていることを確認します。

  2. プライベート接続構成の作成後、データベースの内部 IP アドレスを含むルートが、[VPC ネットワーク ピアリング] ページの [エクスポート済みのルート] タブに現われることを確認します。

    これを行うには、[VPC ネットワーク ピアリング] ページに移動し、追加されたピアリングを検索します（名前は peering-[UUID] です）。ルートは [エクスポート済みのルート] タブで確認できます。このルートが存在しない場合は、手動で追加します。

  3. Datastream は、動的ピアリング ルートとの重複を確認しません。動的ルートと重複するサブネットを指定すると、接続の問題が発生する可能性があります。そのため、動的ルートの一部であるサブネットの使用はおすすめしません。
  4. Datastream IP アドレス範囲のカスタムルートが正しくアドバタイズされていることを確認します。カスタムルートがない場合、カスタム アドバタイズ ルートをご覧ください。
  5. それでもソース データベースへの接続に問題がある場合は、リバース プロキシを設定するをご覧ください。
組織ポリシーの constraints/datastream.disablePublicConnectivity が有効になっていると、接続タイプ STATIC_SERVICE_IP_CONNECTIVITY は使用できません。

作成する接続プロファイルで、パブリック IP 許可リストまたはフォワード SSH トンネル ネットワーク接続方法を選択しましたが、Datastream に対して「パブリック接続方法をブロックする」組織ポリシーが有効になっています。したがって、接続プロファイルにパブリック接続方法は選択できません。

この問題を解決するには、プライベート VPC ピアリング ネットワーク接続方法を選択するか、組織のポリシーを無効にします。

組織のポリシーを無効にするには、次のように操作します。

  1. Google Cloud Console の [組織のポリシー] ページに移動します。
  2. [Datastream - パブリック接続方法のブロック] の組織ポリシーを選択します。

  3. [編集] をクリックします。

  4. ページの [適用先] セクションで、[カスタマイズ] を選択します。

  5. [適用] セクションで、[オフ] を選択します。

  6. [保存] をクリックします。
  7. 作成する Oracle 接続プロファイルに戻り、[作成] をクリックします。
ストリームのソース データベースを設定したときに、転送するテーブルとスキーマが、含めるオブジェクトのリストにありません。

これは、データベースに何千ものテーブルとスキーマがある場合に発生することがあります。Google Cloud コンソールでストリームのソースを構成するときに、pull するオブジェクトのリストに含まれていないものもあります。[含めるオブジェクトを選択] セクションで、[特定のスキーマとテーブル] ではなく、[カスタム] を選択します。[条件に一致するオブジェクト] フィールドに、Datastream に pull するスキーマとテーブルを入力します。
[含めるオブジェクト] メニューを使用して、複数のテーブルをストリームに追加しました。しかし、[ストリームの詳細] の [オブジェクト] タブを見ると、一部のテーブルが欠落していることがわかります。 Datastream が変更を認識し、ストリームにテーブルが自動的に追加されるように、各テーブルに CDC の更新が 1 つ以上あることを確認してください。
Google Cloud コンソールで [含めるオブジェクト] メニューを使用するときにオブジェクトのリストを読み込めませんでした。 これは、データベースに 5,000 を超えるスキーマとテーブルがある場合に発生することがあります。別の方法を使用して含めるオブジェクトを指定するか、Datastream API を使用してください。詳細については、移行元データベースを構成するをご覧ください。
ストリーミング中にドロップされ、宛先で複製されないイベント。

Datastream では、サポートされていないイベントがストリーミング中にドロップされることがあります。問題を解決するには、次の操作を実行します。

  • テーブル全体のバックフィルを手動でトリガーします。これは、破棄されたイベントが UPSERT イベントである場合にのみ機能します。ドロップされたイベントに DELETE イベントが含まれる場合は、バックフィルを実行する前に BigQuery でテーブルを切り捨てる必要があります。

    バックフィルの実行方法については、バックフィルを開始をご覧ください。

  • 部分的にバックフィルを行うよう Google サポートに依頼します。この対応は、SQL 句 WHERE でドロップされたイベントを識別でき、かつ、どのイベントも DELETE イベントではない場合に限り可能です。
  • 破棄されるイベントの数が少ない場合や、破棄されるイベントが重要でない場合は、この問題を無視してください。

Oracle エラー

エラー トラブルシューティングの手順
ソース データベースで、サプリメンタル ロギングが正しく構成されていません。

ソース データベースで補足ロギング構成が正しくない場合、進行中の変更データ キャプチャ（CDC）データの取得でエラーが発生することがあります。補助ロギングが正しく構成されていることを確認します。特に、送信元から送信先にストリーミングされるデータベース テーブルに対して補助ロギングが有効になっていることを確認します。ストリームは自動的に再開されます。
ログの位置が失われているため、レプリケーションを再開できません。 このエラーは、レプリケーション プロセスが長時間一時停止されたときに、ログの位置が失われることによって発生します。ログの保持期間に近づく期間については、ストリームを一時停止しないでください。 ストリームを再作成します。
ログファイルが部分的または完全に欠落しています。

ログファイルが削除された可能性があります。最小ローテーション期間を指定しない限り、Oracle はログファイルを可能な限り早くパージします。 Oracle サーバーで、ログファイルを保持する期間を設定します。たとえば、ログファイルを少なくとも 4 日間保持するには CONFIGURE RETENTION POLICY TO RECOVERY WINDOW OF 4 DAYS; を使用します。

RDS デプロイの場合は、exec rdsadmin.rdsadmin_util.set_configuration('archivelog retention hours',96); を使用します。
除外リストは追加リストを含みます。 追加リストは除外リストに完全に含まれているため、Datastream がソースから取得するオブジェクトのリストは空になります。オブジェクトの選択を変更し、もう一度お試しください。
Oracle データベースのロギングモードが ARCHIVELOG に設定されていません。 ロギングモードを変更してから、再度お試しください。
Datastream から ORA-00942: table or view does not exist エラー メッセージが返されますが、すべてが正しく構成されています。 これは、Oracle サーバー上のキャッシュが原因である可能性があります。データベース ユーザーを再作成すると、キャッシングの問題が解決します。
ストリームがすでに実行中の場合は、Oracle ソースを変更しても宛先に反映されません。 Datastream はアーカイブされた Redo ログファイルから読み取るため、ログがアーカイブされるまで、ソースに加えた変更は宛先に反映されません。宛先の変更を確認するには、ログ アーカイブ ポリシーを変更するか、手動でログスイッチを強制します。詳細については、Oracle データベースの REDO ログファイルを操作するをご覧ください。
予期しない内部エラーがあります。 詳細については、Google サポートまでお問い合わせください。

MySQL エラー

エラー トラブルシューティングの手順
ソース データベースで、バイナリログが正しく構成されていません。

これは、ソース データベースでバイナリログ構成が正しくない場合に、連続する MySQL ストリームで発生する可能性があります。このエラーのトラブルシューティングを実施するには、次の操作を行います。

  1. バイナリログが正しく構成されていることを確認します。
  2. MySQL データベースのバイナリログの形式が、ROW に設定されていることを確認します。
  3. 配信を再開します。
バイナリログの位置が失われているため、レプリケーションを再開できません。 このエラーは、レプリケーション プロセスが長時間一時停止されたときに、バイナリログの位置が失われることによって発生します。バイナリログの保持期間に近づく期間は、ストリームを一時停止しないでください。 ストリームを再作成します。
ソース データベースと宛先データベースのバージョンに互換性がないため、ストリームを実行できません。

この問題は、ソース データベースがバージョン サポート マトリックスに準拠していない場合に発生します。このエラーのトラブルシューティングを実施するには、次の操作を行います。

  1. ソース データベースがマトリックスに準拠するようにします。
  2. 更新されたソース データベースでストリームを再作成します。
AWS RDS MySQL ソース バイナリログが、部分的または完全に失われています。 バイナリログが削除された可能性があります。最小ローテーション期間を指定しない限り、AWS RDS はバイナリログを可能な限り早くパージします。 ソースの AWS RDS MySQL インスタンスで、バイナリログを保持する時間を時間単位で設定します。たとえば、バイナリログを少なくとも 7 日間保持するには mysql.rds_set_configuration('binlog retention hours', 168); を使用します。
除外リストは追加リストを含みます。 追加リストは除外リストに完全に含まれているため、Datastream がソースから取得するオブジェクトのリストは空になります。オブジェクトの選択を変更し、もう一度お試しください。
Datastream が MySQL データベースを複製できません。 データベースを複製する権限が Datastream に付与されていることを確認します。
MySQL ソースの接続プロファイルを作成する際、[暗号化タイプ] メニューで複数の PEM エンコード SSL 証明書が受け入れられません。 Datastream は、MySQL 接続プロファイルでの SSL 証明書チェーンをサポートしていません。x509 PEM でエンコードされた単一の証明書のみがサポートされています。
MySQL ソースからのストリーミング時に高レイテンシになります。

Datastream の機能を強化してソース データベースからの読み取りを可能にします。

  • ソース データベースのバイナリログ（binlog）の最大ファイルサイズを小さくする。サイズを小さくすると、バイナリログ ファイルの数が増加します。
  • 複数のバイナリログ ファイルがある場合は、それに応じてストリームの最大同時 CDC タスク数を設定します。複数のバイナリログ ファイルが存在すると、Datastream は maxConcurrentCdcTasks フィールドに設定された数まで、ソース データベース イベントを同時に読み取ることができます。
予期しない内部エラーがあります。 詳細については、Google サポートまでお問い合わせください。

PostgreSQL エラー

エラー トラブルシューティングの手順
ソース データベースで論理デコードが正しく構成されていません。

論理デコーディングが正しく構成されていることを確認します。ソース PostgreSQL データベースの構成をご覧ください。
レプリケーション スロットが存在しません。 データベースにレプリケーション スロットが存在しない場合、進行中の変更データ キャプチャ（CDC）データの取得中にエラーが発生することがあります。レプリケーション スロットが正しく構成されていることを確認します。ソース PostgreSQL データベースの構成をご覧ください。
レプリケーション スロットが間違ったプラグインで構成されている。 このエラーは、レプリケーション スロットが pgoutput 以外のプラグインで構成されている場合に発生することがあります。レプリケーション スロットが正しく構成されていることを確認します。詳細については、ソース PostgreSQL データベースをご覧ください。
レプリケーション スロットが別のプロセスでアクティブになっている。 このエラーは、レプリケーション スロットが別のプロセスで使用されている場合に発生することがあります。レプリケーション スロットは、一度に 1 つのプロセスでのみ使用できます。Datastream を除く他のプロセスで同じレプリケーション スロットを使用しないようにしてください。
パブリケーションが正しく設定されていません。 このエラーは、ストリーム構成に含まれるテーブルを公開するようにパブリケーションが構成されていない場合に発生することがあります。パブリケーションが正しく設定されていることを確認します。ストリームのソース データベースに関する情報の構成をご覧ください。
パブリケーションが存在しません。 このエラーは、データベースにパブリケーションが存在しない場合などに発生することがあります。パブリケーションが正しく設定されていることを確認します。ソース PostgreSQL データベースの構成をご覧ください。
WAL ファイルが失われているため、レプリケーションを再開できません。 このエラーは、レプリケーション プロセスが長時間一時停止されたときに、WAL ファイルが失われることによって発生します。WAL ファイルの保持期間が近づく期間は、ストリームを一時停止しないでください。ストリームを再作成します。
除外リストは追加リストを含みます。 追加リストは除外リストに完全に含まれているため、Datastream がソースから取得するオブジェクトのリストは空になります。オブジェクトの選択を変更し、もう一度お試しください。
Datastream は PostgreSQL スキーマを複製できません。 データベースを複製する権限が Datastream に付与されていることを確認します。
ソース データベースで大規模なトランザクションが発生すると、データ レプリケーションと同期の問題が発生します。 ソース データベースで大量のレコードを挿入、更新、削除すると、対応するイベントでレプリケーション スロットが過負荷状態になる可能性があります。Datastream には、これらのイベントの読み取りと処理を行う時間が必要になります。PostgreSQL レプリケーション スロットはシングル スレッドであるため、他のテーブルのデータの変更など、レプリケーション スロットの他の変更を処理する場合は、Datastream がレプリケーション スロットのすべての変更に対応できるようになるまで遅延します。
ソース データベースで大規模なトランザクションが発生すると、CDC スループットが低下します。 Datastream は、PostgreSQL のマルチスレッド CDC をサポートしていません。この制限を解決し、CDC のスループットを向上させるには、ソースを複数のストリームに分割し、それぞれが独自のパブリケーションとレプリケーション スロットを持つようにします。たとえば、データベース内の最大のテーブル用に 1 つのストリームを作成し、その他すべてのテーブル用にもう 1 つのストリームを作成する、あるいは、優先度が最も高いテーブル用に 1 つのストリームを作成し、残りのテーブル用にもう 1 つのストリームを作成するといった場合が考えられます。ユースケースはさまざまであるため、特定の CDC シナリオで最も理にかなったものを検討する必要があります。パブリケーションの作成の詳細については、ソース PostgreSQL データベースの構成をご覧ください。
サポートされていないイベントがドロップされました（理由コード: BIGQUERY_TOO_MANY_PRIMARY_KEYS）。 テーブルの PostgreSQL レプリカ ID が FULL に設定されている場合、Datastream は、このテーブル内のすべての列を主キーとして扱います。テーブル内の列数が 16 を超えると、BigQuery CDC の制限に違反し、エラーが発生します。この問題を解決するには、次の手順を完了します。
  1. レプリカ ID を DEFAULT に変更します。
    ALTER TABLE TABLE_NAME REPLICA IDENTITY DEFAULT
     TABLE_NAME は、レプリカ ID を変更するテーブルの名前に置き換えます。
  2. ストリームの対象オブジェクトのリストからテーブルを削除します。詳細については、ソース データベースに関する構成情報を変更するをご覧ください。
  3. BigQuery からテーブルを削除します。詳細については、テーブルを削除するをご覧ください。
  4. Datastream で、ソース構成を編集してテーブルをストリームにもう一度追加します。
予期しない内部エラーがあります。 詳細については、Google サポートまでお問い合わせください。

SQL Server のエラー

エラー トラブルシューティングの手順
データベース DATABASE_NAME の CDC が無効になっています。

データベースに対して変更データ キャプチャ（CDC）を有効にする必要があります。Datastream は、ソース データベースに対する変更をリアルタイムで複製し、完全なログ情報を取得するために、トランザクション ログへの直接読み取りアクセス権を必要とします。データベースの CDC を有効にしてから、もう一度お試しください。

データベースの CDC を有効にする方法については、ソース SQL Server データベースを構成するをご覧ください。
CDC が無効になっているテーブル。

ストリームに含まれるすべてのテーブルに対して、変更データ キャプチャ（CDC）を有効にする必要があります。Datastream は、ソーステーブルに対する変更をリアルタイムで複製し、完全なログ情報を取得するために、トランザクション ログへの直接読み取りアクセス権を必要とします。ストリームに含まれるテーブルの CDC を有効にしてから、もう一度お試しください。

ソーステーブルで CDC を有効にする方法については、ソース SQL Server データベースを構成するをご覧ください。
権限がありません。 ソースからの読み取りに必要な権限が Datastream に付与されていません。データベースへの接続に使用されるユーザー アカウントに適切な権限を付与してから、もう一度お試しください。
SQL Server EDITION_NAME エディションはサポートされていません。 Datastream は、この SQL Server エディションをサポートしていません。SQL Server のサポートされているエディションの詳細については、移行元としての SQL Server の概要をご覧ください。
Standard エディションの SQL Server バージョン VERSION_NAME はサポートされていません。 Datastream は、このバージョンの SQL Server Standard エディションをサポートしていません。サポートされている SQL Server のバージョンの詳細については、ソースとしての SQL Server の概要をご覧ください。
SQL Server CDC の構成: 失敗しました。 選択した CDC メソッドは、データベース構成に準拠していません。CDC メソッドを変更して、もう一度お試しください。

BigQuery エラー

エラー トラブルシューティングの手順
BIGQUERY_UNSUPPORTED_PRIMARY_KEY_CHANGE, details: Failed to write to BigQuery due to an unsupported primary key change: adding primary keys to existing tables is not supported. ソースで主キーが変更された場合は、BigQuery でテーブルを削除し、バックフィルを再度開始する必要があります。これは BigQuery の制限です。主キーが異なる場合、新しいイベントと既存の行を正しく統合する方法はありません。詳細については、BigQuery の宛先を構成するをご覧ください。
宛先 BigQuery テーブルには、ソーステーブルよりもはるかに多くのレコードがあります。 これは、ソーステーブルに主キーがない場合に発生することがあります。この場合、Datastream は追記専用書き込みモードでテーブルを処理し、特定の行の各イベントが BigQuery の個別の行として表示されます。
追加専用書き込みモードでバックフィルを実行すると、データが複製されます。

ストリームに [追加専用] 書き込みモードを選択すると、データは、INSERT、UPDATE-INSERT、UPDATE-DELETE、DELETE のイベントのストリームとして統合されることなく、BigQuery に追加されます。これにより、バックフィルを実行するとき、または問題が発生して BigQuery 書き込みが書き込みオペレーションを再試行するときに、重複する行が BigQuery に書き込まれることがあります。この問題に対処するには、次のような重複除去クエリを定期的に実行することをおすすめします。

SELECT * FROM (SELECT *, row_number() OVER (PARTITION BY datastream_metadata.uuid) AS num FROM TABLE_NAME) WHERE num=1
Datastream がマージ書き込みモードに構成されているが、BigQuery で変更がマージされない。

ソーステーブルに主キーがあることを確認します。BigQuery は、変更を宛先テーブルに統合するためにこのテーブルを必要とします。

主キーがない場合は、ソーステーブルまたは宛先テーブルに主キーを追加することを検討してください。宛先の BigQuery テーブルに主キーを追加する手順は次のとおりです。

  1. ストリーミングを一時停止します。
  2. BigQuery でテーブルを切り捨てます。
  3. テーブル定義に主キーを追加します。
  4. ストリームを再開します。
  5. テーブルのバックフィルをトリガーします。
BigQuery にすでに複製されているテーブルの主キーを追加、削除、変更することはできません。

デフォルトでは、Datastream は、主キーなしで BigQuery にすでに複製されているテーブルに主キーを追加したり、主キーを使用して BigQuery に複製されているテーブルから主キーを削除したりすることはできません。ただし、BigQuery に複製され、すでに主キーがあるソーステーブルの主キー定義は変更できます。

  1. ストリームの合計レイテンシ指標を確認し、少なくとも現在のレイテンシと同じ時間待機して、処理中のイベントが宛先に書き込まれるようにします。これにより、元のプライマリ キーを持つすべてのイベントを正常にストリーミングできます。
  2. ストリーミングを一時停止します。
  3. BigQuery のテーブルの CREATE TABLE データ定義言語（DDL）コマンドをコピーします。
        SELECT ddl FROM PROJECT_ID.DATASET.INFORMATION_SCHEMA.TABLES
      WHERE table_name='TABLE_NAME';

    以下を置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • DATASET_ID: BigQuery 内のデータセットの ID。
    • TABLE_NAME: DDL コマンドをコピーするテーブルの名前。
  4. BigQuery でテーブルを削除します。
  5. 新しい主キーを使用して CREATE TABLE DDL コマンドを調整します。パーティション キーとクラスタキー、max_staleness OPTION を含めます。
        CREATE TABLE `[PROJECT_ID].[DATASET_ID].[TABLE_NAME]`
    (
      product_id INT64 NOT NULL,
      product_name STRING,
      datastream_metadata STRUCT,
      PRIMARY KEY (product_id) NOT ENFORCED
    )
    CLUSTER BY dept_no
    OPTIONS(
      max_staleness=INTERVAL '0-0 0 0:MINS:0' YEAR TO SECOND
    );
    ;

    以下を置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • DATASET_ID: BigQuery 内のデータセットの ID。
    • TABLE_NAME: DDL コマンドをコピーしたテーブルの名前。
    • MINS: max_staleness オプションに設定する分数（15 など）。
  6. 調整したクエリを実行して、BigQuery でテーブルを再作成します。
  7. ストリーミングを再開します。
  8. テーブルのバックフィルを開始します。

次のステップ

  • ライブ配信に関する潜在的な問題を探す方法については、ライブ配信のトラブルシューティングをご覧ください。
  • 移行元データベースの構成方法については、ソースをご覧ください。
  • BigQuery または Cloud Storage の宛先を構成する方法については、リンク先をご覧ください。