パッシブイベント

能動的なポーリングは、機器に「調子はどうか」と尋ねます。パッシブイベントはその逆向きです。機器のほうが先に話しかけ — syslog の 1 行、SNMP トラップ、別システムからの Webhook — Yagra はそれを聞き、メッセージを送信元のノードへ結び付け、アラートに値するかどうかを判断します。

概要

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）も含みます。

リスナーの有効化

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`）

# .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 を使っている場合は、公開するポートをずらしてください。
ポーラーは特権ポートをバインドできません。 非 root コンテナとして動くため、非特権ポートの 1514 と 1162 をバインドし、compose がホスト側で標準の低位ポートをそこへマップします。ホストネットワークやネイティブインストールではポートマッピングがありません — 機器を直接その高位ポートへ向けるか、ファイアウォールで 514 / 162 をそこへリダイレクトしてください。正確な iptables の REDIRECT ルールはポートとファイアウォールにあります。

syslog

syslog リスナーは RFC 5424（現代的で構造化されたもの）と RFC 3164（従来の BSD 形式）の両方のメッセージを受け付けます。そのためルータ、スイッチ、ファイアウォール、Unix ホストは、いずれも既存の syslog 設定を変更せずそのまま Yagra へ向けられます。パースではファシリティ、重大度、ホスト名、アプリケーション名、メッセージ本文を取り出します — イベントルールが突き合わせるフィールドであり、のちに転送のフィルタが選別に使えるのと同じフィールドです。

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

リスナーに届いているかを確かめるには、任意の Linux ホストからテスト行を送ってアラート ▸ イベント で確認します。

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

SNMP トラップ

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

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

受信したトラップはトラップ OID を人が読める名前へ解決するので、トラップは生の OID ではなく名前付きのイベントとして届き、イベントログではトラップのバッジが付きます。組み込みのトラップ用イベントルールも Yagra に同梱されているため、よくあるトラップは最初から分類されます。

任意のコミュニティフィルタを設定すると、コミュニティ文字列が一致しないトラップを破棄します。

YAGRA_TRAP_COMMUNITY=mycommunity   # unset = accept all communities

設定した値がログに出ることはありません。SNMPv3 のトラップはまだ未対応です — トラップリスナーは v1/v2c のみです。

トラップの受信を端から端まで確かめるには、Net-SNMP を入れた任意のホストから標準の linkDown トラップを送り、名前付きのイベントとして届くのを確認します。

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 ソース

3 つ目の受信経路は、他のシステムが HTTPS でイベントを送り込むためのものです — バックアップジョブ、 CI パイプライン、クラウドサービスのアラートフックなど。Webhook ソースはアラート ▸ イベントソース で作成します。各ソースは自分のイベントが属するノードを指定し、専用の Bearer トークンを持ちます。

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

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 は、このコアではイベント取り込みが利用できないことを意味します — 未設定であるか、高可用性のペア構成でリクエストがスタンバイに届いたかのどちらかです。

イベントルール

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

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

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

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

レート制限

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

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

いずれも持続レートの最大 2 倍までのバーストを許容するため、数秒分のメッセージをまとめて送る機器が切り詰められることはなく、本当にループしている機器だけが切り詰められます。1 台の暴走した送信元は、フリート全体の 5000/秒の予算を圧迫するはるか手前で自分の 200/秒の上限に当たります。

Webhook ソースは API 側でソースごとに別途レート制限されます — レートを超えた送信側は 429 を受け取り、バックオフできます。フローのデータグラムには独立した別の予算があります（トラフィックフローを参照）。

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

イベントの閲覧と検索

アラート ▸ イベントは、一致したものもしなかったものも含めて受信したすべてを表示します。ストリーム種別（syslog / トラップ / Webhook）、一致か未一致か、ノード、期間で絞り込めるほか、正規表現のトグルを備えたテキスト検索もあります。未一致のイベントは定期的に眺める価値があります。それは、まだどのルールも分類していない、フリートが送っているメッセージだからです。

同じイベントストリームは、切り分けを行う画面にも現れます。

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

既定ではイベントは PostgreSQL に保存・検索されます。中程度の流量ならこれで十分で、追加のものは何も要りません。本格的なイベント流量に対しては、YAGRA_LOGS_URL を VictoriaLogs のインスタンスへ向けると、イベントの保存と検索が、大量の履歴に対する全文検索のために作られた専用のログストアへ移ります。単一ノードの compose スタックには URL 設定済みの VictoriaLogs サービスが最初から含まれているため、そこでは既定でこちらになります。自前で組んだデプロイではオプトインです。どちらであっても UI と API は同じです。

AI クライアントも同じストリームを見られます。MCP ツール search_events と event_stats が、イベント検索と切り分け用の統計（最も騒がしいノード、重大度の内訳、一致しなかったシグネチャ）を MCP 対応のアシスタントへ公開します。

検索・並べ替え・ページングはすべて、Yagra が取り込んだ時刻ではなくイベントが発生した時刻に基づきます。時刻順のログである以上、避けられないことが 1 つあります。リモートポーラーが障害から復帰してバッファしていたものを再生すると（store-and-forward）、その古いイベントは本来の位置に挿入されます — つまり、すでにスクロールして通り過ぎたページの後ろに入ることがあります。

イベントを先へ転送する

リスナーが受信したものはすべて、SIEM や別のコレクタへ中継することもできます — 元のデータグラムが存在するものは受信したバイト列のまま — あるいは長期的な問い合わせのために、正規化された行として BigQuery へストリーミングすることもできます。転送は迂回ではなくティーです。データがほかのどこへ行こうと、Yagra は照合もアラートも保存も続けます。転送を参照してください。