📊 Prometheus 완전 가이드

services:
  prometheus:
    image: prom/prometheus:latest
    ports: ["9090:9090"]
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - ./alert_rules.yml:/etc/prometheus/alert_rules.yml
      - promdata:/prometheus
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --web.enable-lifecycle          # curl -X POST 로 재시작 없이 설정 리로드

  grafana:
    image: grafana/grafana:latest
    ports: ["3000:3000"]
    environment:
      GF_SECURITY_ADMIN_PASSWORD: admin
    volumes:
      - grafdata:/var/lib/grafana
      - ./grafana/provisioning:/etc/grafana/provisioning   # 데이터소스·대시보드 as Code

  alertmanager:
    image: prom/alertmanager:latest
    ports: ["9093:9093"]
    volumes:
      - ./alertmanager.yml:/etc/alertmanager/alertmanager.yml

  node-exporter:
    image: prom/node-exporter:latest
    ports: ["9100:9100"]

volumes:
  promdata:
  grafdata:

global:
  scrape_interval: 15s        # 기본 수집 주기
  evaluation_interval: 15s    # 레코딩/알림 규칙 평가 주기

rule_files:
  - "alert_rules.yml"         # 레코딩 규칙 + 알림 규칙

alerting:
  alertmanagers:
    - static_configs:
        - targets: ["alertmanager:9093"]

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ["localhost:9090"]

  - job_name: node
    static_configs:
      - targets: ["node-exporter:9100"]

  - job_name: myapp
    metrics_path: /metrics
    static_configs:
      - targets: ["myapp:8080"]
        labels: { env: production, team: backend }

from prometheus_client import Counter, Histogram, start_http_server
import time

# Counter — 누적 증가만 하는 값 (요청 수, 에러 수)
REQUEST_COUNT = Counter(
    "http_requests_total", "Total HTTP requests",
    ["method", "endpoint", "status"]
)

# Histogram — 분포 측정 (응답시간 p50/p95/p99 계산용 버킷)
REQUEST_LATENCY = Histogram(
    "http_request_duration_seconds", "Request latency",
    ["endpoint"], buckets=[0.05, 0.1, 0.3, 0.5, 1, 2, 5]
)

def handle_request(endpoint: str):
    start = time.time()
    try:
        ...  # 실제 처리 로직
        REQUEST_COUNT.labels("GET", endpoint, "200").inc()
    finally:
        REQUEST_LATENCY.labels(endpoint).observe(time.time() - start)

start_http_server(8080)   # /metrics 엔드포인트 자동 노출

# blackbox_exporter — 외부 관점에서 엔드포인트 가용성을 확인 (synthetic monitoring)
# blackbox.yml — exporter 자체 설정
modules:
  http_2xx:
    prober: http
    timeout: 5s
    http:
      valid_status_codes: [200]
      method: GET

---
# prometheus.yml에 추가할 scrape job — 실제 타깃은 params.target으로 전달
scrape_configs:
  - job_name: blackbox
    metrics_path: /probe
    params:
      module: [http_2xx]
    static_configs:
      - targets:
          - https://api.example.com/health
          - https://example.com
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox-exporter:9115   # 실제 프로브를 수행하는 exporter 주소로 리라우팅

management:
  endpoints:
    web:
      exposure:
        include: health, prometheus, metrics   # 필요한 엔드포인트만 명시적으로 노출
  endpoint:
    health:
      probes:
        enabled: true   # /actuator/health/liveness, /actuator/health/readiness를 K8s용으로 분리
  prometheus:
    metrics:
      export:
        enabled: true    # micrometer 메트릭을 Prometheus 형식(/actuator/prometheus)으로 노출

spec:
  containers:
  - name: myapp
    livenessProbe:
      httpGet: { path: /actuator/health/liveness, port: 8080 }
      periodSeconds: 10
    readinessProbe:
      httpGet: { path: /actuator/health/readiness, port: 8080 }
      periodSeconds: 5
---
# prometheus.yml (또는 ServiceMonitor)는 /actuator/prometheus를 별도로 scrape
scrape_configs:
  - job_name: myapp
    metrics_path: /actuator/prometheus
    static_configs:
      - targets: ["myapp:8080"]

groups:
  - name: myapp.recording-rules
    interval: 30s
    rules:
      # 자주 조회하는 무거운 쿼리를 미리 계산해 job:metric:operation 이름 규칙으로 저장
      - record: job:http_requests:rate5m
        expr: sum by (job) (rate(http_requests_total[5m]))

      - record: job:http_errors:ratio5m
        expr: |
          sum by (job) (rate(http_requests_total{status=~"5.."}[5m]))
          / sum by (job) (rate(http_requests_total[5m]))

      - record: job:http_request_duration:p95_5m
        expr: histogram_quantile(0.95, sum by (job, le) (rate(http_request_duration_seconds_bucket[5m])))

apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    jsonData:
      timeInterval: 15s          # global.scrape_interval과 맞춰두면 그래프가 자연스러움
      httpMethod: POST

apiVersion: 1
providers:
  - name: default
    folder: "Services"
    type: file
    updateIntervalSeconds: 30   # 파일 변경을 주기적으로 감지해 자동 리로드
    options:
      path: /etc/grafana/provisioning/dashboards/files
      foldersFromFilesStructure: true

{
  "title": "MyApp - RED Metrics",
  "templating": {
    "list": [
      { "name": "job", "type": "query", "query": "label_values(http_requests_total, job)" }
    ]
  },
  "panels": [
    {
      "title": "Request Rate",
      "type": "timeseries",
      "targets": [
        { "expr": "sum(rate(http_requests_total{job=\"$job\"}[5m]))", "legendFormat": "req/s" }
      ]
    },
    {
      "title": "Error Ratio",
      "type": "timeseries",
      "targets": [
        { "expr": "job:http_errors:ratio5m{job=\"$job\"}", "legendFormat": "error %" }
      ],
      "fieldConfig": { "defaults": { "unit": "percentunit", "thresholds": { "steps": [
        { "color": "green", "value": 0 }, { "color": "red", "value": 0.05 }
      ]}}}
    },
    {
      "title": "P95 Duration",
      "type": "timeseries",
      "targets": [
        { "expr": "job:http_request_duration:p95_5m{job=\"$job\"}", "legendFormat": "p95" }
      ]
    }
  ]
}

# 클러스터가 여러 개면, 각 Prometheus가 자기 자신을 어느 클러스터인지 스스로 표시해야
# 나중에 Grafana나 중앙 저장소에서 클러스터별로 구분·필터링할 수 있습니다.
global:
  external_labels:
    cluster: prod-seoul       # 클러스터마다 고유한 이름 (prod-seoul, prod-tokyo, staging ...)
    region: ap-northeast-2

# 방식 A — 클러스터별로 Prometheus 데이터소스를 따로 등록
# 대시보드 상단의 데이터소스 드롭다운으로 클러스터를 전환하는 구조
apiVersion: 1
datasources:
  - name: Prometheus-Seoul
    uid: prom-seoul
    type: prometheus
    access: proxy
    url: http://prometheus-seoul.monitoring.svc:9090
    jsonData: { timeInterval: 15s }

  - name: Prometheus-Tokyo
    uid: prom-tokyo
    type: prometheus
    access: proxy
    url: http://prometheus-tokyo.monitoring.svc:9090
    jsonData: { timeInterval: 15s }

{
  "templating": {
    "list": [
      {
        "name": "datasource",
        "type": "datasource",
        "query": "prometheus",
        "current": { "text": "Prometheus-Seoul", "value": "prom-seoul" }
      },
      {
        "name": "cluster",
        "type": "query",
        "datasource": "${datasource}",
        "query": "label_values(up, cluster)",
        "refresh": 2
      }
    ]
  },
  "panels": [
    {
      "title": "Cluster Node Count",
      "type": "stat",
      "datasource": "${datasource}",
      "targets": [
        { "expr": "count(up{job=\"node\", cluster=\"$cluster\"} == 1)" }
      ]
    }
  ]
}

# kube-prometheus-stack — grafana.com의 검증된 클러스터 대시보드를 gnetId로 자동 로드
# (Kubernetes 통합 섹션의 helm install -f values.yaml 에 추가)
grafana:
  dashboardProviders:
    dashboardproviders.yaml:
      apiVersion: 1
      providers:
        - name: community
          orgId: 1
          folder: "Community"
          type: file
          options:
            path: /var/lib/grafana/dashboards/community
  dashboards:
    community:
      k8s-cluster-monitoring:
        gnetId: 315            # Kubernetes cluster monitoring (via Prometheus) — 클러스터 전체 개요
        revision: 3
        datasource: Prometheus
      node-exporter-full:
        gnetId: 1860           # Node Exporter Full — 노드별 CPU/메모리/디스크/네트워크 상세
        revision: 37
        datasource: Prometheus
      # revision은 grafana.com/grafana/dashboards/<gnetId> 페이지에서 최신 값 확인 후 갱신

groups:
  - name: myapp.alerts
    rules:
      - alert: HighErrorRate
        expr: job:http_errors:ratio5m > 0.05
        for: 5m                          # 5분 이상 지속돼야 발화 — 순간 스파이크로 인한 오탐 방지
        labels:
          severity: critical
        annotations:
          summary: "{{ $labels.job }} 에러율 {{ $value | humanizePercentage }}"
          runbook_url: "https://wiki.internal/runbooks/high-error-rate"

      - alert: HighMemoryUsage
        expr: (node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes > 0.9
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "{{ $labels.instance }} 메모리 사용률 90% 초과"

      - alert: PodCrashLooping
        expr: increase(kube_pod_container_status_restarts_total[15m]) > 3
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "{{ $labels.namespace }}/{{ $labels.pod }} 반복 재시작 중"

route:
  receiver: default-webhook
  group_by: [alertname, job]
  group_wait: 30s           # 그룹 생성 후 30초 동안 관련 알림을 더 모아서 발송
  group_interval: 5m        # 같은 그룹에 새 알림이 추가됐을 때 재발송 최소 간격
  repeat_interval: 4h       # 미해결 알림 재발송 주기
  routes:
    - matchers: ["severity = critical"]
      receiver: slack-critical
      continue: false
    - matchers: ["severity = warning"]
      receiver: slack-warning

inhibit_rules:
  # critical 알림이 켜져 있으면 같은 job의 warning 알림은 노이즈이므로 억제
  - source_matchers: ["severity = critical"]
    target_matchers: ["severity = warning"]
    equal: [job]

receivers:
  - name: default-webhook
    webhook_configs:
      - url: http://ops-bot:9000/alert

  - name: slack-critical
    slack_configs:
      - api_url: "${SLACK_WEBHOOK_URL}"
        channel: "#alerts-critical"
        title: "{{ .CommonAnnotations.summary }}"
        send_resolved: true

  - name: slack-warning
    slack_configs:
      - api_url: "${SLACK_WEBHOOK_URL}"
        channel: "#alerts-warning"
        send_resolved: true

# 개념 이해를 위한 최소 예시 — "Website"라는 가상의 리소스 종류를 새로 등록
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: websites.example.com          # <복수형>.<group>
spec:
  group: example.com
  scope: Namespaced
  names:
    plural: websites
    singular: website
    kind: Website                     # 이제부터 kubectl get website 가 가능해짐
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:               # CR이 반드시 지켜야 할 필드 구조 (spec.url은 string 필수)
          type: object
          properties:
            spec:
              type: object
              required: ["url"]
              properties:
                url:
                  type: string
---
# 위 CRD를 apply한 뒤에는 아래처럼 CR 인스턴스를 만들 수 있음
apiVersion: example.com/v1
kind: Website
metadata:
  name: aidevops
spec:
  url: https://www.aidevops.kr
# 주의: 이 CR을 apply해도 실제로 웹사이트를 배포/점검하는 동작은 없음.
# 그 동작을 수행하려면 Website CR을 watch하는 Controller를 별도로 만들어 배포해야 함
# (kube-prometheus-stack에서는 이 Controller 역할을 Prometheus Operator가 대신 해줌)

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kube-prometheus-stack
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://prometheus-community.github.io/helm-charts
    chart: kube-prometheus-stack
    targetRevision: 65.5.1        # 버전을 반드시 고정 — Chart.yaml appVersion과 별개로 관리됨
    helm:
      valueFiles: ["values-production.yaml"]   # 같은 Git 저장소의 values 파일 참조
  destination:
    server: https://kubernetes.default.svc
    namespace: monitoring
  syncPolicy:
    automated: { prune: true, selfHeal: true }
    syncOptions: ["CreateNamespace=true"]

prometheus:
  prometheusSpec:
    retention: 30d                        # 로컬 TSDB 보관 기간
    retentionSize: "45GB"                 # 볼륨 대비 여유를 두고 용량 상한도 함께 설정
    resources:
      requests: { cpu: 500m, memory: 2Gi }
      limits:   { memory: 4Gi }           # CPU limit은 스로틀링 유발 — 보통 미설정 권장
    storageSpec:
      volumeClaimTemplate:
        spec:
          storageClassName: fast-ssd
          resources: { requests: { storage: 50Gi } }
    # false로 설정하면 release 라벨과 무관하게 클러스터 전체 ServiceMonitor/PodMonitor/Probe/Rule을 인식
    serviceMonitorSelectorNilUsesHelmValues: false
    podMonitorSelectorNilUsesHelmValues: false
    probeSelectorNilUsesHelmValues: false
    ruleSelectorNilUsesHelmValues: false
    additionalScrapeConfigs: []           # ServiceMonitor로 커버 안 되는 정적 타깃 추가 시 사용
    # remoteWrite:                        # 장기 보관이 필요하면 Thanos/Mimir/Grafana Cloud 등으로 원격 저장
    #   - url: https://mimir.example.com/api/v1/push

# 관리형 K8s(EKS/GKE/AKS)는 컨트롤 플레인 메트릭에 접근 불가 — 기본 Off 권장 (Pending Target 방지)
kubeControllerManager: { enabled: false }
kubeScheduler:         { enabled: false }
kubeEtcd:               { enabled: false }
kubeProxy:               { enabled: false }

alertmanager:
  alertmanagerSpec:
    resources:
      requests: { cpu: 100m, memory: 256Mi }
    storage:
      volumeClaimTemplate:
        spec:
          resources: { requests: { storage: 5Gi } }

grafana:
  admin:
    existingSecret: grafana-admin-credentials   # 평문 비밀번호 대신 별도 Secret 참조 권장
  persistence: { enabled: true, size: 10Gi }
  sidecar:
    dashboards: { enabled: true, label: grafana_dashboard }   # ConfigMap 라벨 기반 대시보드 자동 로드
    datasources: { enabled: true }
  ingress:
    enabled: true
    ingressClassName: nginx
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-prod
    hosts: ["grafana.aidevops.kr"]
    tls:
      - secretName: grafana-tls
        hosts: ["grafana.aidevops.kr"]

defaultRules:
  rules:
    etcd: false          # 컨트롤 플레인 규칙도 관리형 K8s에서는 대부분 비활성화 대상
    kubeScheduler: false

# Operator가 이 리소스를 보고 자동으로 myapp을 scrape 대상에 추가
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: myapp
  namespace: production
  labels:
    release: kube-prom          # serviceMonitorSelectorNilUsesHelmValues: true일 때만 필요
spec:
  selector:
    matchLabels:
      app: myapp                # 대상 Service의 라벨
  endpoints:
    - port: metrics              # 대상 Service의 포트 이름
      path: /metrics
      interval: 15s

# 안정적인 Service 없이 Pod를 직접 스크랩 (예: Job/배치성 워크로드, 사이드카 메트릭)
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: myapp-batch
  namespace: production
spec:
  selector:
    matchLabels:
      app: myapp-batch
  podMetricsEndpoints:
    - port: metrics
      path: /metrics
      interval: 30s

# 외부/내부 엔드포인트 가용성 원격 점검 — blackbox-exporter 별도 설치 필요
# helm install blackbox-exporter prometheus-community/prometheus-blackbox-exporter -n monitoring
apiVersion: monitoring.coreos.com/v1
kind: Probe
metadata:
  name: aidevops-uptime
  namespace: monitoring
  labels:
    release: kube-prom
spec:
  jobName: blackbox-http
  interval: 30s
  module: http_2xx
  prober:
    url: blackbox-exporter-prometheus-blackbox-exporter.monitoring.svc:19115
  targets:
    staticConfig:
      static:
        - https://www.aidevops.kr
        - https://www.aidevops.kr/learn/prometheus/

# alert_rules.yml을 수동 마운트하는 대신 CRD로 선언 — GitOps로 관리 가능
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: myapp-alerts
  namespace: production
  labels:
    release: kube-prom
spec:
  groups:
    - name: myapp.recording
      rules:
        - record: job:http_errors:ratio5m
          expr: sum(rate(http_requests_total{status=~"5.."}[5m])) by (job) / sum(rate(http_requests_total[5m])) by (job)
    - name: myapp.alerts
      rules:
        - alert: HighErrorRate
          expr: job:http_errors:ratio5m{namespace="production"} > 0.05
          for: 5m
          labels: { severity: critical }
          annotations:
            summary: "{{ $labels.job }} 에러율 5% 초과"
        - alert: ProbeFailing
          expr: probe_success{job="blackbox-http"} == 0
          for: 5m
          labels: { severity: critical }
          annotations:
            summary: "{{ $labels.instance }} 헬스체크 실패"

# grafana_dashboard 라벨을 붙이면 sidecar가 클러스터 전체 네임스페이스에서 자동 감지해 로드
apiVersion: v1
kind: ConfigMap
metadata:
  name: myapp-dashboard
  namespace: monitoring
  labels:
    grafana_dashboard: "1"
data:
  myapp-red-metrics.json: |
    { "title": "MyApp - RED Metrics", "panels": [] }