4 Oracle Coherenceメトリックの使用

Oracle Coherenceメトリックは、実行中のCoherenceクラスタを監視するための、JMX MBeansに取ってかわる手段です。

この章の内容は次のとおりです。

• Coherenceメトリックについて
  バージョン12.2.1.4では、メトリック・エンドポイントが提供されています。これによりメトリック機能が拡張され、Prometheusなどのメトリック収集システムを使用してメトリックをスクレイプできます。
• Coherenceメトリック・エンドポイントの有効化
  Coherenceメトリック・エンドポイントを有効にするには、Coherenceキャッシュ・サーバーの起動時にシステム・プロパティcoherence.metrics.http.enabledをtrueに設定します。
• WebLogic管理対象CoherenceサーバーのCoherenceメトリック・エンドポイント
  Coherenceには、メトリック・エンドポイントを提供するメトリック・リソースが含まれます。Prometheusなどのメトリック収集システムを使用してメトリックをスクレイピングすることで、このメトリック・エンドポイントを使用して、WebLogic管理対象Coherenceサーバーのメトリック機能を拡張できます。
• メトリック・システム・プロパティの使用
  メトリック・システム・プロパティは、coherence.jarのmetrics-http-config.xmlファイルで定義されます。
• Coherenceメトリック・エンドポイントをスクレイプするようにPrometheusを構成
  CoherenceクラスタのCoherenceメトリック・エンドポイントをスクレイプするようにスクレイピング・ジョブを構成するには、Prometheus構成ファイルのstatic_configsパラメータを使用します。
• Grafanaでのメトリックのビジュアル化
  これらのダッシュボードは、収集されたメトリックを使用してCoherenceクラスタの詳細なインサイトを提供し、クラスタの状態をモニタリングおよび管理するための貴重なツールです。
• Coherenceメトリックの問合せ
  メトリック・エンドポイントでは、Prometheus形式とJSON形式をサポートしています。また、名前やタグによる特定メトリックの問合せもサポートされています。
• カスタム・メトリックの追加
  Coherenceレジストリに追加するMBeansに注釈を付ける場合は、独自のメトリックを追加できます。
• Coherence Micrometerメトリックの使用
  coherence-micrometerモジュールは、CoherenceメトリックとMicrometerの統合を提供し、いずれかのMicrometerレジストリを介してCoherenceメトリックを公開できるようにします。

Coherenceメトリックについて

バージョン12.2.1.4では、メトリック・エンドポイントが提供されています。これによりメトリック機能が拡張され、Prometheusなどのメトリック収集システムを使用してメトリックをスクレイプできます。各Coherenceキャッシュ・サーバーでCoherenceメトリック・エンドポイントが有効化され、これらのエンドポイントの場所でPrometheusスクレイピング・ジョブが構成されます。

アプリケーションでCoherenceメトリック・エンドポイントを保護する必要がある場合は、Coherenceメトリック・エンドポイントをセキュアに構成し、必要なセキュリティ情報でPrometheusスクレイピング・ジョブを構成できます。Oracle Coherenceの保護のOracle Coherenceメトリックの保護に関する項を参照してください。

Coherenceメトリック・エンドポイントでは、gzipのcontent - encodingがサポートされます。デフォルトでは、メトリックのエンドポイントは、テキストまたはPrometheus形式でメトリックを返しますが、Accepts: application/json HTTPヘッダーが設定されている場合は、メトリックをJSON形式で返すこともできます。

Oracle Coherenceメトリック・エンドポイントを保護するには、『Oracle Coherenceの保護』の「Oracle Coherenceメトリックの保護」を参照してください。

このリリースのCoherenceでは、coherence-metricsモジュールが非推奨となり、すべてのメトリック機能がcoherence.jarに移行されました。これまでのバージョンとは異なり、Coherenceメトリックでは、サードパーティの依存性を必要としなくなりました。そのため、このモジュールは将来のリリースで削除されるので、すべてのアプリケーションでcoherence-metrics.jarへの依存性を削除する必要があります。

Coherenceメトリック・エンドポイントの有効化

Coherenceメトリック・エンドポイントを有効にするには、Coherenceキャッシュ・サーバーの起動時にシステム・プロパティcoherence.metrics.http.enabledをtrueに設定します。

WebLogic管理対象CoherenceサーバーのCoherenceメトリック・エンドポイント

Coherenceには、メトリック・エンドポイントを提供するメトリック・リソースが含まれます。Prometheusなどのメトリック収集システムを使用してメトリックをスクレイピングすることで、このメトリック・エンドポイントを使用して、WebLogic管理対象Coherenceサーバーのメトリック機能を拡張できます。

Coherenceメトリック・エンドポイントを有効にするには、管理対象WebLogic管理対象Coherenceサーバーの起動時に、coherence.metrics.http.enabledシステム・プロパティをtrueに設定します。

エンドポイントURLは、WebLogic管理対象サーバー・リスニング・ポートに基づいています。ポートが7003に設定されている場合、次のURLは完全なCoherenceメトリックを返します: http://<serverHost>:7003/management/coherence/metrics。

特定のメトリックの問合せもできます。たとえば、クラスタ・サイズを取得するには、このURLを使用します:

http://<serverHost>:7003/management/coherence/metrics/Coherence.Cluster.Size?cluster=<CoherenceClusterName>

メトリック・システム・プロパティの使用

メトリック・システム・プロパティは、coherence.jarのmetrics-http-config.xmlファイルで定義されます。

この項では、次の項目について説明します。

• Coherenceメトリック・システム・プロパティ
  次のCoherenceメトリック・システム・プロパティは、coherence.jarのデフォルトのmetrics-http-config.xmlファイルで定義されます。
• その他のメトリック・システム・プロパティ
  その他のメトリック・システム・プロパティには、次のものがあります。

Coherenceメトリック・システム・プロパティ

次のCoherenceメトリック・システム・プロパティは、coherence.jarのデフォルトのmetrics-http-config.xmlファイルで定義されます。

表4-1 Coherenceメトリック・システム・プロパティ

システム・プロパティ	説明	デフォルト
coherence.metrics.http.enabled	メトリック・エンドポイントが有効かどうかを判断します	false
coherence.metrics.http.address	リスニングするアドレスを指定します	0.0.0.0 (すべてのインタフェース)
coherence.metrics.http.port	リスニングするポートを指定します(0はエフェメラル・ポートを示します)	9612
coherence.metrics.http.auth	HTTPサーバーbasic、auth、basic+auth またはnot setの認証メカニズムを構成します	未設定
coherence.metrics.http.provider	Coherenceオペレーション・オーバーライド・ファイルの<socket-provider>のIDを定義します	なし
coherence.metrics.http.path	メトリック・コンテキストのルート・パスを指定します。	未設定

デフォルトのmetrics-http-config.xmlをオーバーライドするには、クラスパスで同じファイル名のオーバーライド・ファイルをcoherence.jarより前に置きます。

ノート:

メトリック・エンドポイントが有効になっている複数のCoherenceキャッシュ・サーバーが同じマシン上で起動されている場合、coherence.metrics.http.portは各サーバーで一意である必要があります。そうでない場合、同じcoherence.metrics.http.port値を持つ後続のサーバーは、すでに使用中のアドレスを取得するため、MetricsHttpProxyサービスの起動時にエラーが発生します。

Coherenceキャッシュ・サーバーは起動しますが、Coherenceメトリック・エンドポイントは1つのCoherenceキャッシュ・サーバーでのみ使用できます。

その他のメトリック・システム・プロパティ

その他のメトリック・システム・プロパティには、次のものがあります。

表4-2 その他のメトリック・システム・プロパティ

システム・プロパティ	説明	デフォルト
coherence.metrics.extended	メトリックを発行する際の、拡張情報(タイプや説明)が含まれます。	false

Prometheusメトリックの拡張情報は#Helpで、メトリック名が含まれます。さらにデータが続く場合、#Helpはそのメトリック名のドックストリングとみなされます。Coherenceメトリックの場合、ドックストリングは通常、メトリック値が導出されたJMX MBean属性の説明です。Prometheusレスポンスには、メトリック値ごとに1つの#Helpが存在するか、または存在しません。

Coherenceメトリック・エンドポイントをスクレイプするようにPrometheusを構成

CoherenceクラスタのCoherenceメトリック・エンドポイントをスクレイプするようにスクレイピング・ジョブを構成するには、Prometheus構成ファイルのstatic_configsパラメータを使用します。Prometheus構成ファイルのstatic_configsのCoherenceメトリック・エンドポイントごとに、IPアドレスとcoherence.metrics.http.portを指定する必要があります。構成して起動した後、Prometheusサーバーは構成された間隔で、構成された静的ターゲットをスクレイプし、Coherenceクラスタのメトリック・データを収集します。

Prometheus構成ドキュメントを参照してください。

ノート:

Coherenceメトリック・エンドポイントによって公開されるプレーン・テキスト形式のメトリック名(Prometheusによってスクレイピングされる場合など)は、vendor:coherence_<metric_name>形式です。このレガシー名形式は非推奨であり、今後のCoherenceリリースでcoherence_<metric_name>に変更される予定です。つまり、vendor:接頭辞が削除されます。将来のメトリック名形式を使用する場合は、Coherenceの起動時にcoherence.metrics.legacy.namesシステム・プロパティをfalseに設定します。

Grafanaでのメトリックのビジュアル化

メトリックをスクレイプするようにPrometheusを構成したら、Coherenceオペレータで使用可能な事前組込みのGrafanaダッシュボードを使用してこれらのメトリックをビジュアル化できます。coherence-operatorを参照してください。

これらのダッシュボードは、収集されたメトリックを使用してCoherenceクラスタの詳細なインサイトを提供し、クラスタの状態をモニタリングおよび管理するための貴重なツールです。

ダッシュボードとそのロード方法の詳細は、Coherence Operatorのドキュメントを参照してください。

Coherenceサマリー・ダッシュボードの例は、ダッシュボードの使用を参照してください。

ノート:

Oracleでは、Grafanaの最小バージョン8.5.13を使用してダッシュボードを表示することをお薦めします。現時点では、Grafana 9.xには多くの問題があるため、このバージョンはまだ使用しないでください。

Coherenceメトリックの問合せ

メトリック・エンドポイントでは、Prometheus形式とJSON形式をサポートしています。また、名前やタグによる特定メトリックの問合せもサポートされています。

この項では、次の項目について説明します。

• 基本的な問合せ
  以下に示す基本的な問合せの例では、coherence.metrics.http.portは9612に設定されていると想定します。
• 特定のメトリックの問合せ
  特定のメトリックを問合せるには、URLにメトリック名を追加します。

基本的な問合せ

以下に示す基本的な問合せの例では、coherence.metrics.http.portは9612に設定されていると想定します。

http://localhost:9612/metrics

デフォルトでは、これによりPrometheusの簡易なテキストベースの説明形式が生成されます。コール元がAccepts: application/jsonヘッダーを使用する場合、JSONが戻されます。エンドポイントでは、URLに必要なタイプを追加することで、コンテンツのネゴシエーションもサポートされます。

http://localhost:9612/metrics/.txtではPrometheusデータが返されますが、http://localhost:9612/metrics/.jsonではJSONデータが返されます。

coherence.metrics.extendedシステム・プロパティは、追加のヘルプまたは説明を含めるかどうかを制御します。デフォルトでは、coherence.metrics.extendedはfalseに設定されており、追加情報は含まれません。extended=true問合せパラメータを追加することにより、追加データを含めることができます。

http://localhost:9612/metrics?extended=true (これは、Prometheus形式とJSON形式の両方に適用されます)。

特定のメトリックの問合せ

特定のメトリックを問い合せるには、URLにメトリック名を追加します。

クラスタ内のメンバー数を問い合せるには:

http://localhost:9612/metrics/Coherence.Cluster.Size

すべてのキャッシュ・サイズ・メトリックを問い合せるには:

http://localhost:9612/metrics/Coherence.Cache.Size

タグが一致するメトリックを問い合せるには、タグ・キーと値を問合せパラメータとして追加します。キャッシュ名がcache_nameの特定のキャッシュのサイズ・メトリックを問い合せるには:

http://localhost:9612/metrics/Coherence.Cache.Size?name=cache_name

また、フロント層とバック層を持つようにキャッシュ(たとえばニア・キャッシュ)を含める場合、リクエストはさらに制限される可能性があります。

http://localhost:9612/metrics/Coherence.Cache.Size?name=cache_name&tier=back

http://localhost:9612/metrics/Coherence.Cache.Size?name=cache_name&tier=front

カスタム・メトリックの追加

Coherenceレジストリに追加するMBeansに注釈を付ける場合は、独自のメトリックを追加できます。

たとえば:

import com.tangosol.net.management.annotation.MetricsValue;
import com.tangosol.net.management.annotation.MetricsTag;   

public interface CustomMBean
    {
    @MetricsValue("custom_value")
    long getValueOne();

    @MetricsValue
    long getValueTwo();

    long getValueThree();

    @MetricsTag("custom_tag")
    String getTagValueOne();

    @MetricsTag
    String getTagValueTwo();
    }

• メソッドgetValueOneには、@MetricValueの注釈が付けられます。それによって、メトリックになり、メトリックの名前はcustom_valueになります。

• メソッドgetValueTwoには、@MetricValueの注釈が付けられます。それによって、メトリックとなります。注釈では名前は指定されないため、名前は属性名から生成されます(この場合はvalue_two)。

• メソッドgetValueThreeには注釈は付けられません。それによって、MBean属性であっても、メトリックまたはタグとしては使用されません。

• メソッドgetTagValueOneには、@MetricTagの注釈が付けられます。それによって、メトリック・タグになり、タグの名前はcustom_tagになります。

• メソッドgetTagValueTwoには、@MetricTagの注釈が付けられます。それによって、メトリック・タグとなります。注釈では名前は指定されないため、名前は属性名から生成されます(この場合はtag_value_two)。

MBeanの登録時にCoherenceで注釈を検出するには、注釈をAnnotatedStandardMBeanにラップする必要があります。

たとえば:

Registry registry   = CacheFactory.ensureCluster().getManagement();
Custom   custom     = new Custom();
String   sMBeanName = registry.ensureGlobalName(“type=Custom,name=bar”);

registry.register(sMBeanName, new AnnotatedStandardMBean(custom, CustomMBean.class));

前述のコードでは、MbeanはCoherence:type=Custom,name=bar,nodeId=1のようなオブジェクト名で登録されます

生成されるメトリック名には、ObjectNameのタイプ・キーの値(この場合はCustom)が接頭辞として付けられます。これにより、次のメトリックが生成されます。

• メソッドgetValueOneからCustom_custom_value
• メソッドgetValueTwoからCustom_value_two

どちらのメトリックも、クラスタ名、ノードID、マシン、ロール、サイトなどの共通タグとカスタム・タグを持ちます(ObjectNameからのname=bar、注釈付きメソッドgetTagValueOneからのcustom_tag、注釈付きメソッドgetTagValueTwoからのtag_value_two)。メソッドgetTagValueTwoには、@MetricTagの注釈が付けられます。それによって、メトリック・タグとなります。注釈では名前は指定されないため、名前は属性名から生成されます(この場合はtag_value_two)。

Coherence Micrometerメトリックの使用

coherence-micrometerモジュールは、CoherenceメトリックとMicrometerの統合を提供し、いずれかのMicrometerレジストリを介してCoherenceメトリックを公開できるようにします。

この項には次のトピックが含まれます:

• Coherence Micrometerメトリックの使用の有効化
  
• 自動グローバル・レジストリ・バインディング
  

Coherence Micrometerメトリックの使用の有効化

Coherence Micrometerメトリックを使用するには、pom.xmlファイルでモジュールを依存性として宣言し、MicrometerレジストリをCoherenceメトリック・アダプタとバインドする必要があります:

<dependency>
    <groupId>${coherence.groupId}</groupId>
    <artifactId>coherence-micrometer</artifactId>
    <version>${coherence.version}</version>
</dependency>

coherence-micrometerは、CoherenceMicrometerMetricsというMicrometer MeterBinder実装クラスを提供します。このクラスはシングルトンであり、構成できません。このクラスにアクセスするには、CoherenceMicrometerMetrics.INSTANCEフィールドを使用します。

Micrometerは、様々なメトリック・アプリケーションおよびフォーマットをサポートする多数のレジストリ実装を提供します。たとえば、CoherenceメトリックをMicrometer PrometheusMeterRegistryにバインドするには、PrometheusMeterRegistryを作成します。詳細は、Micrometerドキュメントを参照し、CoherenceMicrometerMetricsクラスのbindToメソッドをコールしてください:

PrometheusMeterRegistry prometheusRegistry = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);

// complete the registry configuration...

CoherenceMicrometerMetrics.INSTANCE.bindTo(prometheusRegistry);

Micrometerレジストリは、いつでも(Coherenceの起動前または起動後に) Coherenceにバインドできます。Coherenceによってメトリックが作成または削除されると、メトリックがMicrometerレジストリに登録されるかMicrometerレジストリから削除されます。

自動グローバル・レジストリ・バインディング

Micrometerには、coherence.micrometer.bind.to.globalシステム・プロパティをtrueに設定した場合にCoherenceによって自動的にバインドされるグローバル・レジストリがあります(このプロパティはデフォルトではfalseです)。