テレメトリデータプレーン

Ongrid edge は 2 つの物理パス で manager と話します：

コントロールプレーン —— geminio トンネル（ADR-001 / ADR-007）。edge ライフサイクル、RPC、ハートビート、アラートイベント、メトリクスプッシュ（push_prom_samples）に使用。
テレメトリデータプレーン —— edge から manager の公開取り込みエンドポイントへの直接アウトバウンド HTTPS POST。ログ（Loki API）とトレース（OTLP）に使用。

このページが分割、認証モデル、メトリクスの移行トリガーを説明します。

このページは簡潔なリファレンスです。完全な決定記録はソースツリーの ADR-014 です。

分割

プレーン	チャネル	運ぶもの
コントロールプレーン	geminio トンネル（既存 ADR-001）	edge ライフサイクル、RPC、ハートビート、アラートイベント、メトリクスプッシュ（当面）
テレメトリデータプレーン	edge → manager 公開 HTTPS、独立のアウトバウンド接続	ログ（ADR-012）、トレース（ADR-013）

両プレーンとも edge からアウトバウンド —— エージェントが manager にダイヤルします。edge にインバウンドポートなし。

なぜ分割か？

geminio トンネルはコントロール RPC バスとして設計されました。1 つの永続接続内で低レイテンシ RPC 呼び出しを多重化します。メトリクスプッシュは ADR-009 で追加された「無料の便乗」でした —— メトリクスボリュームが小さく（edge あたり数 KB/s）、トンネルに余裕があったからです。

ログとトレースは小さくありません。

シグナル	edge ごと steady state	edge ごとピーク
メトリクス	数 KB/s	〜10 KB/s
ログ	数十 KB/s	1–10 MB/s
トレース	サンプルレートに依存	ログに匹敵

100 edge × 1 MB/s = manager で 100 MB/s 持続インバウンド。トンネルはそれ用に設計されていません。ログとトレースをそれに通すと 2 つの問題に当たります：

manager CPU が溶ける。 トンネルフレームのエンコード/デコード + 下流ストアへの転送が Go プロセスで起きる。nginx + 下流ストア直接のほうが数倍安い。
HOL ブロッキング。 高スループットバイトストリームが mux 上でコントロール RPC と競合。operator が「edge 42 の何が悪い？」と訊くと秒オーダーのジッターを経験する。

トンネルはコントロールプレーン。データプレーンはデータプレーン。混ぜることは NAT 制約下の便宜でした。分割が境界を明示します。

アーキテクチャ

text

                                      ┌──────────────────────────────┐
   ┌──────────────┐                    │           manager            │
   │ ongrid-edge  │                    │                              │
   │              │                    │  nginx :443  ──► /api/* ───► ongrid (manager)
   │  ┌─────────┐ │   geminio tunnel   │                              │
   │  │  agent  │ ├────► :40012 ──────►│  frontier (geminio broker) ──┤
   │  └─────────┘ │   (control plane)  │                              │
   │              │                    │  nginx :443  ──► /loki/* ───► loki      ← data plane
   │  ┌─────────┐ │                    │              ──► /v1/traces ─► tempo    ← data plane
   │  │promtail │ ├────► :443 ────────►│              ──► /api/v1/write─► prom (today)
   │  └─────────┘ │   (data plane)     │                              │
   │              │                    │  edgeauth verifies the token │
   │  ┌─────────┐ │                    │  via /internal/auth/         │
   │  │otelcol  │ ├────► :443 ────────►│  dataplane-verify before     │
   │  └─────────┘ │   (data plane)     │  proxying.                   │
   └──────────────┘                    └──────────────────────────────┘

エージェントはプラグイン（promtail、otelcol-contrib）ごとに 1 つの TLS 接続を使います。すべて edge から ONGRID_PUBLIC_URL へのアウトバウンドです。

認証

1 つの信頼ルート、2 つのパス。

edge の access-key/secret-key ペアが geminio のセッション認証情報でトンネルを認証します。同じ認証情報ペアがデータプレーン HTTPS POST ごとに使われる Bearer トークンに交換されます。nginx の auth_request ディレクティブがトークンを検証するため manager の /internal/auth/dataplane-verify にコールバックします。200 でリクエストは Loki または Tempo にプロキシされます。401/403 で edge は HTTP エラーを見てバックオフします。

これが意味すること：

edge の secret_key のローテーションは 両プレーンを同時に 無効化。
2 つ目の secrets ストアも、プラグインごと認証情報も、別個の ACL もない。
認証は manager 所有 —— Loki と Tempo は edge アイデンティティを直接見ない。

Bearer トークンは短命です。エージェントはトンネル経由で透過的にリフレッシュします。トンネルが長時間ダウンしている edge はトークン期限切れでデータプレーン POST が 401 になり始め、トンネル再接続を強制します。

NAT 互換性

manager の公開ポートへのアウトバウンド HTTPS は、アウトバウンドトンネルと同じネットワーククラスです —— 両方が edge から単一の宛先ポート範囲（データは 443、トンネルは 40012）に発信されます。両方とも通常の企業 egress ファイアウォールを通ります。特別な穴あけなし、インバウンドルールなし。

1 つのアウトバウンド接続しか開けない NAT 限定の edge には、geminio に raw-stream フォールバック（zstd 圧縮ログペイロード、有界バッファ、オーバーフロー時 drop-old）があります。これは脱出ハッチであってデフォルトではありません —— まだ顧客に出荷する必要はありませんでした。

メトリクスは？

push_prom_samples は今日 依然トンネル上 です。

トンネルに残した理由
edge ごとメトリクスボリュームが飽和を遥かに下回る。
既存パスが動く。現在の便益を上回る移行コスト。
`push_prom_samples` はリリースごとに動かされる。触るのはリスキー。

以下のいずれかが成立したらメトリクスをデータプレーン（https://<manager>/api/v1/write 直接 Prometheus remote_write）に移します：

単一 manager のトンネル CPU が持続 > 60%。
単一 edge のメトリクスプッシュレートが持続 > 100 KB/s（ほぼ常に暴走カーディナリティを意味する —— まずそれを直す。それでも残ったら移行）。
メトリクスストリーム圧力下でコントロール RPC P95 レイテンシが > 500ms 劣化。

Prometheus remote_write クライアントはすでに node_exporter にあり、edge のメトリクスプラグインは env 経由で再向け可能です。上のトリガーは優先度を設定するだけです。

edge 実装

ディスク上、エージェントはすべてのテレメトリ送信者を internal/edgeagent/dataplane/ を通して出荷します。そのパッケージが以下を中央化します：

トンネルセッション認証情報からのトークン再利用。
二重宛先ルーティング（コントロールはトンネル、データは HTTPS）。
ジッター付き指数バックオフのリトライ。最大 1 分でキャップ。
ローカル有界キュー（インメモリ。エージェントはディスクにスプールしない）。

各プラグイン（promtail、otelcol-contrib、将来のもの）がこのパッケージを消費します —— プラグインごとリトライ / 認証ロジックはありません。これが ongrid-edge を単一バイナリ + 4 サブプロセスに保ちます。プラグインごと sidecar も、プラグインごと systemd unit もありません。

チューンするもの

変数	場所	効果
`ONGRID_PUBLIC_URL`	manager	edge にデータプレーンルートとして渡される URL。データプレーン動作に必須。
`ONGRID_LOG_QUERY_URL`	manager	読み取りパス —— Logs ページ用 manager → Loki。edge プッシュとは独立。
`ONGRID_TRACE_QUERY_URL`	manager	読み取りパス —— Traces ページ用 manager → Tempo。
`ONGRID_EDGE_PLUGIN_BIN_DIR`	edge	プラグインバイナリ（promtail、otelcol-contrib）の場所。
`ONGRID_EDGE_PLUGIN_WORK_DIR`	edge	プラグインごとランタイム dir（設定、PID、キュースプール）。

ONGRID_PUBLIC_URL は manager 側で最も重要な本番設定です。空でデータプレーンが完全に無効化されます —— edge はトンネルで接続し、エージェントは起動しますが、ログとトレースは決して出荷されません。

テレメトリデータプレーン ​

分割 ​

なぜ分割か？ ​

アーキテクチャ ​

認証 ​

NAT 互換性 ​

メトリクスは？ ​

edge 実装 ​

チューンするもの ​

関連 ​