效率与协作 · SKILL.md

setup-prometheus-monitoring

setup-prometheus-monitoring

【效率与协作】Prometheusを設定して時系列メトリクスを収集する。スクレイプ設定、サービスディスカバリ、記録ルール、マルチクラスタ展開のフェデレーションパターンを含む。マイクロサービスの集中メトリクス収集、アプリケーションとインフラのモニタリング基盤構築、SLO/SLI追跡の確立、レガシー監視システムからの移行などに使用する。

独立 GitHub 快照 · 自动分类 · 以原作者文档为准

Ppjt222 / agent-almanacMIT

技能说明

GitHub

name: setup-prometheus-monitoring description: > Prometheusを設定して時系列メトリクスを収集する。スクレイプ設定、サービスディスカバリ、記録ルール、マルチクラスタ展開のフェデレーションパターンを含む。マイクロサービスの集中メトリクス収集、アプリケーションとインフラのモニタリング基盤構築、SLO/SLI追跡の確立、レガシー監視システムからの移行などに使用する。 locale: ja source_locale: en source_commit: 6f65f316 fence_basis_commit: 6f65f316 translator: claude-opus-4-6 translation_date: 2026-03-16 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: observability complexity: intermediate language: multi tags: prometheus, monitoring, metrics, scrape, recording-rules

Setup Prometheus Monitoring

スクレイプターゲット、記録ルール、フェデレーションを備えた本番対応Prometheusデプロイメントを設定する。

使用タイミング

マイクロサービスや分散システムの集中メトリクス収集を設定する場合
アプリケーションとインフラのメトリクスに対する時系列モニタリングを実装する場合
SLO/SLI追跡とアラートの基盤を確立する場合
フェデレーション経由で複数のPrometheusインスタンスからメトリクスを統合する場合
レガシー監視ソリューションからモダンなオブザーバビリティスタックへ移行する場合

入力

必須: スクレイプターゲットのリスト（サービス、エクスポーター、エンドポイント）
必須: 保持期間とストレージ要件
任意: 既存のサービスディスカバリ機構（Kubernetes、Consul、EC2）
任意: 事前集計メトリクスの記録ルール
任意: マルチクラスタ構成のフェデレーション階層

手順

ステップ1: Prometheusのインストールと設定

グローバル設定とスクレイプインターバルを含むベースのPrometheus設定を作成する。

# Create Prometheus directory structure
mkdir -p /etc/prometheus/{rules,file_sd}
mkdir -p /var/lib/prometheus

# Download Prometheus (adjust version as needed)
cd /tmp
wget https://github.com/prometheus/prometheus/releases/download/v2.48.0/prometheus-2.48.0.linux-amd64.tar.gz
tar xvf prometheus-2.48.0.linux-amd64.tar.gz
sudo cp prometheus-2.48.0.linux-amd64/{prometheus,promtool} /usr/local/bin/

/etc/prometheus/prometheus.yml を作成する:

global:
  scrape_interval: 15s
  scrape_timeout: 10s
  evaluation_interval: 15s
  external_labels:
    cluster: 'production'
    region: 'us-east-1'

# Alertmanager configuration
alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - localhost:9093

# Load recording and alerting rules
rule_files:
  - "rules/*.yml"

# Scrape configurations
scrape_configs:
  # Prometheus self-monitoring
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']
        labels:
          env: 'production'

  # Node exporter for host metrics
  - job_name: 'node'
    static_configs:
      - targets:
          - 'node1:9100'
          - 'node2:9100'
        labels:
          env: 'production'

  # Application metrics with file-based service discovery
  - job_name: 'app-services'
    file_sd_configs:
      - files:
          - '/etc/prometheus/file_sd/services.json'
        refresh_interval: 30s
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance
      - source_labels: [env]
        target_label: environment

期待結果： PrometheusがWebUI（http://localhost:9090）でアクセス可能となり、ターゲットがStatus > Targetsに一覧表示される。

失敗時：

promtool check config /etc/prometheus/prometheus.yml で構文を確認する
ファイルパーミッションを確認: sudo chown -R prometheus:prometheus /etc/prometheus /var/lib/prometheus
ログを確認: journalctl -u prometheus -f

ステップ2: サービスディスカバリの設定

手動でターゲットを管理しなくて済むよう、動的なターゲットディスカバリを設定する。

Kubernetes環境の場合、scrape_configsに追加する:

  - job_name: 'kubernetes-pods'
    kubernetes_sd_configs:
      - role: pod
    relabel_configs:
      # Only scrape pods with prometheus.io/scrape annotation
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
        action: keep
        regex: true
      # Use custom port if specified
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_port]
        action: replace
        target_label: __address__
        regex: ([^:]+)(?::\d+)?;(\d+)
        replacement: $1:$2
      # Add namespace as label
      - source_labels: [__meta_kubernetes_namespace]
        target_label: kubernetes_namespace
      # Add pod name as label
      - source_labels: [__meta_kubernetes_pod_name]
        target_label: kubernetes_pod_name

ファイルベースのサービスディスカバリの場合、/etc/prometheus/file_sd/services.jsonを作成:

[
  {
    "targets": ["web-app-1:8080", "web-app-2:8080"],
    "labels": {
      "job": "web-app",
      "env": "production",
      "team": "platform"
    }
  },
  {
    "targets": ["api-service-1:9090", "api-service-2:9090"],
    "labels": {
      "job": "api-service",
      "env": "production",
      "team": "backend"
    }
  }
]

Consulサービスディスカバリの場合:

  - job_name: 'consul-services'
    consul_sd_configs:
      - server: 'consul.example.com:8500'
        services: []  # Empty list means discover all services
    relabel_configs:
      - source_labels: [__meta_consul_service]
        target_label: job
      - source_labels: [__meta_consul_tags]
        regex: '.*,monitoring,.*'
        action: keep

期待結果： PrometheusのUIに動的ターゲットが表示され、サービスのスケールや変更に合わせて自動更新される。

失敗時：

Kubernetes: kubectl auth can-i list pods --as=system:serviceaccount:monitoring:prometheus でRBACパーミッションを確認する
ファイルSD: python -m json.tool /etc/prometheus/file_sd/services.json でJSON構文を検証する
Consul: curl http://consul.example.com:8500/v1/catalog/services で接続性をテストする

ステップ3: 記録ルールの作成

ダッシュボードのパフォーマンスとアラート効率のために、高コストなクエリを事前集計する。

/etc/prometheus/rules/recording_rules.yml を作成する:

groups:
  - name: api_aggregations
    interval: 30s
    rules:
      # Calculate request rate per endpoint (5m window)
      - record: job:http_requests:rate5m
        expr: |
          sum by (job, endpoint, method) (
            rate(http_requests_total[5m])
          )

      # Calculate error rate percentage
      - record: job:http_errors:rate5m
        expr: |
          sum by (job) (
            rate(http_requests_total{status=~"5.."}[5m])
          ) / sum by (job) (
            rate(http_requests_total[5m])
          ) * 100

      # P95 latency by endpoint
      - record: job:http_request_duration_seconds:p95
        expr: |
          histogram_quantile(0.95,
            sum by (job, endpoint, le) (
              rate(http_request_duration_seconds_bucket[5m])
            )
          )

  - name: resource_aggregations
    interval: 1m
    rules:
      # CPU usage by instance
      - record: instance:cpu_usage:ratio
        expr: |
          1 - avg by (instance) (
            rate(node_cpu_seconds_total{mode="idle"}[5m])
          )

      # Memory usage percentage
      - record: instance:memory_usage:ratio
        expr: |
          1 - (
            node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes
          )

      # Disk usage by mount point
      - record: instance:disk_usage:ratio
        expr: |
          1 - (
            node_filesystem_avail_bytes{fstype!~"tmpfs|fuse.*"}
            / node_filesystem_size_bytes{fstype!~"tmpfs|fuse.*"}
          )

検証とリロード:

# Validate rules syntax
promtool check rules /etc/prometheus/rules/recording_rules.yml

# Reload Prometheus configuration (without restart)
curl -X POST http://localhost:9090/-/reload

# Or send SIGHUP signal
sudo killall -HUP prometheus

期待結果： 記録ルールが正常に評価され、job:プレフィックスの新しいメトリクスがPrometheusに表示され、ダッシュボードのクエリパフォーマンスが向上する。

失敗時：

promtool check rules でルール構文を確認する
評価インターバルがデータの可用性と一致しているか確認する
欠落しているソースメトリクスを確認: curl http://localhost:9090/api/v1/targets
評価エラーのログを確認: journalctl -u prometheus | grep -i error

ステップ4: ストレージと保持期間の設定

保持要件とクエリパフォーマンスのためにストレージを最適化する。

/etc/systemd/system/prometheus.service を編集する:

[Unit]
Description=Prometheus Monitoring System
Documentation=https://prometheus.io/docs/introduction/overview/
After=network-online.target

[Service]
Type=simple
User=prometheus
Group=prometheus
ExecStart=/usr/local/bin/prometheus \
  --config.file=/etc/prometheus/prometheus.yml \
  --storage.tsdb.path=/var/lib/prometheus \
  --storage.tsdb.retention.time=30d \
  --storage.tsdb.retention.size=50GB \
  --web.console.templates=/etc/prometheus/consoles \
  --web.console.libraries=/etc/prometheus/console_libraries \
  --web.listen-address=:9090 \
  --web.enable-lifecycle \
  --web.enable-admin-api

Restart=always
RestartSec=10s

[Install]
WantedBy=multi-user.target

主なストレージフラグ:

--storage.tsdb.retention.time=30d: データを30日間保持
--storage.tsdb.retention.size=50GB: ストレージを50GBに制限（先に達した方の制限が適用）
--storage.tsdb.wal-compression: WAL圧縮を有効化（ディスクI/Oを削減）
--web.enable-lifecycle: HTTP POSTによる設定リロードを許可
--web.enable-admin-api: スナップショットと削除APIを有効化

有効化して起動:

sudo systemctl daemon-reload
sudo systemctl enable prometheus
sudo systemctl start prometheus
sudo systemctl status prometheus

期待結果： Prometheusがポリシーに従ってメトリクスを保持し、ディスク使用量が制限内に収まり、古いデータが自動的に削除される。

失敗時：

ディスク使用量を監視: du -sh /var/lib/prometheus
TSDBの統計を確認: curl http://localhost:9090/api/v1/status/tsdb
保持設定を確認: curl http://localhost:9090/api/v1/status/runtimeinfo | jq .data.storageRetention
強制クリーンアップ: curl -X POST http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]={__name__=~".+"}

ステップ5: フェデレーションの設定（マルチクラスタ）

クラスタ間でメトリクスを集計するための階層型Prometheusを設定する。

エッジPrometheusインスタンス（各クラスタ内）で外部ラベルが設定されていることを確認:

global:
  external_labels:
    cluster: 'production-east'
    datacenter: 'us-east-1'

中央Prometheusインスタンスにフェデレーションスクレイプ設定を追加:

scrape_configs:
  - job_name: 'federate-production'
    honor_labels: true
    metrics_path: '/federate'
    params:
      'match[]':
        # Aggregate only pre-computed recording rules
        - '{__name__=~"job:.*"}'
        # Include alert states
        - '{__name__=~"ALERTS.*"}'
        # Include critical infrastructure metrics
        - 'up{job=~".*"}'
    static_configs:
      - targets:
          - 'prometheus-east.example.com:9090'
          - 'prometheus-west.example.com:9090'
        labels:
          env: 'production'
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance
      - source_labels: [__address__]
        regex: 'prometheus-(.*).example.com.*'
        target_label: cluster
        replacement: '$1'

フェデレーションのベストプラクティス:

honor_labels: true を使用して元のラベルを保持する
記録ルールと集計のみをフェデレートする（生のメトリクスではなく）
適切なスクレイプインターバルを設定する（エッジPrometheusの評価より長く）
match[] を使用してメトリクスをフィルタリングする（すべてをフェデレートしない）

期待結果： 中央Prometheusが全クラスタのフェデレートされたメトリクスを表示し、クエリが複数のリージョンにまたがり、データの重複が最小化される。

失敗時：

フェデレーションエンドポイントのアクセシビリティを確認: curl http://prometheus-east.example.com:9090/federate?match[]={__name__=~"job:.*"} | head -20
ラベルの競合を確認（中央 vs エッジの外部ラベル）
フェデレーションの遅延を監視: タイムスタンプの差異を比較
マッチパターンを確認: curl http://localhost:9090/api/v1/label/__name__/values | jq .data | grep "job:"

ステップ6: 高可用性の実装（任意）

フェイルオーバーのために同一設定の冗長Prometheusインスタンスをデプロイする。

ThanosまたはCortexを使用した真のHA、または単純な負荷分散構成:

# prometheus-1.yml and prometheus-2.yml (identical configs)
global:
  scrape_interval: 15s
  external_labels:
    prometheus: 'prometheus-1'  # Different per instance
    replica: 'A'

# Use --web.external-url flag for each instance
# prometheus-1: --web.external-url=http://prometheus-1.example.com:9090
# prometheus-2: --web.external-url=http://prometheus-2.example.com:9090

Grafanaを設定して両方のインスタンスにクエリする:

{
  "name": "Prometheus-HA",
  "type": "prometheus",
  "url": "http://prometheus-lb.example.com",
  "jsonData": {
    "httpMethod": "POST",
    "timeInterval": "15s"
  }
}

HAProxyまたはnginxで負荷分散する:

upstream prometheus_backend {
    server prometheus-1.example.com:9090 max_fails=3 fail_timeout=30s;
    server prometheus-2.example.com:9090 max_fails=3 fail_timeout=30s;
}

server {
    listen 9090;
    location / {
        proxy_pass http://prometheus_backend;
        proxy_set_header Host $host;
    }
}

期待結果： クエリリクエストがインスタンス間で分散され、1つのインスタンスがダウンしても自動フェイルオーバーし、単一インスタンスの障害時にデータ損失が発生しない。

失敗時：

両インスタンスが同じターゲットをスクレイプしていることを確認する（わずかな時刻のずれは許容可能）
インスタンス間の設定のずれを確認する
クエリでの重複排除を監視する（Grafanaが重複シリーズを表示）
ロードバランサーのヘルスチェックを確認する

バリデーション

よくある落とし穴

高カーディナリティなメトリクス: 無制限の値（ユーザーID、タイムスタンプ、UUID）を持つラベルを避ける。ストレージ前に記録ルールを使用して集計する。
スクレイプインターバルの不一致: 記録ルールはスクレイプインターバル以上の間隔で評価する必要があり、ギャップを避けるため。
フェデレーションの過負荷: すべてのメトリクスをフェデレートすると大量のデータ重複が発生する。集計された記録ルールのみをフェデレートする。
リラベル設定の欠如: 適切なリラベルがないと、サービスディスカバリが混乱したラベルや重複ラベルを作成する可能性がある。
保持期間が短すぎる: 最長のダッシュボード時間ウィンドウより長い保持期間を設定し、「データなし」のギャップを避ける。
リソース制限なし: 高カーディナリティなメトリクスはPrometheusの過剰なメモリ消費につながる可能性がある。--storage.tsdb.max-block-durationを設定し、ヒープ使用量を監視する。
ライフサイクルエンドポイントの無効化: --web.enable-lifecycleがないと、設定のリロードは完全な再起動が必要となり、スクレイプのギャップが生じる。

安装技能

TERMINAL

npx skills add pjt222/agent-almanac --skill setup-prometheus-monitoring

复制命令到本地终端执行；安装前请先审查源代码和许可证。

ZIP · 完整技能目录，含资源与许可证

SKILL.md · 仅技能说明原文

仓库 Star: 未同步
许可证: MIT
版本 / 分支: HEAD · 57c07e1d
仓库更新时间: 未同步

安装前，请检查技能脚本与权限。

源代码

setup-prometheus-monitoring

技能说明

Setup Prometheus Monitoring

使用タイミング

入力

手順

ステップ1: Prometheusのインストールと設定

ステップ2: サービスディスカバリの設定

ステップ3: 記録ルールの作成

ステップ4: ストレージと保持期間の設定

ステップ5: フェデレーションの設定（マルチクラスタ）

ステップ6: 高可用性の実装（任意）

バリデーション

よくある落とし穴

関連スキル

发现更多相关技能

计划执行与检查节点

女娲：花叔原版

仓颉：方法论版 v2.5.0