monitoring-observability

モニタリングとオブザーバビリティ

コアワークフロー：オブザーバビリティの実装

この判断ツリーを使って、開始点を決定してください。

Are you setting up monitoring from scratch?
├─ YES → Start with "1. Design Metrics Strategy"
└─ NO → Do you have an existing issue?
    ├─ YES → Go to "9. Troubleshooting & Analysis"
    └─ NO → Are you improving existing monitoring?
        ├─ Alerts → Go to "3. Alert Design"
        ├─ Dashboards → Go to "4. Dashboard & Visualization"
        ├─ SLOs → Go to "5. SLO & Error Budgets"
        ├─ Tool selection → Read references/tool_comparison.md
        └─ Using Datadog? High costs? → Go to "7. Datadog Cost Optimization & Migration"

---

1. メトリクス戦略の設計

4つのゴールデンシグナルから始める

すべてのサービスで監視すべき項目：レイテンシ（p50/p95/p99）、トラフィック（req/s）、エラー（失敗率）、飽和度（リソース使用率）。

RED メソッド（リクエスト駆動）：レート、エラー、継続時間 | USE メソッド（インフラストラクチャ）：使用率、飽和度、エラー

クイックスタート - ウェブアプリケーションの例：

# Rate (requests/sec)
sum(rate(http_requests_total[5m]))

# Errors (error rate %)
sum(rate(http_requests_total{status=~"5.."}[5m]))
  /
sum(rate(http_requests_total[5m])) * 100

# Duration (p95 latency)
histogram_quantile(0.95,
  sum(rate(http_request_duration_seconds_bucket[5m])) by (le)
)

詳しくはこちら：references/metrics_design.md — メトリクスの種類、カーディナリティ、命名規則、ダッシュボード設計

メトリクスを直接クエリする

CLI/curl を使って Prometheus と CloudWatch のメトリクスをクエリします。

# Query Prometheus instant value
curl -s 'http://localhost:9090/api/v1/query?query=rate(http_requests_total[5m])' | jq .

# Query Prometheus over a time range (last 1h, 15s step)
curl -s 'http://localhost:9090/api/v1/query_range?query=rate(http_requests_total[5m])&start='$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ)'&end='$(date -u +%Y-%m-%dT%H:%M:%SZ)'&step=15s' | jq .

# Query CloudWatch metrics (e.g., EC2 CPU over last 1 hour)
aws cloudwatch get-metric-statistics \
  --namespace AWS/EC2 \
  --metric-name CPUUtilization \
  --dimensions Name=InstanceId,Value=i-1234567890abcdef0 \
  --start-time $(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ) \
  --end-time $(date -u +%Y-%m-%dT%H:%M:%SZ) \
  --period 300 \
  --statistics Average Maximum

---

2. ログの集約と分析

構造化ログのチェックリスト

すべてのログエントリには、タイムスタンプ（ISO 8601）、ログレベル、メッセージ、サービス名、リクエスト ID（トレース用）を含めます。

構造化ログの例（JSON）：

{
  "timestamp": "2024-10-28T14:32:15Z",
  "level": "error",
  "message": "Payment processing failed",
  "service": "payment-service",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user123",
  "order_id": "ORD-456",
  "error_type": "GatewayTimeout",
  "duration_ms": 5000
}

ログ分析

ログを分析して、エラー、パターン、異常を特定します。

# Analyze log file for patterns
python3 scripts/log_analyzer.py application.log

# Show error lines with context
python3 scripts/log_analyzer.py application.log --show-errors

# Extract stack traces
python3 scripts/log_analyzer.py application.log --show-traces

→ スクリプト：scripts/log_analyzer.py

詳しくはこちら：references/logging_guide.md — 構造化ログ、集約パターン（ELK、Loki、CloudWatch）、PII のマスキング、サンプリング

---

3. アラートの設計

アラート設計の原則

1. 対応可能であること - 対応できない場合は、アラートを送信しないでください
2. 症状に基づくこと - コンポーネントではなく、ユーザーエクスペリエンスに対してアラートを設定します
3. SLO に結び付けること - ビジネスへの影響と関連付けます
4. ノイズを抑えること - 重大な問題に対してのみページ通知します

アラートの重大度レベル

重大度	応答時間	例
重大	直ちにページ通知	サービス停止、SLO 違反
警告	チケットを作成し、数時間以内に確認	エラー率の上昇、リソースに関する警告
情報	注意喚起のために記録	デプロイ完了、スケーリングイベント

マルチウィンドウのバーンレートアラート

エラーバジェットが急速に消費された場合にアラートを送信します。

# Fast burn (1h window) - Critical
- alert: ErrorBudgetFastBurn
  expr: |
    (error_rate / 0.001) > 14.4  # 99.9% SLO
  for: 2m
  labels:
    severity: critical

# Slow burn (6h window) - Warning
- alert: ErrorBudgetSlowBurn
  expr: |
    (error_rate / 0.001) > 6  # 99.9% SLO
  for: 30m
  labels:
    severity: warning

アラート品質チェッカー

ベストプラクティスに照らして、アラートルールを監査します。

# Check single file
python3 scripts/alert_quality_checker.py alerts.yml

# Check all rules in directory
python3 scripts/alert_quality_checker.py /path/to/prometheus/rules/

チェック項目：命名規則、必須ラベル／アノテーション、PromQL の品質、フラッピング防止のための「for」句。

→ スクリプト：scripts/alert_quality_checker.py

アラートテンプレート

本番環境ですぐに使えるアラートルールのテンプレート：

→ テンプレート：

• assets/templates/prometheus-alerts/webapp-alerts.yml - ウェブアプリケーションのアラート
• assets/templates/prometheus-alerts/kubernetes-alerts.yml - Kubernetes のアラート

詳しくはこちら：references/alerting_best_practices.md — アラート設計パターン、ルーティング、抑制ルール、ランブックの構成、オンコールの実践

ランブックのテンプレート

アラート用の包括的なランブックを作成します。

→ テンプレート：assets/templates/runbooks/incident-runbook-template.md

---

4. ダッシュボードと可視化

ダッシュボード設計の原則

1. 上から下へのレイアウト：最も重要なメトリクスを先頭に配置します
2. 色分け：赤（重大）、黄（警告）、緑（正常）
3. 時間範囲の統一：すべてのパネルで同じ時間範囲を使用します
4. パネル数の制限：ダッシュボードあたり最大8～12パネルにします
5. コンテキストの追加：関連するメトリクスをまとめて表示します

推奨レイアウト：全体の健全性（単一統計） -> リクエストレートとエラー -> レイテンシ分布 -> リソース使用状況

Grafana ダッシュボードの生成

テンプレートからダッシュボードを自動生成します。

# Web application dashboard
python3 scripts/dashboard_generator.py webapp \
  --title "My API Dashboard" \
  --service my_api \
  --output dashboard.json

# Kubernetes dashboard
python3 scripts/dashboard_generator.py kubernetes \
  --title "K8s Production" \
  --namespace production \
  --output k8s-dashboard.json

# Database dashboard
python3 scripts/dashboard_generator.py database \
  --title "PostgreSQL" \
  --db-type postgres \
  --instance db.example.com:5432 \
  --output db-dashboard.json

対応対象：ウェブアプリケーション、Kubernetes、データベース（PostgreSQL、MySQL）。

→ スクリプト：scripts/dashboard_generator.py

---

5. SLO とエラーバジェット

SLO の基礎

SLI（測定値）、SLO（目標値）、エラーバジェット（許容される失敗率 = 100% - SLO）。定義の詳細は references/slo_sla_guide.md を参照してください。

一般的な SLO 目標

可用性	月間ダウンタイム	ユースケース
99%	7.2 時間	内部ツール
99.9%	43.2 分	標準的な本番環境
99.95%	21.6 分	重要なサービス
99.99%	4.3 分	高可用性

SLO 計算ツール

コンプライアンス、エラーバジェット、バーンレートを計算します。

# Show SLO reference table
python3 scripts/slo_calculator.py --table

# Calculate availability SLO
python3 scripts/slo_calculator.py availability \
  --slo 99.9 \
  --total-requests 1000000 \
  --failed-requests 1500 \
  --period-days 30

# Calculate burn rate
python3 scripts/slo_calculator.py burn-rate \
  --slo 99.9 \
  --errors 50 \
  --requests 10000 \
  --window-hours 1

→ スクリプト：scripts/slo_calculator.py

詳しくはこちら：references/slo_sla_guide.md — SLI の選定、目標値の設定、エラーバジェットポリシー、バーンレートアラート、SLA 契約

---

6. 分散トレーシング

トレーシングを使用する場面

次のような場合に分散トレーシングを使用します。

• サービス間のパフォーマンスの問題をデバッグする
• マイクロサービスを通じたリクエストの流れを把握する
• 分散システムのボトルネックを特定する
• N+1 クエリの問題を見つける

OpenTelemetry の実装

Python の例：

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

@tracer.start_as_current_span("process_order")
def process_order(order_id):
    span = trace.get_current_span()
    span.set_attribute("order.id", order_id)

    try:
        result = payment_service.charge(order_id)
        span.set_attribute("payment.status", "success")
        return result
    except Exception as e:
        span.set_status(trace.Status(trace.StatusCode.ERROR))
        span.record_exception(e)
        raise

サンプリング戦略

• 開発環境：100%（ALWAYS_ON）
• ステージング環境：50～100%
• 本番環境：1～10%（またはエラーベースのサンプリング）

エラーベースのサンプリング（エラーは常にサンプリングし、成功の1%をサンプリング）：

class ErrorSampler(Sampler):
    def should_sample(self, parent_context, trace_id, name, **kwargs):
        attributes = kwargs.get('attributes', {})

        if attributes.get('error', False):
            return Decision.RECORD_AND_SAMPLE

        if trace_id & 0xFF < 3:  # ~1%
            return Decision.RECORD_AND_SAMPLE

        return Decision.DROP

OTel Collector の設定

→ テンプレート：assets/templates/otel-config/collector-config.yaml — OTLP／Prometheus／ホストメトリクスのレシーバー、バッチ処理、テールサンプリング、複数のエクスポーター（Tempo、Jaeger、Loki、Prometheus、CloudWatch、Datadog）

詳しくはこちら：references/tracing_guide.md — OTel の計装（Python、Node.js、Go、Java）、コンテキスト伝播、バックエンドの比較、分析パターン

---

7. Datadog のコスト最適化と移行

シナリオ1：Datadog を使用していて、コストが高すぎる場合

Datadog UI の Plan & Usage > Usage Summary で使用状況を直接確認するか、API にクエリを送信します。

# Get Datadog usage summary for the current month (requires DD_API_KEY and DD_APP_KEY)
curl -s -X GET "https://api.datadoghq.com/api/v1/usage/summary?start_month=$(date -u +%Y-%m)" \
  -H "DD-API-KEY: ${DD_API_KEY}" \
  -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" | jq .

# Get hourly usage for hosts (identify peak usage)
curl -s -X GET "https://api.datadoghq.com/api/v1/usage/hosts?start_hr=$(date -u -v-24H +%Y-%m-%dT%H)" \
  -H "DD-API-KEY: ${DD_API_KEY}" \
  -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" | jq .

一般的なコスト最適化戦略

• カスタムメトリクス（20～40%のコスト削減）：カーディナリティの高いタグを削除し、使用されていないメトリクスを削除して、送信前に集約します
• ログ管理（30～50%のコスト削減）：大量のログを出力するサービスをサンプリングし、本番環境のデバッグログを除外して、7日後にS3へアーカイブします
• APM（15～25%のコスト削減）：トレースのサンプリング率を下げ（10%から5%へ）、重要でないサービスからAPMを削除します
• インフラストラクチャ（10～20%のコスト削減）：コンテナベースの料金体系を使用し、一時的なインスタンスからエージェントを削除して、ステージング環境を統合します

シナリオ2：Datadog から移行する場合

オープンソースのスタック（Prometheus + Grafana、Loki、Tempo／Jaeger、Alertmanager）へ移行します。推定コスト削減率：60～77%。

移行戦略

• フェーズ1（1～2か月目）：オープンソースのスタックを並行して導入し、まずメトリクスを移行して、正確性を検証します
• フェーズ2（2～3か月目）：ダッシュボードを Grafana に移行し、アラートルールを変換（DQL から PromQL へ）して、チームをトレーニングします
• フェーズ3（3～4か月目）：ログ用に Loki を設定し、トレース用に Tempo／Jaeger を導入して、計装を更新します
• フェーズ4（4～5か月目）：すべての機能の移行を確認し、Datadog を廃止します

移行ガイド全文：references/datadog_migration.md | クエリの変換：references/dql_promql_translation.md

---

8. ツールの選定と比較

ソリューション	月額費用（100ホスト）	最適な用途
Prometheus + Loki + Tempo	$1,500	Kubernetes、予算重視、運用能力のあるチーム
Grafana Cloud	$3,000	オープンソースのスタック、運用負荷の軽減
Datadog	$8,000	使いやすさ、すぐに使える包括的なオブザーバビリティ
ELK Stack	$4,000	大規模なログ分析、高性能な検索
CloudWatch	$2,000	AWS のみを使用する場合、シンプルなニーズ

詳しくはこちら：references/tool_comparison.md — メトリクス、ロギング、トレーシング、フルスタックプラットフォームの詳細な比較

---

9. トラブルシューティングと分析

ヘルスチェックの検証

curl を使用してヘルスチェックのエンドポイントを検証します。

# Check endpoint returns 200 and measure response time
curl -sf -o /dev/null -w "status:%{http_code} time:%{time_total}s\n" https://api.example.com/health

# Get full response body (check for JSON 'status' field, version info)
curl -sf https://api.example.com/health | jq .

# Check multiple endpoints in sequence
for ep in /health /readiness /liveness; do
  printf "%-20s " "$ep"
  curl -sf -o /dev/null -w "status:%{http_code} time:%{time_total}s\n" "https://api.example.com${ep}"
done

確認項目：ステータスが200であること、応答時間が1秒未満であること、status フィールドを含むJSON形式であること、バージョン／ビルド情報があること、依存関係をチェックすること、キャッシュ関連のヘッダーがないこと（Cache-Control: no-cache）。

一般的なトラブルシューティングのワークフロー

レイテンシが高い場合：ダッシュボードで急増を確認 -> 遅い処理のトレースを検索 -> DB のスロークエリを確認 -> 外部 API を確認 -> デプロイを見直す -> リソース使用率を確認

エラー率が高い場合：エラーログを確認 -> 影響を受けているエンドポイントを特定 -> 依存関係の状態を確認 -> デプロイを見直す -> リソース制限を確認 -> 設定を検証

サービスがダウンしている場合：稼働中のポッド／インスタンスを確認 -> ヘルスエンドポイントを確認 -> デプロイを見直す -> リソースの空き状況を確認 -> ネットワークを確認 -> 起動ログを見直す

---

クイックリファレンスコマンド

Prometheus クエリ

# Request rate
sum(rate(http_requests_total[5m]))

# Error rate
sum(rate(http_requests_total{status=~"5.."}[5m]))
  /
sum(rate(http_requests_total[5m])) * 100

# P95 latency
histogram_quantile(0.95,
  sum(rate(http_request_duration_seconds_bucket[5m])) by (le)
)

# CPU usage
100 - (avg(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)

# Memory usage
(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100

Kubernetes、Elasticsearch、Loki、CloudWatch のクエリリファレンスについては、references/quick_commands.md を参照してください。

---

リソースの概要

スクリプト：alert_quality_checker.py | dashboard_generator.py | log_analyzer.py | slo_calculator.py

リファレンス：metrics_design.md | alerting_best_practices.md | logging_guide.md | tracing_guide.md | slo_sla_guide.md | tool_comparison.md | datadog_migration.md | dql_promql_translation.md

テンプレート：prometheus-alerts/webapp-alerts.yml | prometheus-alerts/kubernetes-alerts.yml | otel-config/collector-config.yaml | runbooks/incident-runbook-template.md