コンテンツにスキップ
Yagra

パッシブイベント

こちらから行うポーリングは、機器に「調子はどうですか」と尋ねる形です。パッシブイベントは、その逆 です。機器のほうから先に話しかけてきます。syslog の 1 行、SNMP トラップ、別システムからの Webhook です。

Yagra はそれを受け取り、メッセージを送信元のノードへ結び付け、アラートに値するかどうかを判断します。

概要

Section titled “概要”

3 つの受信経路が 1 つのイベントパイプラインへ流れ込みます。

経路 届き方 受信側
syslog UDP データグラム（ホスト側ポートは既定 514） ポーラー
SNMP トラップ UDP データグラム（ホスト側ポートは既定 162） — v1/v2c のトラップと inform ポーラー
Webhook ソースごとの Bearer トークンを付けた POST /api/v1/ingest/webhook/<source-id> コア（API ポート）

ポーラーは、機器の近くで syslog とトラップを受け取り、バス経由でコアへ送ります。ですからパッシブな 受信も、ポーリングと同じ分散の形で動きます。拠点のポーラーが拠点のイベントをその場で受け取り、 ポーラーがすでに張っているバスの接続に乗せて本社へ届けます。

Webhook だけは、ポーラーを通りません。コアの API へ直接届きます。

コアは、受け取ったすべてのイベントをイベントルール（後述）と突き合わせます。一致したイベントは 重大度を得て、アラートを上げられます。

一致しなかったイベントも保存され、閲覧できます。ですからまだルールを書いていない段階でも、フリート が何を言っているかを見られます。

イベントから上がったアラートは、しきい値のアラートと同じパイプラインに合流します。通知チャネルも 同じです。発報と解消のライフサイクルにそのまま対応する PagerDuty（Events API v2）や Jira Service Management（Alerts API）も含みます。

リスナーの有効化

Section titled “リスナーの有効化”

syslog とトラップのリスナーはオプトインです。それぞれ、対応するバインド変数が設定されているあいだ だけ存在します。compose ファイルは既定で両方を有効にしています。

リスナー 有効化する変数 コンテナ側のバインド ホスト側ポート（compose）
syslog YAGRA_SYSLOG_BIND（例 0.0.0.0:1514） 1514/udp 514（YAGRA_SYSLOG_PORT）
SNMP トラップ YAGRA_TRAP_BIND（例 0.0.0.0:1162） 1162/udp 162（YAGRA_TRAP_PORT）
Terminal window
# .env — these are the compose defaults; set a bind empty to disable that listener
YAGRA_SYSLOG_BIND=0.0.0.0:1514
YAGRA_TRAP_BIND=0.0.0.0:1162
YAGRA_SYSLOG_PORT=514   # host port devices send to
YAGRA_TRAP_PORT=162

compose で片方を無効にするには、.env でそのバインド変数を空文字列に設定します。compose を使わない 場合は、変数を未設定のままにしておけばリスナーは起動しません。

このページで最も重要な、デプロイ上の注意点が 2 つあります。

  • イベントとノードの結び付けには、データグラムの送信元 IP を使います。 イベントは、そのアドレス を持つノードのものとして扱われます。

    ホストで Docker のブリッジネットワークが送信元アドレスを書き換えてしまう場合は、ポーラーを network_mode: host で動かしてください。機器の実アドレスが残ります。リモート拠点向けの compose 構成は、すでにそうなっています。

    送信元アドレスを書き換えるものは、他にもあります。機器とポーラーの間にある NAT などです。どれも 同じように結び付けを壊します。ポーラーを機器の近くに置くべき理由が、これでもう 1 つ増えます。

    なお、ホストですでに syslog デーモンがポート 514 を使っている場合は、公開するポートをずらして ください。

  • ポーラーは 1024 未満のポートを開けません。 権限を絞ったコンテナとして動くからです。代わりに 1514 と 1162 を開き、compose がホスト側の標準ポートをそこへ割り当てます。

    ホストネットワークやネイティブのインストールでは、この割り当てがありません。機器を直接その大きい 番号のポートへ向けるか、ファイアウォールで 514 / 162 をそこへ転送してください。実際の iptables のルールはポートとファイアウォールにあります。

syslog

Section titled “syslog”

syslog のリスナーは、2 つの形式を受け付けます。RFC 5424（新しく、構造化された形式）と RFC 3164（従来の BSD 形式）です。

ですからルータ、スイッチ、ファイアウォール、Unix ホストは、いずれも既存の syslog 設定を変えずに そのまま Yagra へ向けられます。

解析で取り出すのは、ファシリティ、重大度、ホスト名、アプリケーション名、メッセージ本文です。これらは イベントルールが突き合わせる項目であり、あとで転送のフィルタが 選別に使う項目でもあります。

Yagra 側で、機器ごとに設定するものはありません。送信元アドレスが監視対象のノードと一致すれば、 自動的に結び付きます。Yagra が監視していないアドレスからのメッセージも、受け取って閲覧できます。

イベント ▸ イベントの見出しの下には、いまフリートが受信待ちしている宛先と、それを持っている ポーラーが並びます。何も届かないときは、まずここを見てください。リスナーに届いているか確かめるには、 Linux ホストからテストの 1 行を送り、同じ画面で確認します。

Terminal window
logger --server <yagra-host> --port 514 --udp "test: hello from yagra docs"

SNMP トラップ

Section titled “SNMP トラップ”

トラップリスナーは SNMP v1 と v2c を話し、通知の 2 つの形式のどちらも扱います。

  • トラップ — 送りっぱなしの通知。受信してパースします。
  • inform — 確認応答を伴う通知。Yagra が送信側の待っている確認応答を返します。ですから inform を 設定した機器が、再送を繰り返し続けることはありません。

受け取ったトラップは、トラップの OID を人が読める名前に変換します。ですからトラップは生の OID ではなく、名前の付いたイベントとして届きます。イベントログでは、トラップのバッジが付きます。

組み込みのトラップ用イベントルールも同梱しているので、よくあるトラップは最初から分類されます。

コミュニティのフィルタを設定することもできます。設定すると、コミュニティ文字列が一致しないトラップ を捨てます。

Terminal window
YAGRA_TRAP_COMMUNITY=mycommunity   # unset = accept all communities

設定した値がログに出ることはありません。なお、SNMPv3 のトラップにはまだ対応していません。 トラップのリスナーが扱えるのは v1 と v2c だけです。

トラップの受信を最初から最後まで確かめるには、Net-SNMP を入れたホストから標準の linkDown トラップ を送ってください。名前の付いたイベントとして届けば成功です。

Terminal window
snmptrap -v 2c -c public <yagra-host>:162 '' 1.3.6.1.6.3.1.1.5.3 1.3.6.1.2.1.2.2.1.1 i 2

Webhook ソース

Section titled “Webhook ソース”

3 つ目の受信経路は、他のシステムが HTTPS でイベントを送り込むためのものです。バックアップのジョブ、 CI のパイプライン、クラウドサービスのアラートフックなどが使います。

Webhook のソースは、イベント ▸ Webhook 送信元で作ります。ソースごとに、自分のイベントが属する ノードを指定し、専用の Bearer トークンを持ちます。

送信側は、コアの API ポート上にあるそのソースのエンドポイントへ POST します。

Terminal window
curl -X POST "http://<yagra-host>:8080/api/v1/ingest/webhook/<source-id>" \
  -H "Authorization: Bearer <source-token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "nightly backup failed on db-01"}'

送るデータの形は、意図的に緩くしてあります。ボディが JSON オブジェクトなら、その message・text・ summary のいずれかがイベントの本文になります。それ以外のボディは、そのまま受け取ります。

返すコードは、意図的に区別してあります。自動化した送信側が、何が悪かったのか判断できるようにする ためです。

  • 202 — 受理しました（イベントの id を返します）
  • 401 — トークンが違います
  • 404 — 知らないソース、または無効にされたソースです
  • 413 — ボディが大きすぎます
  • 429 — そのソースがレート制限を超えました
  • 503 — このコアではイベントの取り込みが使えません。設定していないか、高可用性のペア構成で リクエストがスタンバイに届いたかのどちらかです

イベントルール

Section titled “イベントルール”

ルールはアラート ▸ イベントのアラートルールにあり、生のイベントを分類済みでアラート可能な信号へ変えます。 ルールは次の要素で組み立てます。

  • 一致条件 — イベントの本文に対する部分一致か、正規表現です。任意で 1 つのストリーム（syslog、 トラップ、Webhook）に限定できます。あるソース向けに書いたパターンが、別のソースで発火するのを 防げます。
  • 重大度 — 一致したイベントの重大度です。これがイベントログ、ダッシュボードウィジェット、そして ルールが上げるアラートを動かします。
  • 自動で解消するアラート — ルールは、イベントを送ってきたノードに対して実際のアラートを上げられ ます。イベントのアラートは TTL（有効期間）を持ち、それが切れると自動的に解消します。イベントの アラートが閉じるのは、この TTL によってだけです。
  • 解消パターン — アラートを早く閉じるための、2 つ目のパターンです（任意）。これがあると link up のメッセージが、対になる link down の上げたアラートを、TTL を待たずに閉じられます。
  • 発報のしきい値 — 「M 秒間に N 件」という条件です。1 件では単なるノイズのパターン（たまに起きる 認証失敗など）を、嵐になったときだけアラートにできます。

知っておく価値のある挙動が 2 つあります。

  • イベント由来のアラートは、意図的に依存関係の抑制を通りません。イベントを送ってきたばかりの デバイスは明らかに到達できているので、まとめるべき上流の障害が存在しないからです。
  • このコアが知らないストリーム種別に限定されたルールは、照合の対象から外され、ログに記録されます。 黙ってすべてのストリームへ広がることはありません。こうしたルールは、たとえば新しい WebUI が、 まだそれを知らない古いコアにルールを書き込んだアップグレードの途中で生まれます。

レート制限

Section titled “レート制限”

イベントの洪水は、バスにもデータベースにも何かが届く前に、エッジすなわちポーラー上で抑えられます。 syslog とトラップの受信は、送信元 IP をキーにしたトークンバケットのリミッタを共有します。

制限 既定 変数
送信元 IP ごと 200 イベント/秒 YAGRA_EVENT_RATE_PER_SOURCE
グローバル（全ソース） 5000 イベント/秒 YAGRA_EVENT_RATE_GLOBAL

どちらも、持続レートの 2 倍までの一時的な増加を許します。ですから数秒ぶんのメッセージをまとめて 送ってくる機器が切り捨てられることはありません。切り捨てられるのは、本当にループしている機器だけ です。

暴走した送信元 1 台は、フリート全体の 5000/秒の枠を圧迫するはるか手前で、自分の 200/秒の上限に 当たります。

Webhook のソースは、API 側でソースごとに別のレート制限がかかります。超えた送信側は 429 を受け取る ので、間隔を空けて送り直せます。フローのデータグラムには、独立した別の枠があります （トラフィックフローを見てください）。

イベント側の 2 つの制限は、どちらも調整できます。 設定リファレンスを見てください。

イベントの閲覧と検索

Section titled “イベントの閲覧と検索”

イベント ▸ イベントは、受け取ったものをすべて表示します。ルールに一致したものも、しなかったものも です。絞り込みは、列ごとに行います。

  • 種別と結果は、複数選べます。結果が表すのは、ルールが一致したかどうかではなく、何をしたか です（発報／更新／解除／抑制）。
  • メッセージと送信元は、条件を選べます。部分一致、正規表現（メッセージのみ）、除外の 3 つ です。
  • 日時は、よくある期間のプリセットです。開始と終了を自分で指定したいときは、「期間を指定…」の 下にあります。

絞り込みの条件はすべて URL に入ります。ですから絞り込んだ画面を、そのままリンクとして渡せます。

普通に入力した検索語は、大文字小文字を区別しません。SSH で ssh も見つかります。既定の期間が 過去 24 時間なのは、その代償です。期間を区切らずに検索すると、大文字小文字を区別しない検索は 区別する検索の約 10 倍かかります。1 日に区切れば、ほぼ同じ速さです。「全期間」にしたいときは、期間の ドロップダウンから選ぶだけです。

一致しなかったイベントは、ときどき眺める価値があります。まだどのルールも分類していない、フリートが 送っているメッセージだからです。

普通の語がどう当たるかは、ストアによって変わります。今どちらなのかは画面が表示します。

VictoriaLogs では、語の先頭から当たります。POLICY は POLICYPERMIT を見つけますが、 PERMIT は見つけません。語の途中に当てるには期間全体を走査することになり、約 15 倍遅いから です。

途中まで当てたいときは、正規表現のスイッチの下にあります。なお普通の語で 1 件も見つからなかった 場合、画面はもう一度、語の途中まで見て探し直します。そしてそうしたことを表示します。

PostgreSQL では、普通の語がそのまま部分一致します。ですからどちらの書き方でも当たります。自分の デプロイがどちらかは、GET /api/v1/system-health が search_semantics として返します。

同じイベントの流れは、切り分けをする画面にも出ます。

  • どのノードの詳細ページにも、そのノードに限った Events タブがあります。
  • ダッシュボードには、パッシブ監視のウィジェットがあります。最新イベント、イベント量、イベント種別、 トラップ種別の上位、処理結果、いちばん騒がしい送信元、ルールのカバレッジです。

既定では、イベントは PostgreSQL に保存・検索されます。中くらいの量ならこれで十分で、追加のものは 要りません。

本格的な量になったら、YAGRA_LOGS_URL を VictoriaLogs のインスタンスへ向けてください。イベントの 保存と検索が、大量の履歴に対する全文検索のために作られた専用のログストアへ移ります。

単一ノードの compose スタックには、URL を設定済みの VictoriaLogs サービスが最初から入っています。 ですからそこでは既定でこちらになります。自分で組んだデプロイでは、自分で有効にします。どちらでも UI と API は同じです。

AI のクライアントも、同じ流れを見られます。MCP ツールの search_events と event_stats が、イベント 検索と切り分け用の統計を渡します。統計の中身は、いちばん騒がしいノード、重大度の内訳、どのルールにも 一致しなかったシグネチャです。

検索・並べ替え・ページ送りはすべて、イベントが発生した時刻に基づきます。Yagra が取り込んだ時刻 ではありません。

時刻順のログである以上、避けられないことが 1 つあります。リモートポーラーが障害から復帰して、ためて いたものを送り直すと（store-and-forward）、その古いイベントは本来の位置に挿入されます。つまり、 すでにスクロールして通り過ぎたページの中に入ることがあります。

イベントを先へ転送する

Section titled “イベントを先へ転送する”

リスナーが受け取ったものは、すべて SIEM や別のコレクタへ中継できます。元のデータグラムがあるものは、 受け取ったバイト列のまま送れます。長く問い合わせたい場合は、正規化した行として BigQuery へ流すことも できます。

転送は、迂回ではなく分岐です。データが他のどこへ行こうと、Yagra は照合もアラートも保存も続けます。 詳しくは転送を見てください。

関連ページ

Section titled “関連ページ”