dt-obs-ext-monitors

外部モニターの取り込み

events ingest API を使用して、サードパーティーのテストおよびモニターの結果を Dynatrace Grail に送信します。 非推奨の POST /api/v1/synthetic/ext/tests エンドポイントの正式な代替手段です。

概要

/platform/ingest/custom/events/{endpoint} に POST されたイベントは Grail に取り込まれ、OpenPipeline によって処理されます。OpenPipeline は次の処理を行います。

• アラートと SLO 用のメトリクス（external.test.availability、external.test.duration）を抽出します
• 一意の test.id ごとに EXT_TEST Smartscape ノードを登録します。これにより、トポロジー情報のない状態で問題が浮いたままになるのではなく、Davis Problems が名前付きエンティティ（「外部テスト X がダウンしました」）に関連付けられるようになります
• ダッシュボードでのフィルタリング用に、ステップイベントに result.status.category（SUCCESS／SKIPPED／FAIL）を追加します

テスト結果は、次の 2 種類のイベントで構成されます。

種類	用途
external_test_run	1 回のテスト実行全体の成功／失敗結果
external_test_step	その実行内の 1 つのステップ（任意。ステップレベルのメトリクスを有効にします）

認証

次の 2 種類のトークンを使用できます。

トークンの種類	スコープ
Classic Api-Token	openpipeline.events.custom
Platform Token / OAuth	openpipeline:events.custom:ingest

よくある誤った推測ですが、events.ingest は機能しません。

クイックスタート

前提条件： イベントを送信する前に、OpenPipeline で取り込みエンドポイントを作成する必要があります。 デフォルトの Dynatrace 3rd-party monitors Monaco バンドルにより、external.tests エンドポイントが自動的にプロビジョニングされます。 セットアップの詳細とカスタムエンドポイントの作成については、references/event-ingestion.md を参照してください。

最小構成のテスト結果を 1 件送信します（external.tests は、設定したエンドポイント名に置き換えてください）。

curl -X POST "https://{env-id}.live.dynatrace.com/platform/ingest/custom/events/external.tests" \
  -H "Authorization: Api-Token {token}" \
  -H "Content-Type: application/json" \
  -d '[{
    "event.kind": "EXTERNAL_TEST_EVENT",
    "event.type": "external_test_run",
    "test.id": "my-api-health-check",
    "test.run.id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "test.name": "My API Health Check",
    "test.type": "api",
    "test.run.status": "passed",
    "test.run.availability": 1,
    "test.run.duration_ms": 245,
    "test.run.location": "us-east-1",
    "dt.security_context": "team-checkout",
    "timestamp": "2024-01-15T10:30:00Z"
  }]'

期待される応答： HTTP 200（空の本文）。

イベントスキーマ全体、ステップイベント、エラーフィールドと CI メタデータを含む拡張例、Java DTO の形式、および DQL クエリについては、references/event-ingestion.md を参照してください。

Grail での確認

送信後、イベントが表示されることを確認します。

fetch events, from:now()-1h
| filter event.type == "external_test_run"
| fields timestamp, test.id, test.name, test.run.status, test.run.duration_ms, test.run.location
| sort timestamp desc
| limit 20

主な制約

• 本文は JSON 配列（[{...}]）である必要があります。オブジェクトラッパー（{"events":[...]}）は使用できません。
• 1 つのリクエストの配列に、実行イベントとステップイベントを混在させることができます。
• timestamp は ISO 8601 UTC 形式である必要があります（例："2024-01-15T10:30:00Z"）。
• test.run.availability は、文字列ではなく整数の 1 または 0 である必要があります。
• 1 回の実行に含まれるすべてのステップイベントでは、親の実行イベントと同じ test.run.id および test.id を使用する必要があります。
• ステップイベントには、test.run.id に加えて test.step.id（実行内で一意）が必要です。
• event.kind: "EXTERNAL_TEST_EVENT" を含める必要があります。これは Grail によるイベント分類に使用されます。 正しいパイプラインへのルーティングは、event.kind ではなく event.type によって行われます。
• dt.smartscape.ext_test または result.status.category は送信しないでください。これらは取り込み後にパイプラインによって書き込まれるため、含めると上書きされます。
• dt.security_context はデータアクセスのポリシーを制御します。複数チームのテナントでチームごとのアクセス制御とコストの割り当てを有効にするには、すべてのイベントに設定することをお勧めします。

複数ロケーションのテスト

異なる test.run.location 値を使用して、同じ test.id を複数のロケーションから送信し、複数ロケーションのテストを構成します。OpenPipeline は test.id ごとに 1 つの EXT_TEST ノードを作成し、(test.id, location) の組み合わせごとに 1 つの可用性メトリクス時系列を作成します。

これにより、次の 2 段階のアラートをすぐに利用できます。

アラートの種類	発生条件
ローカル障害	1 つのロケーションの可用性が低下したとき（ロケーションごとの時系列）
グローバル障害	すべてのロケーションの平均がしきい値を下回ったとき（例：過半数で障害が発生）

3 ロケーションのテストにおけるしきい値の計算：1 ロケーションで障害が発生 → 平均 0.67（しきい値 0.5 ではアラートなし）。2 ロケーションで障害が発生 → 平均 0.33（アラート発生）。3 ロケーションすべてで障害が発生 → 平均 ≈ 0（即座にアラート発生）。

すべてのロケーションで test.id を一定に保ってください。変更すると、新しい Smartscape ノードが作成され、メトリクスの履歴が途切れます。

関連スキル

• dt-dql-essentials — 取り込んだイベントをクエリし、分析クエリを作成するための DQL 構文
• dt-obs-frontends — dt.smartscape.frontend を介してテスト実行をフロントエンドエンティティにリンクし、 Smartscape に EXT_TEST → FRONTEND の依存関係エッジを描画します