ワークフローをモニタリングする

このページでは、ワークフローのデプロイと実行のモニタリングに役立つ情報を提供します。

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

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

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

    [ワークフロー] に移動

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

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

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

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

ワークフローの実行結果には、Cloud コンソールで、または gcloud CLI を使用してアクセスできます。

コンソール

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

    [ワークフロー] に移動

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

  3. 特定の実行の詳細を確認するには、[実行] タブでリスト内の実行 ID をクリックして、[実行の詳細] ページに移動します。

  4. [Summary] タブでは、実行ごとに次の情報が表示されます。

    • 実行の状態: 現在または最後のワークフロー ステップを含むワークフローの終了状態を示します。
    • 実行開始: 実行が開始された日時。
    • 実行終了: 実行が終了した日時。
    • 実行期間: 合計経過時間。これは、ネットワーク エラーまたは接続の問題を示す場合があります。
    • ワークフロー名: ワークフローの名前。
    • ワークフロー リビジョン: 実行時点での現在のリビジョン。
    • コールロギング レベル: 実行中に適用されるコールロギングのレベル。このドキュメントでは、コールロギングをご覧ください。
    • 入力: ワークフローに渡されるランタイム引数(存在する場合)。
    • 出力: ワークフローの出力。実行が失敗した場合は、実行の失敗の原因となる例外が含まれます。このドキュメントでは、実行のエラー メッセージをご覧ください。
  5. ワークフローの実行履歴をステップ エントリのリストとして表示するには、[ステップ] タブをクリックします。詳細については、実行ステップの履歴を表示するをご覧ください。

  6. ワークフローの実行のログを表示するには、[ログ] タブをクリックします。

  7. 実行ログをフィルタするには、テーブルの上部にある [フィルタ] フィールドを使用します。たとえば、失敗した実行の試行のみを表示するには、フィルタのテキスト フィールドに「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: 'null'
    endTime: '2022-07-19T12:40:07.070039707Z'
    error:
     context: |-
        The argument of 'in' must be a dict or an array; got: null
        in step "checkSearchTermInInput", routine "main", line: 12
     payload: "{"message":"The argument of 'in' must be a dict or an array; got: null"
    ,"tags":["TypeError"]}" stackTrace: elements: - position: column: '26' length: '24' line: '12' routine: main step: checkSearchTermInInput name: projects/1051295516635/locations/us-central1/workflows/myFirstWorkflow/executions/17ffc89c-0a27-4d2f-8356-e681d949a3d3 startTime: '2022-07-19T12:40:07.024823663Z' state: FAILED status: currentSteps: - routine: main step: checkSearchTermInInput workflowRevisionId: 000001-ac2
    出力には次の情報が含まれます。

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

実行エラーマップ

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

ワークフローの実行中にスローされたエラーには、エラーの原因を特定するためのタグが含まれています。たとえば、コネクタから返されるエラーに、次のような 2 つのキー(tagsmessage)が含まれる場合があります。

{'tags': ['SystemError'], 'message': 'an error has occurred'}

複数のタグが存在している可能性があります。特定のタグを確認するには、を使用します。次に例を示します。

${'SystemError' in e.tags}

文字列として返されたエラーデータにアクセスする

一部のコネクタと HTTP API は、エラーを返す前に、エラーを文字列としてシリアル化します。標準ライブラリ関数を使用して、ペイロードを元のエラーに復元できます。たとえば、エラー文字列をマップに変換するには、json.decode 関数と text.encode 関数を使用します。

json.decode(text.encode(ERROR_FROM_API))

エラータグ

次の表は、さまざまなエラータグの意味を説明したものです。

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

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

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

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

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

    gcloud workflows executions list WORKFLOW_NAME

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

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

    projects/PROJECT_NUMBER/locations/REGION/workflows/WORKFLOW_NAME/executions/EXECUTION_ID

    次のコマンドで使用する実行 ID をコピーします。

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

    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.
    

実行をフィルタ

workflows.executions.list メソッドによって返されるワークフロー実行のリストにフィルタを適用できます。

次のフィールドでフィルタリングできます。

  • duration
  • endTime
  • executionId
  • label
  • startTime
  • state
  • stepName
  • workflowRevisionId

たとえば、ラベル(labels."fruit":"apple")でフィルタリングするには、次のような API リクエストを行います。

GET https://workflowexecutions.googleapis.com/v1/projects/MY_PROJECT/locations/MY_LOCATION/workflows/MY_WORKFLOW/executions?view=full&filter=labels.%22fruit%22%3A%22apple%22"

ここで

  • view=full は、返される実行で入力するフィールドを定義するビューを指定します。この場合、すべてのデータ
  • labels.%22fruit%22%3A%22apple%22 は、URL エンコードされたフィルタ構文です。

詳細については、AIP-160 フィルタリングをご覧ください。

Cloud Logging にログを送信する

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

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

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

実行ログ

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

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

コールロギング

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

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

HTTP Authorization リクエスト ヘッダーは、HTTP 呼び出しのログから削除されます。

ワークフローの定義またはワークフローの実行にコールロギングを適用するときは、必要なロギングのレベルを指定できます。実行ログレベルが指定されていない場合を除き、実行ログレベルがワークフローのログレベルよりも優先されます(デフォルト)。実行ログレベルが指定されていない場合、ワークフローのログレベルが適用されます。

Cloud Logging によって設定されたログエントリのサイズ制限は、呼び出しのログ記録にも適用されます。

カスタムログ

ワークフローの実行中に 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: 省略可。ログエントリの重大度。例: INFOWARNING、または CRITICAL

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

必要な権限

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

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

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

Workflows でログを表示する

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

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

    [ワークフロー] に移動

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

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

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

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

  • Logging に送信されるログ

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

Logging でログを表示する

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

  1. Google Cloud コンソールで、[ログ エクスプローラ] ページに移動します。

    [ログ エクスプローラ] に移動

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

    ワークフローのロギング

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

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

次のステップ