Prometheus

基本情報

項目	内容
モジュールパス	.
種別	監視システム（時系列データベース + メトリクス収集 + クエリエンジン + アラート）
ファイル数	6
サブモジュール数	21

概要

Prometheus は、CNCF（Cloud Native Computing Foundation）が管理するオープンソースの監視・アラートシステムであり、メトリクスの収集（スクレイプ）・格納（TSDB）・クエリ（PromQL）・アラート通知を一体的に提供する。サービスディスカバリ（30 以上のクラウド/インフラプロバイダに対応）で動的にターゲットを発見し、HTTP エンドポイントからメトリクスを定期収集してローカルの時系列データベースに永続化する。PromQL クエリ言語による柔軟なデータ分析、Recording Rule / Alerting Rule によるプリコンピュテーションとアラート生成、Alertmanager 連携による通知ディスパッチ、Remote Write/Read プロトコルによる外部ストレージ統合、Web UI / REST API によるユーザーインターフェースを備える。Go 言語で実装され、単一バイナリ（prometheus サーバーと promtool CLI）として配布される。

設計パターン

パターン名	適用範囲	説明
Actor Model	cmd/prometheus（run.Group）	各コンポーネント（TSDB, Scrape, Rule, Notifier, Web, Tracing, Discovery）を独立した goroutine として管理し、一つが終了すると全体をグレースフルシャットダウン
Strategy	discovery, storage, promql	Discoverer / Storage / QueryEngine 等のインターフェースにより、実装の差し替えを可能にする
Registry (Self-Registration)	plugins, discovery	各 SD プロバイダが `init()` でグローバルレジストリに自己登録するプラグインアーキテクチャ
Observer / Pub-Sub	discovery → scrape/notifier	ディスカバリマネージャーがチャネル経由でターゲット更新を下流に配信
Proxy / Fan-out	storage	primary + secondaries への読み書きを透過的に分配するファンアウトストレージ
Template Method	Makefile.common + Makefile	共通ビルドフローの骨格を定義し、プロジェクト固有の処理をオーバーライド
Pipeline	scrape → storage → promql	メトリクスのスクレイプ → パース → リラベル → ストレージ書き込み → クエリ評価の段階的処理
Builder / Validation Chain	config	YAML パース → デフォルト適用 → バリデーションのチェーン構造で設定を構築

アーキテクチャ

モジュール構成

prometheus/
├── .github/  - Prometheus プロジェクトの GitHub プラットフォーム統合設定を一元管理するモジュールである。
├── cmd/  - Prometheus プロジェクトが提供する 2 つの実行バイナリ（`prometheus` サーバーと `promtool` CLI ユーティリティ）のエントリーポイントを集約するモジュール。
├── compliance/  - Prometheus の Remote Write 送信機能が外部仕様に準拠しているかを検証するコンプライアンステストモジュール。
├── config/  - Prometheus の YAML 設定ファイルを Go の構造体にパース・バリデーションするための中核パッケージ。
├── discovery/  - Prometheus のサービスディスカバリ（SD）サブシステムの中核フレームワーク。
├── documentation/  - Prometheus プロジェクトのドキュメント資産、リファレンス実装、およびセルフモニタリング定義を統合的に管理するモジュール。
├── internal/  - `internal` は、Prometheus プロジェクトの内部専用ユーティリティを格納するトップレベルディレクトリである。
├── model/  - Prometheus のコアデータモデル層を構成する最上位モジュール。
├── notifier/  - Prometheus のアラート通知サブシステムを実装するモジュール。
├── plugins/  - Prometheus のサービスディスカバリ（SD）プラグインをビルド時に選択的に登録するためのモジュール。
├── prompb/  - Prometheus のリモートストレージ通信プロトコル（Remote Write / Remote Read）のデータ型定義・シリアライズ・コーデック変換を一元的に提供するモジュール。
├── promql/  - Prometheus の PromQL（Prometheus Query Language）クエリ実行エンジンの中核モジュール。
├── rules/  - Prometheus のルール評価エンジンのコア実装を提供するモジュール。
├── schema/  - Prometheus のメトリクススキーマメタデータ（メトリクス名・型・単位）をラベルとして統一的に管理するためのドメインモデルおよびユーティリティを提供するモジュール。
├── scrape/  - Prometheus のメトリクススクレイピングサブシステムの中核モジュール。
├── storage/  - Prometheus のストレージ層における中核的な抽象レイヤーを提供するモジュール。
├── template/  - Prometheus のアラートルール通知文面および Web コンソール画面で使用されるテンプレート展開エンジンを提供するモジュール。
├── tracing/  - Prometheus の分散トレーシング機能を一元管理するモジュール。
├── tsdb/  - Prometheus の時系列データベース（TSDB）の中核モジュールであり、float サンプル・ネイティブヒストグラム・Exemplar の永続的なストレージエンジンを実装する。
├── util/  - Prometheus プロジェクト全体で共有される横断的ユーティリティ機能を集約したトップレベルモジュール。
├── web/  - Prometheus サーバーの HTTP レイヤー全体を統括するモジュール。
├── .golangci.yml  - Prometheus プロジェクトにおける golangci-lint v2 の設定ファイル。
├── .promu.yml  - Prometheus プロジェクトのビルドツール **promu**（Prometheus Utility Tool）の設定ファイル。
├── Dockerfile  - Prometheus 監視システムのコンテナイメージを定義する Dockerfile。
├── Makefile  - Prometheus プロジェクトのトップレベルビルド定義ファイル。
├── SECURITY-INSIGHTS.yml  - Prometheus プロジェクトのセキュリティに関するメタデータを [Security Insights specification (v1.0.0)](https://github.com/ossf/security-insights-spec) に準拠して定義する YAML ファイル。
└── renovate.json  - Prometheus リポジトリにおける [Renovate Bot](https://docs.renovatebot.com/) の設定ファイル。

コンポーネント関連図

Mermaid形式:

graph TD
    SD["discovery/<br/>Service Discovery<br/>(30+ providers)"] -->|ターゲット配信| SM["scrape/<br/>Scrape Manager"]
    SM -->|メトリクス取得| TP["model/textparse/<br/>メトリクスパーサー"]
    TP -->|パース結果| ST["storage/ + tsdb/<br/>TSDB ストレージ"]
    ST -->|Remote Write/Read| RS["storage/remote/<br/>リモートストレージ"]

    CFG["config/<br/>設定パーサー"] -->|ApplyConfig| SM
    CFG -->|ApplyConfig| RM["rules/<br/>Rule Manager"]
    CFG -->|ApplyConfig| NM["notifier/<br/>Notifier Manager"]
    CFG -->|ApplyConfig| TR["tracing/<br/>Tracing Manager"]

    RM -->|PromQL 評価| PQ["promql/<br/>PromQL Engine"]
    PQ -->|クエリ| ST
    RM -->|アラート生成| NM
    NM -->|HTTP POST| AM["Alertmanager"]

    WEB["web/<br/>Web Handler + API"] -->|クエリ API| PQ
    WEB -->|UI 配信| UI["web/ui/<br/>React UI"]
    WEB -->|メタデータ| ST

    CMD["cmd/prometheus/<br/>メインエントリ"] --> SM
    CMD --> RM
    CMD --> NM
    CMD --> WEB
    CMD --> SD
    CMD --> TR
    CMD --> ST

    TOOL["cmd/promtool/<br/>CLI ユーティリティ"] -->|設定検証| CFG
    TOOL -->|ルールテスト| RM
    TOOL -->|TSDB 操作| ST

    MODEL["model/<br/>コアデータモデル"] -.->|Labels, Histogram, etc.| SM
    MODEL -.-> PQ
    MODEL -.-> ST
    MODEL -.-> RM

機能一覧

機能名	説明	主要モジュール
メトリクス収集（スクレイプ）	HTTP エンドポイントからメトリクスを定期収集。Content-Type に応じた自動パーサー選択	scrape, model/textparse
サービスディスカバリ	30 以上のプロバイダ（AWS, Azure, K8s, Consul, DNS 等）によるターゲット動的検出	discovery, plugins
時系列データベース（TSDB）	ブロックベースの時系列ストレージ。WAL、OOO サンプル、コンパクション、リテンション管理	tsdb
PromQL クエリエンジン	80 種以上の組み込み関数、ネイティブヒストグラム対応、同時実行制限	promql
Recording Rule	PromQL 式の結果を新時系列として事前計算・記録	rules
Alerting Rule	条件式に基づくアラート状態管理（Pending → Firing）と Alertmanager 連携	rules, notifier
Remote Write/Read	Protocol Buffers ベースのリモートストレージ統合（v1/v2 プロトコル対応）	storage/remote, prompb
Web UI / REST API	React ベース UI、PromQL クエリ API、メタデータ API、管理 API	web
フェデレーション	上位 Prometheus からのメトリクス収集サポート	web
設定ホットリロード	SIGHUP / HTTP API / 自動検出によるランタイム設定更新	config, cmd/prometheus
分散トレーシング	OpenTelemetry SDK による OTLP gRPC/HTTP トレース出力	tracing
OTLP 受信	OpenTelemetry メトリクスの受信・変換	web, storage/remote
ラベルリラベリング	正規表現ベースのラベル変換・フィルタリング	model/relabel
テンプレートエンジン	アラート通知文面・コンソール画面の動的レンダリング	template
コンプライアンステスト	Remote Write 送信者準拠性テスト（サーバー/エージェントモード）	compliance
CLI ユーティリティ	設定/ルール検証、PromQL クエリ、TSDB 操作、メトリクスプッシュ	cmd/promtool
ビルドシステム	Go バイナリ + React UI のクロスプラットフォームビルド、Docker イメージ作成	Makefile, .promu.yml, Dockerfile
CI/CD パイプライン	テスト・ビルド・リリース・セキュリティスキャンの自動化	.github/workflows
セルフモニタリング	Prometheus 自身の健全性監視（Monitoring Mixin: アラート + ダッシュボード）	documentation/prometheus-mixin

公開インターフェース

クラス / 関数

名前	モジュール	種別	用途
Config / LoadFile	config	struct / function	YAML 設定ファイルのパース・バリデーション
Manager (discovery)	discovery	struct	サービスディスカバリプロバイダの統合管理
Manager (scrape)	scrape	struct	スクレイプジョブ・ターゲットの管理
Engine / NewEngine	promql	struct / function	PromQL クエリエンジン
DB / Open	tsdb	struct / function	時系列データベースのオープン・管理
Manager (rules)	rules	struct	ルールグループのライフサイクル管理
Manager (notifier)	notifier	struct	Alertmanager へのアラート通知管理
Handler / New	web	struct / function	HTTP サーバー・ルーティング
Storage (fanout)	storage	struct	ファンアウトストレージ（primary + secondaries）
Manager (tracing)	tracing	struct	OpenTelemetry トレーシング管理
Labels / Matcher	model/labels	struct	ラベルセット・マッチャー
Parser	model/textparse	interface	メトリクスフォーマットパーサー
Histogram / FloatHistogram	model/histogram	struct	ネイティブヒストグラムデータ型
WriteRequest / ReadRequest	prompb	struct	Remote Write/Read プロトコルメッセージ

エンドポイント

メソッド	パス	説明
GET	/api/v1/query	インスタント PromQL クエリ
GET	/api/v1/query_range	レンジ PromQL クエリ
GET	/api/v1/series	時系列メタデータ検索
GET	/api/v1/labels	ラベル名一覧
GET	/api/v1/label/{name}/values	ラベル値一覧
GET	/api/v1/targets	スクレイプターゲット一覧
GET	/api/v1/rules	ルール・アラート一覧
GET	/api/v1/alerts	発火中アラート一覧
POST	/api/v1/write	Remote Write 受信
POST	/api/v1/read	Remote Read
GET	/federate	フェデレーションエンドポイント
POST	/-/reload	設定リロード
POST	/-/quit	グレースフルシャットダウン
GET	/metrics	Prometheus 自身のメトリクス

依存関係

外部依存（このモジュールが依存する外部パッケージ）

パッケージ	主要クラス	用途
github.com/prometheus/client_golang/prometheus	Registerer, Gauge, Counter, Summary, Histogram	Prometheus メトリクスライブラリ
github.com/prometheus/common/config	HTTPClientConfig, TLSConfig	HTTP クライアント・TLS 設定
github.com/prometheus/common/model	Duration, LabelSet, MetricType	共通データモデル
github.com/prometheus/common/promslog	Config, New	構造化ロガー
github.com/prometheus/common/version	Version, Revision	バージョン情報
github.com/prometheus/alertmanager/api/v2/models	PostableAlerts	Alertmanager API モデル
github.com/prometheus/exporter-toolkit/web	FetchConfig, Validate	Web サーバー TLS / Basic 認証
github.com/alecthomas/kingpin/v2	Application	CLI フラグ・サブコマンド
github.com/grafana/regexp	Regexp	RE2 互換正規表現
github.com/oklog/run	Group	goroutine ライフサイクル管理
github.com/gogo/protobuf/proto	Marshal, Unmarshal	protobuf ランタイム
github.com/cespare/xxhash/v2	Sum64	高速非暗号ハッシュ
go.uber.org/atomic	Int32, String	アトミック変数
go.uber.org/automaxprocs/maxprocs	Set	GOMAXPROCS 自動設定
go.opentelemetry.io/otel	Tracer	OpenTelemetry トレーシング
go.yaml.in/yaml/v2	UnmarshalStrict	YAML パース
k8s.io/client-go	—	Kubernetes SD クライアント
github.com/edsrzf/mmap-go	MMap	メモリマップドファイル
github.com/klauspost/compress	gzip, zstd	高速圧縮
golang.org/x/sync/semaphore	Weighted	セマフォ同期

外部依存（このモジュールが依存する内部モジュール）

ルートモジュールのため該当なし（配下の全サブモジュールがプロジェクト内の依存関係を構成）。

内部依存（このモジュールに依存するもの）

ルートモジュールのため該当なし。外部プロジェクトからは github.com/prometheus/prometheus の各パッケージが Go モジュールとしてインポートされる。

データフロー

Mermaid形式:

flowchart TD
    Target["ターゲット<br/>(HTTP エンドポイント)"] -->|HTTP GET /metrics| Scrape["scrape.Manager"]
    Scrape -->|パース| Parser["model/textparse.Parser"]
    Parser -->|Labels + Samples| Relabel["model/relabel<br/>リラベル + フィルタ"]
    Relabel --> Appender["storage.Appender"]
    Appender --> Head["tsdb.Head<br/>(WAL)"]
    Head -->|コンパクション| Block["tsdb.Block<br/>(ディスク)"]
    Head -->|Remote Write| Remote["storage/remote<br/>→ 外部ストレージ"]
    Block --> PQ["promql.Engine"]
    Head --> PQ
    PQ --> API["web/api/v1<br/>REST API"]
    API --> UI["React UI"]
    PQ --> Rules["rules.Manager"]
    Rules -->|RecordingRule| Appender
    Rules -->|AlertingRule| Notifier["notifier.Manager"]
    Notifier -->|HTTP POST| AM["Alertmanager"]

セキュリティ考慮

観点	対策状況	詳細
入力検証	集約	設定ファイル: `yaml.UnmarshalStrict` による厳密パース + 各フィールドバリデーション。メトリクス: テキストパーサーでの UTF-8 検証、NaN/Inf タイムスタンプ拒否。PromQL: パーサーでの構文・型検証
認証/認可	あり	`--web.config.file` による TLS / Basic 認証（exporter-toolkit 経由）。Kubernetes SD の ServiceAccount トークン認証。AWS SigV4 / Azure AD / Google IAM 認証
シークレット保護	あり	YAML マーシャル時にパスワード・トークンを `<secret>` にマスク。`credentials_file` / `password_file` による外部ファイル参照
リソース制限	あり	PromQL: `maxSamplesPerQuery`、クエリタイムアウト、同時実行制限。スクレイプ: サンプル数制限、ボディサイズ制限。TSDB: リテンションポリシー（時間/サイズ/ディスク使用率）
サプライチェーン	あり	CI で全 GitHub Actions をコミット SHA でピン留め。OpenSSF Scorecard による継続的評価。CodeQL / govulncheck による脆弱性スキャン
コンテナセキュリティ	あり	非 root 実行（`USER nobody`）。最小ベースイメージ（busybox / distroless）
ReDoS 対策	あり	`github.com/grafana/regexp`（RE2 互換）の使用、`FastRegexMatcher` による最適化
CORS	あり	`--web.cors.origin` フラグで正規表現によるオリジン制御

技術的負債・既知の問題

種別	内容	影響範囲	優先度
非推奨ライブラリ	`gogo/protobuf` が公式にアーカイブ済み（メンテナンス終了）。protobuf コード生成全体が依存	prompb, internal/tools	高
設計	`cmd/prometheus/main.go` の `main` 関数が約 1,250 行と非常に長大。Server / Agent モードの分岐が混在	cmd/prometheus	中
設計	`promql/engine.go` が約 4,875 行、`promql/functions.go` が約 2,800 行と巨大	promql	中
有効期限切れ	`SECURITY-INSIGHTS.yml` の `expiration-date` が 2025-07-30 で超過	SECURITY-INSIGHTS.yml	高
セキュリティ	`prombench.yml` の `curl` コマンド内でシェルインジェクションのリスク	.github/workflows	中
セキュリティ	`documentation/examples/remote_storage/influxdb` の Flux インジェクション可能性	documentation	高
非推奨	`documentation/examples/kubernetes-rabbitmq` が ReplicationController（非推奨）と古いイメージを使用	documentation	高
同期管理	Go バージョンが `.promu.yml`、`.github/workflows/ci.yml`、`go.mod` の 3 箇所に分散	ビルドシステム	中
設計	react-app が npm workspaces から分離（Mantine UI 移行中の暫定対応）	Makefile, web/ui	中
v1/v2 並存	Remote Write v1 / v2 プロトコルが並存。v2 への完全移行後に v1 を非推奨化する必要がある	prompb, storage/remote	中
設計	discovery の `reflect.DeepEqual` によるプロバイダ設定比較	discovery	低

拡張ポイント

変更内容	修正対象	手順・注意点
新しい SD プラグインの追加	plugins/plugin_\<name>.go, discovery/\<name>/	1. `discovery/<name>` パッケージに `Config` / `Discoverer` 実装を作成 2. `init()` で `discovery.RegisterConfig()` を呼び出し 3. `plugins/plugin_<name>.go` にビルドタグ付きブランクインポートを追加
新しい PromQL 関数の追加	promql/functions.go, promql/parser/functions.go	1. parser の `Functions` マップにメタデータ追加 2. functions.go に実装を追加 3. `FunctionCalls` マップにエントリ追加
新しい設定セクションの追加	config/config.go	1. `Config` 構造体にフィールド追加 2. デフォルト値定義 3. `UnmarshalYAML` 実装 4. `SetDirectory` にパス解決追加
新しいフィーチャーフラグの追加	cmd/prometheus/main.go	1. `setFeatureListOptions` の switch に case 追加 2. ヘルプテキスト更新 3. `docs/feature_flags.md` にドキュメント追加
新しいストレージバックエンド追加	storage/	`Storage` インターフェースを実装し、ファンアウトストレージの secondary として登録
新しいメトリクスパーサーの追加	model/textparse/	`Parser` インターフェースを実装し、`New()` ファクトリの switch に対応メディアタイプを追加
新しいリラベル Action の追加	model/relabel/	`Action` 定数追加、`relabel()` の switch にケース追加、`Validate()` にバリデーション追加（4 箇所全て修正必要）
新しいアラートルール型の追加	rules/	`Rule` インターフェースを実装し、`origin.go` の type switch と `manager.go` の `LoadGroups` にロジック追加

注意点・特記事項

設計上の制約: labels.StableHash のハッシュアルゴリズム（xxhash）・セパレータ・連結順序は TSDB シャーディングで使用されるため変更禁止。value.StaleNaN のビットパターンは TSDB 永続データとの後方互換性維持が必須。Discoverer / Config インターフェースの変更は 30 以上の SD プロバイダに波及する。Rule インターフェースへのメソッド追加は全実装体に同時更新が必要
パフォーマンス: labels パッケージは unsafe パッケージによるゼロコピー変換を意図的に使用しメモリ効率を最優先。PromQL エンジンは Object Pool によるメモリ再利用が性能の要。TSDB の stripeSeries によるシャード化ハッシュマップでロック競合を大幅削減。スクレイプの scrapeCache がシリーズ参照をキャッシュしスクレイプ間のオーバーヘッドを低減
互換性: Remote Write v1 の SAMPLES レスポンスタイプは非推奨（ストリーミング形式推奨）。PromQL の Vector / Matrix / Sample 等のコアデータ型は Web API レスポンス・ルール評価・テンプレート等で広く使用されフィールド変更は後方互換性に影響。labels の 3 つのビルドタグ実装（stringlabels / slicelabels / dedupelabels）は同一公開 API を提供し新メソッド追加時は 3 ファイル全てに実装が必要

配下ドキュメント

サブモジュール

.github.md - Prometheus プロジェクトの GitHub プラットフォーム統合設定を一元管理するモジュールである。
cmd.md - Prometheus プロジェクトが提供する 2 つの実行バイナリ（prometheus サーバーと promtool CLI ユーティリティ）のエントリーポイントを集約するモジュール。
compliance.md - Prometheus の Remote Write 送信機能が外部仕様に準拠しているかを検証するコンプライアンステストモジュール。
config.md - Prometheus の YAML 設定ファイルを Go の構造体にパース・バリデーションするための中核パッケージ。
discovery.md - Prometheus のサービスディスカバリ（SD）サブシステムの中核フレームワーク。
documentation.md - Prometheus プロジェクトのドキュメント資産、リファレンス実装、およびセルフモニタリング定義を統合的に管理するモジュール。
internal.md - internal は、Prometheus プロジェクトの内部専用ユーティリティを格納するトップレベルディレクトリである。
model.md - Prometheus のコアデータモデル層を構成する最上位モジュール。
notifier.md - Prometheus のアラート通知サブシステムを実装するモジュール。
plugins.md - Prometheus のサービスディスカバリ（SD）プラグインをビルド時に選択的に登録するためのモジュール。
prompb.md - Prometheus のリモートストレージ通信プロトコル（Remote Write / Remote Read）のデータ型定義・シリアライズ・コーデック変換を一元的に提供するモジュール。
promql.md - Prometheus の PromQL（Prometheus Query Language）クエリ実行エンジンの中核モジュール。
rules.md - Prometheus のルール評価エンジンのコア実装を提供するモジュール。
schema.md - Prometheus のメトリクススキーマメタデータ（メトリクス名・型・単位）をラベルとして統一的に管理するためのドメインモデルおよびユーティリティを提供するモジュール。
scrape.md - Prometheus のメトリクススクレイピングサブシステムの中核モジュール。
storage.md - Prometheus のストレージ層における中核的な抽象レイヤーを提供するモジュール。
template.md - Prometheus のアラートルール通知文面および Web コンソール画面で使用されるテンプレート展開エンジンを提供するモジュール。
tracing.md - Prometheus の分散トレーシング機能を一元管理するモジュール。
tsdb.md - Prometheus の時系列データベース（TSDB）の中核モジュールであり、float サンプル・ネイティブヒストグラム・Exemplar の永続的なストレージエンジンを実装する。
util.md - Prometheus プロジェクト全体で共有される横断的ユーティリティ機能を集約したトップレベルモジュール。
web.md - Prometheus サーバーの HTTP レイヤー全体を統括するモジュール。

ファイル

.golangci.yml.md - Prometheus プロジェクトにおける golangci-lint v2 の設定ファイル。
.promu.yml.md - Prometheus プロジェクトのビルドツール promu（Prometheus Utility Tool）の設定ファイル。
Dockerfile.md - Prometheus 監視システムのコンテナイメージを定義する Dockerfile。
Makefile.md - Prometheus プロジェクトのトップレベルビルド定義ファイル。
SECURITY-INSIGHTS.yml.md - Prometheus プロジェクトのセキュリティに関するメタデータを Security Insights specification (v1.0.0) に準拠して定義する YAML ファイル。
renovate.json.md - Prometheus リポジトリにおける Renovate Bot の設定ファイル。