インテグレーション

GitLabは、Webhookレシーバーを介して、あらゆるソースからのアラートを受け入れることができます。アラート通知は、オンコールのローテーションのしたり、インシデントの作成に使用したりできます。

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

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

設定

GitLabは、設定したHTTPエンドポイントを介してアラートを受信できます。

単一のアラートエンドポイント

GitLabプロジェクトでアラートエンドポイントを有効にすると、JSON形式でアラートペイロードを受信できるようになります。いつでも、好みに合わせてペイロードをカスタマイズできます。

1. メンテナーロールを持つユーザーとしてGitLabにサインインします。
2. プロジェクトで、設定 > モニタリングに移動します。
3. アラートセクションを展開し、インテグレーションタイプを選択するドロップダウンリストで、Prometheusからのアラートの場合はPrometheusを、その他のモニタリングツールの場合はHTTPエンドポイントを選択します。
4. 有効アラート設定を切り替えます。Webhook設定のURLと認可キーは、インテグレーションを保存した後、認証情報の表示タブで確認できます。外部サービスでURLと認可キーも入力する必要があります。

アラートエンドポイント

GitLab Premiumでは、複数の固有なアラートエンドポイントを作成して、JSON形式であらゆる外部ソースからアラートを受信したり、ペイロードをカスタマイズしたりできます。

1. メンテナーロールを持つユーザーとしてGitLabにサインインします。

2. プロジェクトで、設定 > モニタリングに移動します。

3. アラートセクションを展開します。

4. 作成するエンドポイントごとに:

   1. 新しいインテグレーションを追加を選択します。

   2. インテグレーションタイプを選択するドロップダウンリストで、Prometheusからのアラートの場合はPrometheusを、その他のモニタリングツールの場合はHTTPエンドポイントを選択します。詳細を参照

   3. インテグレーションに名前を付けます。

   4. 有効アラート設定を切り替えます。Webhook設定のURLとAuthorization Key（認可キー）は、インテグレーションを保存した後、認証情報の表示タブで確認できます。外部サービスでURLと認可キーも入力する必要があります。

   5. オプション。モニタリングツールのアラートのフィールドをGitLabフィールドにマップするには、サンプルペイロードを入力し、Parse payload for custom mapping（カスタムマッピングのペイロードを解析）を選択します。有効なJSONが必要です。サンプルペイロードを更新する場合は、フィールドも再マップする必要があります。Prometheusインテグレーションの場合、ペイロード全体の代わりに、ペイロードのalertsキーから単一のアラートを入力します。

   6. オプション。有効なサンプルペイロードを入力した場合は、ペイロードアラートキーの各値を選択して、マップしてGitLabアラートキーにします。

   7. インテグレーションを保存するには、Save Integration（インテグレーションの保存）を選択します。必要に応じて、インテグレーションを作成した後、インテグレーションのテストアラートの送信タブからテストアラートを送信できます。

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

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

モニタリングツールのアラート形式をGitLabアラートと統合できます。アラートリストとアラート詳細ページに正しい情報を表示するには、HTTPエンドポイントを作成するときに、アラートのフィールドをGitLabフィールドにマップします。:

Alertmanagerにインテグレーション認証情報を追加する（Prometheusインテグレーションのみ）

Prometheusアラート通知をGitLabに送信するには、PrometheusのインテグレーションからURLと認可キーをPrometheus Alertmanager設定のwebhook_configsセクションにコピーします:

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
        # ...

GitLabの外部でアラートペイロードをカスタマイズする

予期されるHTTPリクエスト属性

カスタムマッピングのない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リクエスト属性

アラートは、Prometheus Webhookレシーバー用にフォーマットされることが想定されています。

トップレベルの必須属性:

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

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

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

属性は、プリミティブ型（文字列や数値など）に限定されませんが、ネストされたJSONオブジェクトにすることができます。次に例を示します:

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

Prometheusの重大度オプション

Prometheusからのアラートは、アラート重大度に関して、大文字と小文字を区別しない次の値のいずれかを提供できます:

• クリティカル: critical、s1、p1、emergency、fatal
• 高: high、s2、p2、major、page
• 中: medium、s3、p3、error、alert
• 低: 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
        }
      }
    }
  }]
}

認証

次の認可方法が使用できます:

• ヘッダーにAuthZ（認可）を指定する。
• 基本認証

<authorization_key>と<url>の値は、アラートインテグレーションを設定するときに見つけることができます。

Bearer AuthZ（認可）

認可キーは、ベアラートークンとして使用できます:

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>

レスポンスボディ

JSONレスポンスビルドには、リクエスト内で作成されたすべてのアラートのリストが含まれています:

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

成功したレスポンスは、200レスポンスコードを返します。

テストアラートをトリガーする

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

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

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

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

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

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

リカバリーアラート

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

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

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

Opsgenieアラートへのリンク

OpsgenieとのGitLabインテグレーションを使用して、アラートをモニタリングできます。

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

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

1. 少なくともメンテナーロールを持つユーザーとしてサインインします。
2. モニタリング > アラートに移動します。
3. インテグレーションの選択ボックスで、Opsgenie（Opsgenie）を選択します。
4. 有効切り替えを選択します。
5. API URLフィールドに、OpsgenieインテグレーションのベースURL（https://app.opsgenie.com/alert/listなど）を入力します。
6. 変更を保存を選択します。

インテグレーションを有効にした後、アラートページ（モニタリング > アラート）に移動し、View alerts in Opsgenie（Opsgenieでアラートを表示）を選択します。