Oracle Coherenceメトリックの使用

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リリース14.1.1.2206より前では、Coherenceメトリック機能はcoherence-metricsモジュールによって提供されていました。ただし、Coherence 14.1.1.2206以降では、すべてのメトリック機能がcoherence.jarに移されています。これまでのバージョンとは異なり、Coherenceメトリックでは、すべてのサードパーティの依存関係を必要としなくなりました。したがって、このモジュールが削除されたため、すべてのアプリケーションでcoherence-metrics.jarに対する依存関係を削除する必要があります。

親トピック: Oracle Coherenceメトリックの使用

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

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

親トピック: Oracle Coherenceメトリックの使用

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>

親トピック: Oracle Coherenceメトリックの使用

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

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

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

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

親トピック: Oracle Coherenceメトリックの使用

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`

デフォルトの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メトリックの名前と説明を取得するには、システム・プロパティcoherence.metrics.extendedをtrueに設定します。URLを使用して行うこともできます。メトリック・ポートが9612に設定されている場合、次のURLによって使用可能なすべてのメトリック名と説明が返されます:

http://<serverHost>:9612/metrics?extended=true

キャッシュ・サイズ・メトリックの名前と説明とその値を取得するには、次のURLを使用します:

http://<serverHost>:9612/metrics/Coherence.Cache.Size?extended=true

次のような結果が返されます:

# TYPE coherence_cache_size gauge
# HELP coherence_cache_size The number of entries in the cache.
  coherence_cache_size {cluster="coherence's cluster", coherence_service="DistributedCacheService", machine="localhost", member="null", name="dist-test1", node_id="2", role="SimpleMetricsTests", site="null", tier="back"} 100

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

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

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

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

ノート:

Coherenceメトリック・エンドポイントによって公開されるプレーン・テキスト形式のメトリック名(Prometheusによってスクレイピングされる場合など)は、coherence_<metric_name>形式です。Oracle Coherenceリリース14.1.2.0.0から、vendor:接頭辞が付けられたレガシー名の形式は、デフォルト・オプションではなくなりました(14.1.1.2206で非推奨となったため)。Grafanaダッシュボードの最新バージョンについては、coherence_<metric_name>メトリックに関係するCoherence Operatorプロジェクトを参照してください。

メトリックのレガシー名を使用する場合は、Coherenceの起動時にcoherence.metrics.legacy.namesシステム・プロパティをtrueに設定します。

親トピック: Oracle Coherenceメトリックの使用

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

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

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

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

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

ノート:

Oracleでは、Grafanaバージョン10.0.13以降を使用してダッシュボードを表示することをお薦めします。

親トピック: Oracle Coherenceメトリックの使用

Coherenceメトリックの問合せ

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

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

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

親トピック: Oracle Coherenceメトリックの使用

基本的な問合せ

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

http://localhost:9612/metrics

この問合せによって、使用可能なすべてのCoherenceメトリックが返されます。デフォルトでは、これにより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形式の両方に適用されます)。

この問合せによって、使用可能なすべてのCoherenceメトリックと説明が返されます。

親トピック: Coherenceメトリックの問合せ

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

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

Coherenceメトリック名は、次の規則を使用してCoherence MBean属性から導出できます:

Coherence_<MBeanType>_<AttributeName>
キャメル・ケースであるMBean名または属性が、アンダースコア(_)で区切られます。たとえば、ConnectionManager MBeanのメトリック名はconnection_managerです。AverageRequestTimeという属性名のメトリック名はaverage_request_timeになります。ConnectionManager MBeanのAverageRequestTimeのメトリック名全体は、coherence_connection_manager_average_request_timeです。
繰り返される名前は削除されます。たとえば、Cluster MBeanのClusterSize属性のメトリック名はcoherence_cluster_sizeです(「ClusterSize」の「Cluster」の部分は削除されます)。
定数属性はメトリックにマップされません

Cluster MBean内のメンバー数を表す属性ClusterSizeを問い合せるには:

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

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

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

ここでは、MBean型はCache、属性名は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)。

親トピック: Oracle Coherenceメトリックの使用

Coherence Micrometerメトリックの使用

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

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

親トピック: Oracle Coherenceメトリックの使用

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レジストリから削除されます。

親トピック: Coherence Micrometerメトリックの使用

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

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

親トピック: Coherence Micrometerメトリックの使用