問題のトラブルシューティング

ワークフローの使用中に問題が発生した場合に役立つトラブルシューティングの方法について説明します。

デプロイエラー

ワークフローがデプロイされると、Workflows により、ソースコードにエラーがなく、言語構文と一致することが確認されます。 Workflows によりエラーが検出された場合は、エラーが返されます。最も一般的な種類のデプロイエラーは、次のとおりです。

  • 未定義の変数、ステップ、サブワークフローの参照
  • 不適切な構文
    • 不適切なインデント
    • {}"-: の欠落、または無関係なものがある

たとえば、次のソースコードはデプロイ エラーをスローします。これは、return 文で未定義の変数 varC が参照されるためです。

- step1:
    assign:
    - varA: "Hello"
    - varB: "World"
- step2:
    return: ${varC + varB}

この間違ったソースコードは、次の Google Cloud Console と Cloud SDK のサンプルで使用されています。

Console

デプロイエラーが発生した場合、ワークフローではソースコードの上に、赤いバナー内にエラー メッセージが表示されます。

デプロイエラー

エラー メッセージは、可能であればエラーの原因を指定して、ソースコードの問題を報告します。

Could not deploy workflow: failed to build: error in step step2: error
evaluating return value: symbol 'varC' is neither a variable nor a
sub-workflow name (Code: 3)

gcloud

gcloud workflows deploy コマンドを実行すると、デプロイが失敗した場合、Workflows はコマンドラインにエラー メッセージを返します。エラー メッセージは、可能であればエラーの原因を指定して、ソースコードの問題を報告します。

ERROR: (gcloud.workflows.deploy) [INVALID_ARGUMENT] failed to build:
error in step step2: error evaluating return value: symbol 'varC' is neither
a variable nor a sub-workflow name

この問題を解決するには、ワークフローのソースコードを編集します。この場合は、varC ではなく varA を参照してください。

コロンを含む式

YAML でコロンを含む式を使用すると、コロンがマップの定義と解釈されたときに予期しない動作が発生する可能性があります。ワークフローをデプロイして実行することは可能ですが、想定どおりに出力されません。

Google Cloud Console を使用してワークフローを作成すると、ワークフローを Cloud Console で視覚的にレンダリングできず、次のような警告が表示されることがあります。

ワークフロー作成の警告

この問題を解決するには、YAML 式を単一引用符で囲みます。

推奨: '${"a: " +string(a)}'

おすすめしません ${"a: " +string(a)}

ワークフローのデプロイログと削除ログにアクセスする

ワークフローのデプロイと削除に関するエラーログには、Cloud Console でアクセスできます。

  1. Cloud Console の [Workflows] ページに移動します。
    [Workflows] に移動

  2. ワークフローの名前をクリックして、[ワークフローの詳細] ページを表示します。

  3. [Logs] タブをクリックします。

  4. 重大度でログをフィルタするには、[デフォルト] リストで、表示するログのタイプを選択します。

ワークフローの実行結果にアクセスする

ワークフローの実行結果には、Cloud Console または Cloud SDK を使用してアクセスできます。

Console

  1. Cloud Console の [Workflows] ページに移動します。
    [Workflows] に移動

  2. ワークフローの実行結果にアクセスするには、ワークフローの名前をクリックして [詳細] ページに移動します。

  3. 特定の実行の詳細を確認するには、リスト内の実行 ID をクリックします。実行ごとに次の情報が含まれます。

    • 実行の状態: ワークフローの終了状態を示します。
    • 実行開始: 実行が開始された日時。
    • 実行終了: 実行が終了した日時。
    • 実行期間: 合計経過時間。これは、ネットワーク エラーまたは接続の問題を示す場合があります。
    • 出力: ワークフローの出力。実行が失敗した場合は、実行の失敗の原因となる例外が含まれます。詳細については、実行エラー メッセージのセクションをご覧ください。
    • 入力: ワークフローに渡されるランタイム引数(存在する場合)。
  4. ワークフローの実行のすべてのログを表示するには、[ログ] をクリックして [ログ] タブを開きます。

  5. 実行ログをフィルタするには、テーブルの上部にある [フィルタ] フィールドを使用します。たとえば、失敗した実行の試行のみを表示するには、フィルタのテキスト フィールドに「failed」を入力します。

    実行ログをフィルタする

gcloud

  1. ワークフローの実行の完全なリストを確認するには、次のコマンドを入力します。

    gcloud workflows executions list WORKFLOW-NAME
    

    WORKFLOW-NAME は、ワークフローの名前に置き換えます。 目的の実行の実行 ID をコピーします。

  2. ワークフローの実行ログを表示するには、次のコマンドを入力します。

    gcloud workflows executions describe \
    --workflow=WORKFLOW-NAME \
    EXECUTION-ID
    

    次のように置き換えます。

    • WORKFLOW-NAME: ワークフローの名前
    • EXECUTION-ID: 実行の一意の ID

このコマンドは、次のような出力を返します。

argument: '{"message":"I love it so much!"}'
endTime: '2020-07-21T17:48:16.438109757Z'
error: 'in step "sentimentCheck": {"message":"KeyError: key not found: messaage","tags":["KeyError","LookupError"]}'
name: projects/********/locations/us-central1/workflows/sentimentCheck/executions/e8103c53-72ba-4af7-8996-f5a8337c2a7
startTime: '2020-10-12T17:48:16.342177302Z'
state: FAILED
workflowRevisionId: '000009-e6d'

出力には次の情報が含まれます。

  • argument: ワークフローに渡されるランタイム引数(存在する場合)。
  • endTime: 実行が終了した日時。
  • error: 実行の失敗につながった例外の一部としてスローされたエラー メッセージ。
  • name: 実行の完全な名前(プロジェクトの名前、ワークフローのロケーション、ワークフローの名前、実行 ID を含む)。
  • startTime: 実行が開始された日時。
  • state: ワークフローの終了状態を示します
  • workflowRevisionID: 実行時点でのリビジョン。

実行エラー メッセージ

ワークフローが実行中に、try / except ブロックでキャッチされないエラーをスローする場合、実行は失敗し、エラーを説明するマップが返されます。

ワークフローの実行中にスローされたエラーには、エラーの原因を特定するためのタグが含まれています。次の表は、さまざまなエラータグの意味を説明したものです。

エラータグ 説明
AuthError HTTP リクエストの認証情報の生成が失敗した場合に送出されます。
ConnectionError API エンドポイントに接続できない場合に発生します。たとえば、ドメイン名の誤り、DNS の解決の問題、その他のネットワークの問題などが考えられます。
HttpError HTTP エラー ステータスで HTTP リクエストが失敗した場合に発生します。この例外が発生すると、レスポンスは次の要素を含むマップになります。
  • tags - HttpError 文字列を含むリスト
  • message: 人が読めるエラー メッセージ
  • code - HTTP レスポンス ステータス コード
  • headers - レスポンス ヘッダー
  • body - レスポンスの本文
IndexError シーケンス サブスクリプトが範囲外の整数である場合に発生します。
KeyError 既存のキーのセットにマップキーが見つからない場合に発生します。
RecursionError 最大再帰回数を超えることをインタープリタが検出した場合に発生します。
ResourceLimitError 一部のリソースを上限まで使い切った場合に発生します。内部で発生すると、このタイプのエラーはキャッチされず、すぐに実行は失敗します。
SystemError インタープリタで内部エラーを検出した場合に発生します。
TimeoutError システム関数がシステムレベルでタイムアウトした場合に発生します。
TypeError オペレーションまたは関数が互換性のないタイプのオブジェクトに適用された場合に発生します。関連する値は、タイプの不一致の詳細を示す文字列です。
ValueError オペレーションまたは関数が、型は適切ですが、値が正しくない引数を受け取った場合で、「IndexError」などの、より厳密な例外で状況が説明されない場合に発生します。
ZeroDivisionError 除算または剰余演算の 2 番目の引数がゼロの場合に発生します。関連する値は、演算対象のタイプと演算を示す文字列です。

raise 構文を使用してカスタムエラーを発生させることもできます。

長時間実行のステータスを確認する

ワークフロー実行のステータスの確認に役立つコマンドがいくつかあります。

  • ワークフロー実行の試行とその ID のリストを取得するには、次のコマンドを入力します。

    gcloud workflows executions list WORKFLOW_NAME
    

    WORKFLOW_NAME はワークフローの名前で置き換えます。

  • 実行の試行のステータスを確認し、試行が完了するまで待機するには、次のコマンドを入力します。

    gcloud workflows executions wait EXECUTION_ID
    

    EXECUTION_ID を実行の試行 ID に置き換えます。

    このコマンドは、実行の試行の完了を待ってから、結果を返します。

  • 前回の実行の試行のステータスを確認するには、次のコマンドを入力します。

    gcloud workflows executions wait-last
    

    同じ gcloud セッションで以前の実行を試行した場合、コマンドは、以前の実行の試行を待ってから、結果を返します。以前の試行が存在しない場合、gcloud は次のエラーを返します。

    ERROR: (gcloud.workflows.executions.wait-last) [NOT FOUND] There are no cached executions available.
    
  • 最後に完了した実行のステータスを取得するには、次のコマンドを入力します。

    gcloud workflows executions describe-last
    

    同じ gcloud セッションで以前の実行を試行した場合、コマンドは最後に完了した実行の結果を返します。以前の試行が存在しない場合、gcloud は次のエラーを返します。

    ERROR: (gcloud.beta.workflows.executions.describe-last) [NOT FOUND] There are no cached executions available.
    

Cloud Logging にログを送信する

ワークフローは、Cloud Logging でのワークフロー実行の実行ログを自動的に生成します。

コールロギングを有効にすることもできます。または、ソースで sys.log 関数を使用するカスタムログを作成できます。コールロギングとカスタムログを使用すると、ワークフローの実行中にログが Logging に送信されるタイミングを制御できます。特に、ワークフローをデバッグする際に便利です。

engine_call および executions_system ロギング proto ファイルなどの詳細については、この GitHub リポジトリをご覧ください。

実行ログ

ワークフローが実行されるたびに、少なくとも 2 つの実行ログ(実行の開始時と終了時に 1 つずつ)が自動的にトリガーされます。

Logging で使用可能な Workflows プラットフォームのログの詳細については、Google Cloud Platform のログをご覧ください。

コールロギング

フラグを設定して、ワークフローの実行中に各呼び出しステップがログに記録され、ステップ名、関数名、関数引数、呼び出しレスポンスが返されます。または、呼び出しを停止した例外をログに記録することもできます。

明示的な呼び出しステップのみがログに記録されます。たとえば、サブワークフローやライブラリ関数の呼び出しです。式内または標準ライブラリ関数(sys.loghttp.post など)とコネクタ内部からの呼び出しはログに記録されません。

コールロギングを適用するには、Google Cloud Console または gcloud コマンドライン ツールを使用します。

Console

  1. Google Cloud Console の [ワークフロー] ページに移動します。
    ワークフローに移動

  2. [ワークフロー] ページで、ワークフローを選択して詳細ページに移動します。

  3. [ワークフローの詳細] ページで [ 実行] を選択します。

  4. 必要に応じて、[ワークフローの実行] ページで、ワークフローの実行中に適用するコールロギングのレベルを指定できます。

    [ログ呼び出し] プルダウン リストで、次のいずれかを選択します。

    • none: 通話ロギングなし。これがデフォルトのレベルです。
    • log-all-calls: サブワークフローまたはライブラリ関数のすべての呼び出しとその結果をログに記録します。
    • log-errors-only: 例外のために呼び出しが停止した場合にのみログに記録されます。
  5. [実行] をクリックします。

gcloud

ワークフローを実行し、実行が完了するまで待機するには、次のコマンドを入力します。

gcloud workflows run WORKFLOW_NAME \
    --call-log-level=CALL_LOGGING_LEVEL \
    --data=DATA

実行の試行を待たずにワークフローを実行するには、次のコマンドを入力します。

gcloud workflows execute WORKFLOW_NAME \
    --call-log-level=CALL_LOGGING_LEVEL \
    --data=DATA

次のように置き換えます。

  • WORKFLOW_NAME: ワークフローの名前。
  • CALL_LOGGING_LEVEL: 省略可。実行中に適用する通話ロギングのレベル。次のいずれか 1 つを設定できます。
    • none: 通話ロギングなし。これがデフォルトのレベルです。
    • log-all-calls: サブワークフローまたはライブラリ関数のすべての呼び出しとその結果をログに記録します。
    • log-errors-only: 例外のために呼び出しが停止した場合にのみログに記録されます。
  • DATA: 省略可。ワークフローのランタイム引数(JSON 形式)。

カスタムログ

ワークフローの実行中に Logging でログエントリを作成するには、標準ライブラリ sys.log 関数を呼び出すステップをワークフローに定義します。

YAML

  - step1:
      assign:
          - varA: "Hello"
          - varB: "World"
  - logStep:
      call: sys.log
      args:
          text: TEXT
          severity: SEVERITY 
  - step2:
      return: ${varA + " " + varB}
    

JSON

    [
      {
        "step1": {
          "assign": [
            {
              "varA": "Hello"
            },
            {
              "varB": "World"
            }
          ]
        }
      },
      {
        "logStep": {
          "call": "sys.log",
          "args": {
            "text": "TEXT",
            "severity": "SEVERITY"
          }
        }
      },
      {
        "step2": {
          "return": "${varA + " " + varB}"
        }
      }
    ]
      

ログエントリの作成時に、以下を定義します。

  • TEXT: 必須。ログに記録されるテキスト。マップの値をログに記録する必要がある場合は、${json.encode_to_string(myMap)} を使用します。
  • SEVERITY: 省略可。ログエントリの重大度。たとえば、INFOWARNINGCRITICAL などです。

詳細については、sys.log 関数リファレンスをご覧ください。

必要な権限

コールロギングを適用するか、カスタムログを Logging に送信するには、logging.logEntries.create 権限(たとえば、roles/logging.logWriter ロール)を含むサービス アカウントにワークフローを関連付ける必要があります。ワークフローでサービス アカウントを最新に変更する必要がある場合は、ワークフローの更新をご覧ください。サービス アカウントの作成とロールの割り当てに関する詳細は、プロジェクト、フォルダ、組織へのアクセスの管理をご覧ください。

ワークフローのログを表示する

ログは、ワークフローかロギングに表示できます。1 つのワークフローのログを表示するには、ワークフローで [ログ] タブを使用します。すべてのワークフローのログの集計ビューを取得するには、ロギングの [ログ エクスプローラ] ページを使用します。

Workflows でログを表示する

ワークフローでワークフローのログを表示するには:

  1. Cloud Console の [Workflows] ページに移動します。
    [Workflows] に移動

  2. ワークフローのログにアクセスするには、ワークフローの名前をクリックして [詳細] ページに移動します。

  3. ログを表示するには、[ログ] をクリックします。

  4. 重大度でログをフィルタするには、[デフォルト] リストで、表示するログのタイプを選択します。デフォルトでは、すべての重大度のログが表示されます。

ワークフローの [詳細] ページの [ログ] タブに、次のタイプのログが表示されます。

  • Logging に送信されるログ

  • ワークフローの定義の更新など、ワークフローで実行されるオペレーションの監査ログ

Logging でログを表示する

Logging でログを表示するには:

  1. Cloud Console の [ログ エクスプローラ] ページに移動します。
    ログ エクスプローラに移動する

  2. クエリビルダーで、[リソース] をクリックして「workflow」と入力します。リストから [Cloud Workflow] を選択し、[Add] をクリックします。

    ワークフローのロギング

  3. [実行] をクリックします。

Logging でログを表示する方法の詳細については、ログ エクスプローラの使用をご覧ください。