• インテグレーションリスト
• 設定
  • 単一のHTTPエンドポイント
  • HTTP エンドポイント
    • カスタムアラートのマップフィールド
• GitLabの外でアラートのペイロードをカスタマイズします。
  • リクエストボディの例
  • Prometheus エンドポイント
    • Prometheus Alertmanagerへのインテグレーション認証情報の追加
    • 期待されるリクエスト属性
    • Prometheus 重大度オプション
    • Prometheus アラートの例
• 作成者
  • ベアラ認証ヘッダ
  • 基本認証
• レスポンスボディ
• テストアラートのトリガー
• 同じアラートの自動グループ化
• 回復アラート
• Opsgenieアラートへのリンク

インテグレーション

• GitLab 12.4で導入されました。
• 12.8でGitLab UltimateからGitLab Freeへ移行。

GitLabはWebhookレシーバー経由であらゆるソースからのアラートを受け取ることができます。アラート通知は、オンコールローテーションのためのページングをトリガーしたり、インシデントを作成するために使用することができます。

インテグレーションリスト

GitLab 13.5 で導入されました。

少なくともメンテナーのロールがあれば、設定済みのアラートインテグレーションの一覧を見ることができます。プロジェクトのサイドバーメニューからSettings > Monitorと進み、Alertsセクションを展開します。リストには、インテグレーション名、タイプ、ステータス（有効または無効）が表示されます：

設定

GitLabは設定したHTTPエンドポイント経由でアラートを受け取ることができます。

単一のHTTPエンドポイント

GitLabプロジェクトでHTTPエンドポイントを有効にすると、JSON形式のアラートペイロードを受け取るアクティビティが有効になります。ペイロードはいつでも好きなようにカスタマイズできます。

1. プロジェクトのメンテナーのロールを持つユーザーとしてGitLabにサインインしてください。
2. プロジェクトのSettings > Monitorに移動します。
3. Alerts] セクションを展開し、[Select integration type] ドロップダウン リストで [HTTP Endpoint] を選択します。
4. アクティブアラートの設定を切り替えます。Webhook 設定の URL と作成者キーは、インテグレーションを保存した後、[資格情報の表示] タブで使用できます。また、外部サービスに URL と認証キーを入力する必要があります。

HTTP エンドポイント

GitLab 13.6で導入されました。

GitLab Premiumでは、任意の外部ソースからのアラートをJSONフォーマットで受信するための複数のユニークなHTTPエンドポイントを作成し、ペイロードをカスタマイズすることができます。

1. プロジェクトのメンテナーのロールを持つユーザーとしてGitLabにサインインしてください。
2. プロジェクトのSettings > Monitorに移動します。
3. アラートセクションを展開します。

4. 作成する各エンドポイントについて

   1. 新しいインテグレーションを追加]を選択します。
   2. インテグレーションタイプの選択] ドロップダウン リストで、[HTTP エンドポイント] を選択します。
   3. インテグレーションに名前を付けます。
   4. アクティブアラート設定を切り替えます。Webhook 設定のURLと作成者キーは、インテグレーションを保存した後、[資格情報の表示] タブで使用できます。また、外部サービスに URL と認証キーを入力する必要があります。

   5. オプションです。監視ツールのアラートのフィールドをGitLabのフィールドにマッピングするには、サンプルのペイロードを入力し、カスタムマッピングのためにペイロードを解析するを選択します。有効な JSON が必要です。サンプルのペイロードを更新した場合は、フィールドのマッピングもやり直す必要があります。

   6. オプションです。有効なサンプルペイロードを提供した場合、GitLabアラートキーにマッピングするPayloadアラートキーの各値を選択します。
   7. インテグレーションを保存するには、Save Integration を選択します。必要であれば、インテグレーションを作成した後、Send test alertタブからテストアラートを送信することができます。

新しい HTTP エンドポイントがインテグレーションリストに表示されます。インテグレーションリストの右側にある{設定}設定アイコンを選択すると、インテグレーションを編集できます。

カスタムアラートのマップフィールド

GitLab 13.10で導入されました。

監視ツールのアラート形式をGitLabアラートとインテグレーションすることができます。アラートリストと アラート詳細ページに正しい情報を表示するには、HTTPエンドポイントを作成する際にアラートのフィールドをGitLabのフィールドにマッピングしてください：

GitLabの外でアラートのペイロードをカスタマイズします。

カスタムマッピングのない HTTP エンドポイントでは、以下のパラメータを送信することでペイロードをカスタマイズできます。すべてのフィールドはオプションです。受信アラートにTitle フィールドの値が含まれていない場合、デフォルト値New: Alert が適用されます。

アラートのペイロードにカスタムフィールドを追加することもできます。追加パラメータの値はプリミティブ型（文字列や数値など）に限らず、ネストされたJSONオブジェクトでも構いません。例えば

{ "foo": { "bar": { "baz": 42 } } }

リクエストボディの例

ペイロードの例

{
  "title": "Incident title",
  "description": "Short description of the incident",
  "start_time": "2019-09-12T06:00:55Z",
  "service": "service affected",
  "monitoring_tool": "value",
  "hosts": "value",
  "severity": "high",
  "fingerprint": "d19381d4e8ebca87b55cda6e8eee7385",
  "foo": {
    "bar": {
      "baz": 42
    }
  }
}

Prometheus エンドポイント

前提条件：

• 少なくともプロジェクトのメンテナーのロールを持っている必要があります。

1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
2. 設定 > モニターを選択します。
3. アラート]セクションを展開し、[新しいインテグレーションを追加]を選択します。
4. Select integration type］ドロップダウンリストで、［Prometheus］を選択します。
5. アクティブトグルをオンにします。
6. Prometheus APIベースURLを入力します。プレースホルダのURLを入力してください。このフィールドを使用する機能は非推奨であり、GitLab 16.0で削除される予定です。
7. インテグレーションを保存を選択します。

Webhook 設定の URL と作成者は、[資格情報の表示] タブで確認できます。

外部サービスに URL と認証キーを入力します。インテグレーションからテストアラートを送信することもできます。 テストアラートの送信タブから送信することもできます。

Prometheus Alertmanagerへのインテグレーション認証情報の追加

Prometheus のアラート通知を GitLab に送るには、PrometheusAlertmanager 設定のwebhook_configs セクションにPrometheus インテグレーションのURL と作成者の認証キーをコピーします：

receivers:
  - name: gitlab
    webhook_configs:
      - http_config:
          authorization:
            type: Bearer
            credentials: 1234567890abdcdefg
        send_resolved: true
        url: http://IP_ADDRESS:PORT/root/manual_prometheus/prometheus/alerts/notify.json
        # Rest of configuration omitted
        # ...

期待されるリクエスト属性

アラートはPrometheusWebhookレシーバー用にフォーマットされることが期待されます。

トップレベルの必須属性

• alerts
• commonAnnotations
• commonLabels
• externalURL
• groupKey
• groupLabels
• receiver
• status
• version

Prometheusペイロードのalerts 、配列の各項目に対してGitLabアラートが作成されます。GitLabアラートを設定するために、以下のネストされたパラメータを変更することができます。

annotations に含まれるその他の属性は、アラートの詳細ページで利用できます。その他の属性は無視されます。

属性はプリミティブな型（文字列や数値など）に限らず、ネストされたJSONオブジェクトでもかまいません。例えば

{
    "target": {
        "user": {
            "id": 42
        }
    }
}

Prometheus 重大度オプション

GitLab 13.9 で導入されました。

Prometheus からのアラートでは、アラートの重大度として大文字と小文字を区別しない follow 値を指定することができます：

• Critical:critical,s1,p1,emergency、fatal
• High:high,s2,p2,major、page
• 中 medium s3, , 、 p3erroralert
• 低： low,s4,p4,warn、warning
• 情報：info,s5,p5,debug,information、notice

値がない場合、またはこのリストにない場合、深刻度のデフォルトはcritical になります。

Prometheus アラートの例

警告ルールの例

groups:
- name: example
  rules:
  - alert: ServiceDown
    expr: up == 0
    for: 5m
    labels:
      severity: high
    annotations:
      title: "Example title"
      runbook: "http://example.com/my-alert-runbook"
      description: "Service has been down for more than 5 minutes."
      gitlab_y_label: "y-axis label"
      foo:
        bar:
          baz: 42

リクエストペイロードの例

{
  "version" : "4",
  "groupKey": null,
  "status": "firing",
  "receiver": "",
  "groupLabels": {},
  "commonLabels": {},
  "commonAnnotations": {},
  "externalURL": "",
  "alerts": [{
    "startsAt": "2022-010-30T11:22:40Z",
    "generatorURL": "http://host?g0.expr=up",
    "endsAt": null,
    "status": "firing",
    "labels": {
      "gitlab_environment_name": "production",
      "severity": "high"
    },
    "annotations": {
      "title": "Example title",
      "runbook": "http://example.com/my-alert-runbook",
      "description": "Service has been down for more than 5 minutes.",
      "gitlab_y_label": "y-axis label",
      "foo": {
        "bar": {
          "baz": 42
        }
      }
    }
  }]
}

作成者

以下の作成者が利用できます：

• ベアラ認証ヘッダ
• 基本認証

<authorization_key> および<url> の値は、アラートインテグレーションを設定する際に確認できます。

ベアラ認証ヘッダ

作成者キーはBearerトークンとして使用できます：

curl --request POST \
  --data '{"title": "Incident title"}' \
  --header "Authorization: Bearer <authorization_key>" \
  --header "Content-Type: application/json" \
  <url>

基本認証

作成者は、password 。username は空白のままです：

• ユーザー名：<blank>
• パスワード<authorization_key>

curl --request POST \
  --data '{"title": "Incident title"}' \
  --header "Authorization: Basic <base_64_encoded_credentials>" \
  --header "Content-Type: application/json" \
  <url>

ベーシック認証は、URLに直接認証情報を入力して使用することもできます：

curl --request POST \
  --data '{"title": "Incident title"}' \
  --header "Content-Type: application/json" \
  <username:password@url>

レスポンスボディ

GitLab 14.5 で導入されました。

JSON レスポンスボディには、リクエスト内で作成されたアラートのリストが含まれます：

[
  {
    "iid": 1,
    "title": "Incident title"
  },
  {
    "iid": 2,
    "title": "Second Incident title"
  }
]

レスポンスに成功すると、200 レスポンスコードが返されます。

テストアラートのトリガー

GitLab 13.2 で導入されました。

プロジェクトのメンテナーやオーナーがインテグレーションを設定した後、テストアラートをトリガーしてインテグレーションが正しく動作することを確認できます。

1. 少なくとも Developer ロールを持つユーザーとしてサインインします。
2. プロジェクトのSettings > Monitorに移動します。
3. Alerts］を選択してセクションを展開します。
4. リストのインテグレーション右側の{設定}設定アイコンを選択します。
5. テストアラートの送信]タブを選択して開きます。
6. ペイロードフィールドにテストペイロードを入力します（有効なJSONが必要です）。
7. 送信を選択します。

GitLabはテストの結果に応じてエラーまたは成功のメッセージを表示します。

同じアラートの自動グループ化

GitLab 13.2 で導入されました。

GitLab バージョン 13.2 以降では、GitLab はペイロードに基づいてアラートをグループ化します。受信したアラートが他のアラートと同じペイロードを含む場合（start_time とhosts 属性を除く）、GitLabはこれらのアラートをグループ化し、アラート管理リストと詳細ページにカウンターを表示します。

既存のアラートが既にresolved である場合、GitLab は代わりに新しいアラートを作成します。

回復アラート

GitLab 13.4 で導入されました。

GitLabのアラートは、HTTP Endpointがアラートの終了時刻が設定されたペイロードを受信すると自動的に解決されます。カスタムマッピングのないHTTP Endpointの場合、期待されるフィールドはend_time 。カスタムマッピングでは、予想されるフィールドを選択できます。

GitLab は、ペイロードの一部として提供できるfingerprint 値に基づいて解決するアラートを決定します。アラートのプロパティとマッピングの詳細については、GitLabの外でアラートのペイロードをカスタマイズするを参照してください。

アラートが解決されたときに、関連するインシデントが自動的にクローズされるように設定することもできます。

Opsgenieアラートへのリンク

GitLab 13.2 で導入されました。

OpsgenieとGitLabインテグレーションを使用してアラートを監視できます。

Opsgenieインテグレーションを有効にした場合、他のGitLabアラートサービスを同時にアクティブにすることはできません。

Opsgenieインテグレーションを有効にするには：

1. メンテナーまたはオーナーのロールを持つユーザーとしてサインインします。
2. Monitor] > [Alerts] に移動します。
3. インテグレーション］セレクト・ボックスで［Opsgenie］を選択します。
4. アクティブ］トグルを選択します。
5. API URL］フィールドに、OpsgenieインテグレーションのベースURLを入力します（https://app.opsgenie.com/alert/listなど）。
6. 変更を保存を選択します。

インテグレーションを有効にしたら、[Monitor] > [Alerts]でアラート・リスト・ページに移動し、[View alerts in Opsgenie]を選択します。