本文へ移動
Telemetry
統合ガイド

GitHub アクション ワークフロー Telemetry の統合

実行、試行、ジョブ、結論、期間、リリース コンテキストを含む GitHub アクションから、制限されたターミナル ワークフロー結果を送信します。

レビュー者 Telemetry 製品チーム に . インストルメンテーション契約、プライバシー境界、および実装ガイダンス. 基準と所有権を確認する

API キーを取得するスニペットを表示
役に立つ
  • CI ワークフローの信頼性
  • スケジュールされたワークフロー監視
  • リリースパイプラインの期間と再試行分析
実装の証拠

GitHub Actions Workflow Telemetry Integration: 境界から検証された行まで

制御されたアプリケーション境界で GitHub Actions Workflow Telemetry Integration を使用し、イベント コントラクトを小さく保ち、集約ビューを構築する前に既知の結果を検証します。

  1. 1

    結果を選択してください

    CI ワークフローの信頼性

  2. 2

    契約を定義する

    workflow_name、job_name、run_id、run_attempt、ステータス、duration_ms、リポジトリ、リリース

  3. 3

    境界を計測する

    if: always() を使用してステップを実行すると、失敗したジョブが端末レコードを生成し、可観測性の配信によってワークフローの結論が変更されてはならない場合は continue-on-error: true を使用します。

  4. 4

    証拠を検証する

    Exercise a known fixture, then inspect github_workflow_completed for one correctly typed terminal row.

始める前に

前提条件と境界

  • GitHub アクション シークレットとして保存された書き込みスコープの Telemetry キー
  • 最後のステップは always() で保護され、テレメトリの配信が失敗した場合にワークフローの結果をオーバーライドしないように構成されています。
  • イベント ペイロード、トークン、アクター データ、コミット メッセージ、プル リクエスト コンテンツを除外する、GitHub が提供する変数のホワイトリスト

配信設定

サーバー側のインストールと初期化

明示的な接続とリクエストのタイムアウトを指定した cURL の例を使用します。 ブラウザ バンドル、クライアントに表示される環境変数、ソース管理、ログ、および例外メッセージに取り込み資格情報が含まれないようにします。

  1. 1制限されたネットワーク動作を持つ再利用可能なサーバー側配信クライアントを 1 つ準備します。
  2. 2成功、失敗、再試行、またはタイムアウトの境界に結果イベントを追加します。
  3. 3アラートを有効にする前に、制御されたフィクスチャを送信し、保存されている行を検査します。

スニペット

1 つの構造化されたイベントから始める

ワークフローが完了、失敗、または再試行される場所にこの図形を追加します。次に、実際のフィールドからダッシュボードを構築します。

github-actions

GitHub Actions Workflow Telemetry Integrationイベント

bash
# Use in a final GitHub Actions step with:
# if: ${{ always() }}
# continue-on-error: true
# env:
#   TELEMETRY_API_KEY: ${{ secrets.TELEMETRY_WRITE_KEY }}
#   JOB_STATUS: ${{ job.status }}

jq -n   --arg workflow_name "$GITHUB_WORKFLOW"   --arg job_name "$GITHUB_JOB"   --arg run_id "$GITHUB_RUN_ID"   --arg run_attempt "$GITHUB_RUN_ATTEMPT"   --arg status "$JOB_STATUS"   --arg repository "$GITHUB_REPOSITORY"   --arg release "$GITHUB_SHA"   '{
    table: "github_workflow_completed",
    data: {
      workflow_name: $workflow_name,
      job_name: $job_name,
      run_id: $run_id,
      run_attempt: ($run_attempt | tonumber),
      status: $status,
      repository: $repository,
      release: $release
    }
  }' |
curl --fail-with-body --connect-timeout 2 --max-time 5   --request POST "https://api.telemetry.sh/log"   --header "Authorization: ${TELEMETRY_API_KEY}"   --header "Content-Type: application/json"   --data-binary @-

イベント契約

workflow_name、job_name、run_id、run_attempt、ステータス、duration_ms、リポジトリ、リリース

trigger_type、runner_environment、スケジュール済み、retry_recovered、および承認された場合の制御済み error_type

GITHUB_TOKEN、シークレット コンテキスト、github.event ペイロード、環境ダンプ、コミット メッセージ、信頼できないフォークによって提供されたブランチ、または任意のステップ出力はありません

実装のチェックポイント

チェックポイント 1

if: always() を使用してステップを実行すると、失敗したジョブが端末レコードを生成し、可観測性の配信によってワークフローの結論が変更されてはならない場合は continue-on-error: true を使用します。

チェックポイント 2

GitHub は、コンテキストには機密情報が含まれる可能性があり、一部のコンテキスト値は信頼できない入力として扱う必要があると警告します。文書化された許可リストのみをシェル環境変数に展開します。

チェックポイント 3

論理実行識別子として GITHUB_RUN_ID を使用し、再実行を区別するために GITHUB_RUN_ATTEMPT を使用します。無関係なイベントから期間を推測するのではなく、制御された開始タイムスタンプから期間を測定します。

検証

イベントが到着したことを証明する

既知の成功例と失敗例を実行した後、これを実行します。最終的なイベント コントラクトがスニペットと異なる場合は、フォールバック テーブル名を置き換えます。

github-actions-検証

GitHub Actions Workflow Telemetry Integration 検証クエリ

sql
SELECT *
FROM github_workflow_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
論理結果ごとに 1 つのターミナル行を、予想されるステータス、識別子、単位、および UTC 時刻とともに確認します。
推論されたスキーマを検査し、再試行によってフィールド タイプが変更されたり、新しい論理イベント ID が生成されたりしないことを確認します。
保存されたフィールドで認証情報、生のペイロード、プロンプト、プライベート コンテンツ、および無制限のエラー メッセージを検索します。
ダッシュボードを完了として扱う前に、プロバイダーのタイムアウト、取り込みの拒否、およびプロセスのシャットダウンを実行します。

実装の参考資料

新しい運用パスを有効にする前に、イベント契約、データ安全性に関するガイダンス、上流の主要ドキュメントを確認してください。

CI でのテレメトリのテストスケジュールを逃しました SQLワークフロー相関 SQLGitHub アクションコンテキストGitHub アクション変数

生産境界

結果イベントを小さく、回復可能なものに保つ

このパターンが提供するのは、

  • 上流のワークフローの横にある、制限付きの SQL 対応の結果。
  • ダッシュボード、アラート、およびイベント間の相関関係の安定したフィールド。
  • 成功、失敗、再試行、タイムアウトの動作を検証するためのフィクスチャ駆動のパス。

このパターンでは提供されません

  • OTLP エクスポーター、自動収集パイプライン、または詳細なトレースと診断ログの代替。
  • ペイロードにイベント ID が含まれているという理由だけで、1 回だけ配信されます。
  • 生のプロバイダー ペイロード、ユーザー コンテンツ、資格情報、または規制されたデータを収集する許可。
配信と冪等性バッチ処理とシャットダウン取り込みのトラブルシューティング

イベントスキーマの開始点

このワークフローのイベント コントラクト

クエリまたはスニペットを運用環境に適用する前に、行粒度、出力境界、必要なタイプ、プライバシー クラス、サンプル ペイロード、および検証チェックリストを確認してください。

非同期の信頼性11 フィールド

background_job_completed

論理ジョブごとに 1 つの最終結果。

契約書の検査
データ品質11 フィールド

telemetry_delivery_observed

配信試行または配信ウィンドウごとに 1 つのサンプリングまたは集約された観測。

契約書の検査

関連製品の機能

このワークフローを続行します アラート

レビューされた信頼性クエリを、所有するしきい値と応答のワークフローにプロモートします。

探索 アラート顧客の証拠を確認する

関連する SQL レシピ

SQL で次の質問に答えてください

このワークフローの構造化フィールドに対してクエリを実行し、結果の例を検査して、有用な回答をダッシュボードまたはアラートに変換します。

すべてのレシピを参照する
バックグラウンドジョブ初心者

バックグラウンドジョブの再試行と失敗率を測定する

どのバックグラウンド ジョブが再試行を最も多く消費するか、または依然として失敗するのはどれですか?

レシピを開く
バックグラウンドジョブ中級者

欠落した Cron スケジュールの検出

スケジュールされたジョブは、文書化された間隔よりも遅く実行されましたか?

レシピを開く
インフラストラクチャー上級者向け

インシデントの検出と復旧時間を計算する

各サービスがインシデントを検出して回復するまでにどれくらいの時間がかかりますか?

レシピを開く
構造化イベント上級者向け

相関のあるワークフローのタイムラインを再構築する

最近失敗したワークフロー中に、順番に何が起こったのでしょうか?

レシピを開く
データ品質初心者

イベント名によるTelemetryボリュームの測定

どのイベント コントラクトが最も多くの取り込み量を生み出しますか?

レシピを開く
完全なコレクションバックグラウンドジョブ SQLデータ品質 SQL構造化イベント SQLインフラストラクチャー SQL

実装ファミリーごとに参照する

関連する統合パターンを比較する

バックグラウンド ジョブとキュー Telemetry の統合

この統合と組み合わせるテンプレート

バックグラウンドジョブ失敗モニター

最初の実行から再試行と失敗に至るまで、キュー、cron、インポート、請求同期、および Webhook ジョブの健全性をキャプチャします。

テンプレートを開く

AI エージェントのセキュリティ監査テンプレート

ツール認可の決定、ポリシーのバージョン、人間による承認、およびプライバシーに配慮した構造化イベントによる最終結果を計測します。

テンプレートを開く

AI エージェント可観測性テンプレート

構造化された SQL 対応イベントを使用して、エージェントの実行、ツール呼び出し、再試行、モデルの遅延、エラー、受け入れられた結果を追跡します。

テンプレートを開く

さらなる統合

Ingest and Trigger.dev ジョブ Telemetry

SQL 対応ログを使用して、非同期ワーカー、スケジュールされたジョブ、再試行、失敗、配信不能イベントを計測します。

オープンガイド

n8n ワークフロー Telemetry

n8n ワークフローの完了、失敗、再試行、項目数、およびダウンストリーム配信結果を、HTTP 要求ノードを介して、制限された Telemetry イベントに送信します。

オープンガイド

AWS Lambda 構造化イベント監視

コンパクトな構造化イベントを使用して、Lambda の呼び出し、コールド スタート、期間、再試行、ビジネスの結果を追跡します。

オープンガイド