Webhook 接続のセットアップ
webhook について
Webhook とは HTTP コールバックであり、何かが発生したときに実行される HTTP POST です。Webhook 接続により、Webhook を受け付けるサードパーティ アプリケーションに Sumo Logic のアラートを送信することができます。
たとえば、Sumo Logic で webhook 接続をセットアップして、Scheduled Search を作成すると、その Scheduled Search から Slack チャネルへの投稿としてアラートを送信したり、サードパーティ システムと統合したりすることができます。アラートに加えて、検索または一部の検索結果への直接的なリンクを含めることもできます (接続先のサードパーティ ツールによる)。Sumo Logic から送信できる webhook 数に制限はありませんが、サードパーティが制限を設けている可能性があります。さらに、webhook のペイロードが Sumo またはサードパーティによって制限されていることがあります。
完全にカスタマイズ可能な webhook 接続を利用すれば、以下の webhook をすばやく作成できます。
REST API を使用するほとんどのサービスでは、汎用の webhook を使用して接続を作成できるはずです。
webhook 接続のセットアップ
webhook を Sumo Logic に統合する最初の手順は、1 つ以上の接続の設定です。この接続が、Sumo Logic にデータの送信先を指示する HTTP エンドポイントになります。組織のニーズに応じて、任意の数の接続をセットアップできます。
webhook 接続をセットアップする手順
- [Manage Data (データの管理)] > [Settings (設定)] > [Connections (接続)] に移動します。
- [Connections (接続)] ページで、[Add (追加)] をクリックします。
- [Webhook] をクリックします。
- [Create Connection (接続の作成)] ダイアログに、接続の名前を入力します。
- (省略可能) 接続の説明を入力します。
- エンドポイントの URL を入力します。これはリモート システムの API から生成されます。
- (省略可能) サードパーティ システムで認証ヘッダーが必要な場合、ここで入力します。詳細については、下記の「認証ヘッダーの例」を参照してください。
- (省略可能) [Custom Headers (カスタム ヘッダー)]。最大 5 つのコンマ区切りのキーと値のペアを入力します。
- [Payload (ペイロード)] で、ターゲットの webhook URL によって規定されている形式で JSON オブジェクトを入力します。JSON オブジェクト内でパラメータとして使用できる変数の詳細については、下記の「webhook ペイロードの変数」を参照してください。
- [Save (保存)] をクリックします。
- 準備ができたら、Scheduled Search を作成してアラートをこの接続に送信します。
Webhook ペイロードの変数
このセクションでは、JSON ペイロード オブジェクトでパラメータとして使用できる変数を示しています。変数は二重中括弧で囲む必要があります。
Scheduled Search (ログ) およびモニタ (メトリクス) のペイロードの変数
以下の変数は、ログまたはメトリクス クエリによってトリガされる webhook のペイロードを指定するときに使用できます。
変数 | 説明 |
|
保存済み検索またはモニタの説明。転送されたペイロードで、この変数は検索に割り当てた名前または作成したモニタに置換されます。 |
|
保存済み検索またはモニタの説明。転送されたペイロードで、この変数は検索に割り当てた説明または作成したモニタに置換されます。 |
|
保存済み検索を実行するために使用されるクエリ。転送されたペイロードで、この変数は保存済み検索クエリまたはメトリクス クエリに置換されます。 |
|
検索またはメトリクス クエリへの URL リンク。転送されたペイロードで、これはクリックして保存済み検索クエリまたはメトリクス クエリを実行できる URL です。 |
|
検索を実行するために使用される時間範囲、またはメトリクス アラートをトリガした時間範囲。転送されたペイロードで、この変数はログまたはメトリクス クエリの時間範囲に置換されます。 |
|
通知をトリガしたログ検索またはメトリクス クエリの開始時間。 |
Scheduled Search (ログ) のみのペイロードの変数
変数 | 説明 |
|
検索の集計結果が含まれる JSON オブジェクト。 最大 200 件の集計結果を webhook 経由で送信できます。 |
|
未処理のメッセージが含まれる JSON オブジェクト。 最大 10 件の未処理のメッセージを webhook 経由で送信できます。 |
|
検索によって返される結果の数。 |
|
指定されたフィールド名の検索結果から返される値。これは、クエリ結果に基づいて読みやすい Slack メッセージを作成するのに役立ちます。 このフィールドの最大 200 件の集計結果または 10 件の未処理のメッセージを webhook 経由で送信できます。 フィールド名は、検索のフィールドに完全一致する必要があり、すべて小文字の英数字、アンダースコア、およびスペースで記述する必要があります。 |
Results.fieldname 変数の使用例
単一の結果—1 行のデータのみを返す Scheduled Search
このペイロードのテキスト... | この出力の結果... |
{ |
70.69.152.165 had 391 errors |
複数の結果—複数の行を返す Scheduled Search
このペイロード... | この出力の結果 |
{ |
70.69.152.165 had 391 errors |
モニタ (メトリクス) のみのペイロードの変数
以下の変数は、メトリクス クエリによってトリガされる webhook のペイロードを指定するときに使用できます。
変数 | 説明 |
{{AlertThreshold}} |
アラートをトリガした条件 (たとえば、過去 5 分の間に少なくとも 1 回 90 を上回る) |
{{AlertSource}} |
アラートをトリガしたメトリクスおよび sourceHost (そのメトリクスの関連付けられたタグを含む)。 |
{{AlertSource.fieldname}} |
指定されたフィールド名の AlertSource オブジェクトから返される値。 |
{{AlertID}} |
トリガされたアラートの ID。 |
{{AlertStatus}} |
トリガした時系列の現在のステータス (たとえば、重大や警告)。 |
認証ヘッダーの例
次の例のように、認証ヘッダーを作成します。(例は Wikipedia の記事「Basic access authentication (基本アクセス認証)」から引用)。
[Authorization (認証)] フィールドは次のように作成されます。
- ユーザ名とパスワードがシングル コロンで結合されます。
- 生成された文字列は Base64 の RFC2045-MIME バリアントを使用してエンコードされますが、76 文字/行の制限はありません。
- 承認方法とスペース、つまり「Basic」がエンコードされた文字列の前に付加されます。
たとえば、ユーザ エージェントがユーザ名として Aladdin
を、パスワードとして OpenSesame
を使用する場合、フィールドは次のように形成されます。
echo -n "Aladdin:OpenSesame" | base64
文字列「QWxhZGRpbjpPcGVuU2VzYW1l」が生成され、次のように使用されます。
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l
そのため、[Authentication Header (認証ヘッダー)] フィールドに次のように入力します。
Basic QWxhZGRpbjpPcGVuU2VzYW1l
ペイロードの例
フラット JSON
このペイロードの例はフラット JSON です。
{ "text": "{{SearchName}} ran over {{TimeRange}} at {{FireTime}}", "raw": "{{RawResultsJson}}", "num": "{{NumRawResults}}", "agg": "{{AggregateResultsJson}}" }
Hierarchical JSON
このペイロードの例は階層 JSON です。
{ "event_type": "trigger", "description": "{{SearchDescription}}", "client": "Sumo Logic", "client_url": "{{SearchQueryUrl}}", "details": { "name: {{SearchName}}, time: {{TimeRange}}--{{FireTime}}, num: {{NumRawResults}}, agg: {{AggregateResultsJson}}--raw: {{RawResultsJson}}" } }
ペイロード フィールドの例
すべての変数を有効な JSON として解釈するには引用符で囲む必要があります。
次のメッセージの例
{ "thread": "conciergePartitioner-1", "user_id": "", "user_name": "", "web_session": "", "Message": "2015-10-27 10:31:15,853 -0700 INFO Partitioned 0 tokens, 2 targets into 773 assignments" }
で、以下はペイロード設定です。RawResultsJson
が引用符で囲まれている点に注意してください。
{ "channel": "ops", "text": "{{RawResultsJson}}" }
次の有効な JSON は POST リクエストのペイロードで送信されます。
{"channel": "ops", "text": "{\"thread\":\"conciergePartitioner-1\",\"user\_id\":\"\",\"user\_name\":\"\",\"web\_session\":\"\",\"Message\":\"2015-10-27 10:31:15,853 -0700 INFO Partitioned 0 tokens, 2 targets into 773 assignments\"}
接続のテスト
接続を設定した後で、[Test Connection (接続のテスト)] をクリックします。接続が確立されると、「200 OK」応答メッセージが表示されます。
接続に成功すると、サードパーティ ツールにメッセージが表示されます。このメッセージには Scheduled Search の情報は一切含まれず、単にペイロードのテキストが含まれます。
接続の編集または削除
接続が変更された場合、接続にリンクされたそれ以降のすべての Scheduled Search が変更されます。以前の検索は何も変更されません。
接続を削除しても、こうした接続に送信された検索は削除されません。これらの検索を削除するには、ライブラリを使用します。