182-java-observability-metrics-micrometer

Micrometer による Java メトリクスのオブザーバビリティ

意味のあるサービスレベルのメトリクスを定義し、カーディナリティを制御し、適切なメータータイプを選択して、本番環境に対応したテレメトリーをダッシュボードやアラートに公開することで、Micrometer を使った効果的な Java メトリクス計測を実装します。

このスキルで扱う内容

• Java アプリケーションにおける Micrometer を使ったメトリクス中心のオブザーバビリティ
• メーターの選択：Counter、Timer、DistributionSummary、Gauge、LongTaskTimer
• 低カーディナリティのディメンションを用いた命名規則とタグ付け規則
• 時系列の爆発を防ぐカーディナリティとメーターのライフサイクルに関する安全対策
• ヒストグラム／パーセンタイル戦略と SLO を重視したメトリクス設計
• Actuator と Prometheus／OpenTelemetry パイプラインの統合に関するガイダンス
• メトリクスの登録と値のテストおよび検証

対象範囲： Java サービスにおけるアプリケーションレベルのメトリクス設計と計測品質。運用に役立ち、コスト効率の高いテレメトリーを重視します。

制約事項

メトリクスの計測は、運用上安全で、低カーディナリティであり、検証済みである必要があります。不適切なタグ設計や過剰なメーター作成は、オブザーバビリティシステムの性能を低下させ、コストを増加させる可能性があります。

• まず低カーディナリティを優先：上限のない値（userId、UUID、生の URL、例外メッセージ全体）をメトリクスのタグに指定しないでください
• 適切なメータータイプを選択：単調に増加するイベントには Counter、レイテンシには Timer、ある時点の状態には Gauge、サンプリングされた値には DistributionSummary を使用してください
• 適用前に確認：適切な計測例、不適切な計測例、アンチパターンについて、リファレンスを読んでください
• 検証：変更後に ./mvnw clean verify または mvn clean verify を実行してください

このスキルを使う場面

• メトリクスを改善する
• Micrometer を適用する
• メトリクスのオブザーバビリティを追加する
• Micrometer による計測をリファクタリングする
• Java サービスに Micrometer のタイマー、カウンター、ゲージを追加する

ワークフロー

1. 測定目標とメーターの契約を定義する

重要なサービス指標（スループット、レイテンシ、エラー率、飽和度）を特定し、それぞれを安定したメトリクス名、単位、低カーディナリティのタグに対応付けます。

2. メータータイプを選択し、コードパスを計測する

適切な箇所で Counter／Timer／Gauge／DistributionSummary／LongTaskTimer を適用し、一貫した命名規則と再利用可能なタグを使用します。

3. 本番環境向けに計測を堅牢化する

カーディナリティを制御し、動的なメーターの頻繁な生成を避け、必要な箇所に限ってヒストグラム／パーセンタイル戦略を設定し、エクスポート設定をテレメトリーのバックエンドに合わせます。

4. メトリクスを検証し、運用に活用する

テストと実行時のエンドポイントでメトリクスを検証し、想定されるラベルと単位を確認して、出力された時系列をダッシュボードやアラートで利用できることを確かめます。

リファレンス

詳しいガイダンス、例、制約事項については、references/182-java-observability-metrics-micrometer.md を参照してください。