アノテーション駆動のモニタリング — 1 つのアノテーションで多数のコンポーネントに
この例では、コンポーネントごとの features: ブロックを 1 つも書かずに、モニタリング用の Feature をネストしたトポロジー全体の 6 つのサービスにアタッチします。最上位のバウンダリーに付けた 1 つのオペレーターアノテーションを 2 つのサブツリーのオーバーライドで調整すると、それが Manifest の features.annotations バインディングを介して、含まれるすべてのコンポーネントへの
core/prometheus-exporter のアタッチメントに展開され、各コンポーネントがそれぞれ Prometheus の ServiceMonitor をレンダリングします。
これがアノテーション駆動の Feature 展開の仕組みです。コンポーネントごとに繰り返される Feature のアタッチメントを、バウンダリーツリーを下方向にカスケードする 1 つのアノテーションに集約するためのパターンです。
構成
- **開発者の意図(
aggregate.yaml)**では、6 つのexample/compute/serviceコンポーネント(gatewayと、api/worker/ledger/etl/reconcile)だけを宣言します。モニタリング用のfeatures:ブロックを持つコンポーネントは 1 つもありません。 - **Manifest(
manifest.yaml)**は、アノテーションを Feature にバインドします。features:type:core/prometheus-exporter: helm/prometheus-exporter:1.0.0 # the FeatureRecipe version bindingannotations:feature.aggrega.ai/monitoring:feature: core/prometheus-exportermaps:infra: [interval, port, path] # structured-value subkeys → the feature's infra - **Release(
release.yaml)**は、platformバウンダリーにアノテーションを 1 度だけ設定し、サブツリーごとに調整します。platform:annotations:feature.aggrega.ai/monitoring: {interval: 30s, port: metrics, path: /metrics} # gateway inherits thisboundaries:payments:annotations:feature.aggrega.ai/monitoring: {interval: 15s} # api/worker/ledgerbatch:annotations:feature.aggrega.ai/monitoring: {interval: 120s} # etl/reconcile
core/prometheus-exporter と、そのコンポーネントスコープの ServiceMonitor FeatureRecipe は標準カタログから利用します(この例ではローカルのコピーを宣言しません)。レシピのチャートは、アタッチされたコンポーネントごとに monitoring.coreos.com/v1 ServiceMonitor を 1 つ出力し、解決済みのアノテーションから interval/port/path をテンプレート化します。この 3 つはいずれも、フィーチャーの infra にあるオペレーター用のスクレイプ設定です。(これは FeatureRecipe によるリソース生成(helm プロバイダーがレンダリングする source: + valuesMapping:)であり、Wasm のミューテーターやパイプラインステップではありません。)
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example annotation-driven-monitoringその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd annotation-driven-monitoringビルド
pull がロックファイルを解決し、ビルドがそれを読み込みます。
aggrega pull --release release.yamlaggrega build --release release.yamlAI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーを自分で作成しないでください。ワークスペースフォルダーにまだ `annotation-driven-monitoring` フォルダーがない場合は、`example` を `annotation-driven-monitoring` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、サンプルが新しい `annotation-driven-monitoring` フォルダーに書き出されます。次に、`workspace_root` を `annotation-driven-monitoring`、`release` を `release.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き出したファイルを教えてください。ファイルは `annotation-driven-monitoring/dist/` の下にあります。レンダリング結果が示すこと
ロックファイルを解決してビルドし、dist/<boundary>/helm/<component>--feature-zdaggrega-zdai-zsmonitoring--<component>-servicemonitor-<component>-scrape.yaml を確認します。
aggrega pull --release release.yamlaggrega build --release release.yaml**このファイル名は誰も入力していないので、読み解いてみる価値があります。**このターゲットはディレクトリ直下のファイルしか読まないため、アタッチメントのファイルはコンポーネント自身のファイルの隣に置かれ、2 つの座標をディレクトリ階層ではなくファイル名に持ちます。1 つ目は Feature のアタッチ先のコンポーネント、2 つ目はアタッチ時の名前です。ここでの 2 つ目の座標は誰かが書いた名前ではなく、アノテーションが生成したもので、アノテーションキーそのもの
feature.aggrega.ai/monitoring です。ドットとスラッシュはそのままではファイル名に入れられないため、それぞれ -z と 1 文字に置き換えられます。ドットは -zd、スラッシュは -zs です。payments バウンダリーの api コンポーネントについて、ビルドは次のファイルを書き出します
dist/payments/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-api-scrape.yamlこのエンコードにより、キー内のスラッシュが独自のディレクトリを作ることはありません。これが重要なのは、1 階層下にあるファイルは、バウンダリーディレクトリを読むスクレイプ設定のコンシューマーには拾われないからです。
この例では、core/prometheus-exporter とその ServiceMonitor FeatureRecipe(および helm プロバイダー)を標準ライブラリから利用します。デモ用の example/compute/service コンポーネントとそのレシピは、共有カタログ内の example/ パブリッシャーの下に、これらの標準ライブラリのエンティティと並んで置かれています。この例の .aggrega-config.yaml は hub.aggrega.ai をデフォルトのレジストリとして宣言しているため、エンティティはハブから解決されます。どちらのコマンドにも --catalog フラグは不要です。
| Component | バウンダリー | interval | port | path |
|---|---|---|---|---|
gateway | platform | 30s(platform のデフォルト) | metrics | /metrics |
api / worker / ledger | payments | 15s(オーバーライド) | metrics | /metrics |
etl / reconcile | batch | 120s(オーバーライド) | metrics | /metrics |
この表で具体的に示される 3 つの事実:
- 作成者の宣言ではなく、アノテーション駆動。 Aggregate にはモニタリング用の
features:がどこにもないのに、6 つの ServiceMonitor がレンダリングされます。これらが存在するのは、アノテーションがcore/prometheus-exporterを各コンポーネントに展開したからだけです(ビルドグラフにおけるアタッチメントのoriginはexplicitではなくannotationです)。 - サブキー単位のディープマージ。
paymentsとbatchはintervalしか設定していませんが、 その ServiceMonitor はport: metricsとpath: /metricsを持ちます。これらは platform アノテーションの構造化された値から継承され、サブキー単位でマージされたものです。サブツリーは 1 つのフィールドをオーバーライドしながら、兄弟フィールドを継承します。 - ファンアウト。 6 つのコンポーネントが、1 つの platform アノテーションと
2 つの 1 行のオーバーライドだけでモニタリングされます。コンポーネントごとに
features:ブロックを繰り返す必要はありません。
ServiceMonitor は Service の名前付き metrics ポートをスクレイプします(合成された
Service は metrics: 9090 を公開します)。そのため、バインディングの port: metrics は実在するエンドポイントに解決されます。
コンパイル時とランタイム
これは Kubernetes/Helm の例であり、その証拠は
dist/ 内のレンダリングされたマニフェストです。ServiceMonitor の port は Service の名前付きポートを参照しているため、セレクターとエンドポイントは構造上一致し、配線の検証にクラスターは必要ありません。稼働中の Prometheus Operator であれば、デプロイ時にレンダリングされた ServiceMonitor を利用します。コンパイラの役割(アノテーション → カスケードで解決されたプロファイルを持つコンポーネントごとの ServiceMonitor)は、事前に完了しており、確認することができます。
ビルドは決定的です。再実行しても出力はバイト単位で同一です。