4 Oracle Coherenceメトリックの使用

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

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

• Coherenceメトリックについて
  バージョン12.2.1.4では、メトリック・エンドポイントが提供されています。これによりメトリック機能が拡張され、Prometheusなどのメトリック収集システムを使用してメトリックをスクレイプできます。
• Coherenceメトリック・エンドポイントの有効化
  Coherenceメトリック・エンドポイントには、COHERENCE_HOME/lib/coherence-metrics.jarライブラリおよび、そのサード・パーティの依存関係が必要です。
• メトリック・システム・プロパティの使用
  メトリック・システム・プロパティは、coherence-metrics.jarのmetrics-http-config.xmlファイルで定義されます。
• Coherenceメトリック・エンドポイントをスクレイプするようにPrometheusを構成
  CoherenceクラスタのCoherenceメトリック・エンドポイントをスクレイプするようにスクレイピング・ジョブを構成するには、Prometheus構成ファイルのstatic_configsパラメータを使用します。
• Grafanaでのメトリックのビジュアル化
  これらのダッシュボードは、収集されたメトリックを使用してCoherenceクラスタの詳細なインサイトを提供し、クラスタの状態をモニタリングおよび管理するための貴重なツールです。
• Coherenceメトリックの問合せ
  メトリック・エンドポイントでは、Prometheus形式とJSON形式をサポートしています。また、名前やタグによる特定メトリックの問合せもサポートされています。
• カスタム・メトリックの追加
  Coherenceレジストリに追加するMBeansに注釈を付ける場合は、独自のメトリックを追加できます。
• Fusion MiddlewareドメインでCoherenceメトリックにアクセスするためのWebアプリケーションの作成
  HTTPエンドポイントを使用してWebLogic管理対象サーバーでCoherenceを実行するときにCoherenceメトリックにアクセスする場合、Webアプリケーションをデプロイする必要があります。

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メトリック・エンドポイントには、COHERENCE_HOME/lib/coherence-metrics.jarライブラリおよび、そのサード・パーティの依存関係が必要です。

Coherenceキャッシュ・サーバーに対してCoherenceメトリック・エンドポイントを有効にするには、Coherenceメトリック・モジュールとその依存関係をクラスパスに追加し、Coherenceキャッシュ・サーバーの起動時にシステム・プロパティcoherence.metrics.http.enabledをtrueに設定します。

ノート:

Coherence Distributionには、サード・パーティの依存関係は含まれません。

Mavenを使用して依存関係を管理することをお薦めします。Mavenリポジトリ・マネージャの移入に関する項の説明に従って、Oracle Maven同期プラグインを使用し、最新のOracle CoherenceアーティファクトがローカルのMavenリポジトリにインストールされていることを前提とします。サード・パーティ・ライブラリを含むクラスパスを生成するには、下のpom.xmlを使用して、次のMavenコマンドを実行します。サーバー・スクリプトを起動するには、生成されたクラスパスを追加します。

mvn dependency:build-classpath

JDK 11で実行している場合は、mvnコマンドラインに-P jdk11を追加して、JDK 11の一部ではなくなった追加ライブラリを取得します。

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <artifactId>metrics</artifactId>
  <groupId>metrics-deps</groupId>
  <version>12.2.1-4-0</version>
  <name>Coherence Metrics dependencies</name>
  <packaging>pom</packaging>
  <dependencies>
    <dependency>
      <groupId>com.oracle.coherence</groupId>
      <artifactId>coherence-metrics</artifactId>
      <version>${project.version}</version>
    </dependency>
  </dependencies>
  <profiles>
    <profile>
      <id>jdk11</id>
      <properties>
        <com.sun.xml.bind.version>2.3.0</com.sun.xml.bind.version>
        <javax.activation.version>1.1.1</javax.activation.version>
      </properties>
      <dependencies>
	<dependency>
          <groupId>com.sun.xml.bind</groupId>
          <artifactId>jaxb-core</artifactId>
          <version>${com.sun.xml.bind.version}</version>
        </dependency>
        <dependency>
          <groupId>com.sun.xml.bind</groupId>
          <artifactId>jaxb-impl</artifactId>   
          <version>${com.sun.xml.bind.version}</version>
        </dependency>
        <dependency>
          <groupId>javax.activation</groupId>
          <artifactId>activation</artifactId>
          <version>${javax.activation.version}</version>
        </dependency>
        <dependency>
          <groupId>javax.xml.bind</groupId>
          <artifactId>jaxb-api</artifactId>
          <version>${com.sun.xml.bind.version}</version>
        </dependency>
      </dependencies>
    </profile>
  </profiles>
</project>

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

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

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

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

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

次のCoherenceメトリック・システム・プロパティは、coherence-metrics.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.jarより前に同じファイル名のオーバーライド・ファイルを置くことで、デフォルトのmetrics-http-config.xmlをオーバーライドできます。

ノート:

メトリック・エンドポイントが有効になっている複数の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構成ドキュメントを参照してください。

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)。

Fusion MiddlewareドメインでCoherenceメトリックにアクセスするためのWebアプリケーションの作成

HTTPエンドポイントを使用してWebLogic管理対象サーバーでCoherenceを実行するときにCoherenceメトリックにアクセスする場合、Webアプリケーションをデプロイする必要があります。

CoherenceメトリックにアクセスするためのWebアプリケーションを構築する方法の例を次に示します:

1. Webアプリケーションのディレクトリを作成します:

   $ mkdir coherence-metrics-resource

2. Webアプリケーション・ディレクトリに移動し、WEB-INFディレクトリを作成します。

   $ cd coherence-metrics-resource
   $ mkdir WEB-INF

3. WEB-INFディレクトリにある次のweb.xmlおよびweblogic.xmlファイルを追加します。必要に応じて、weblogic.xmlの<context-root>の名前を変更できます。
   WEB-INF/web.xml

   <?xml version="1.0" encoding="UTF-8"?>
   <web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee 
            http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
            version="3.1">
   
     <display-name>Coherence Metrics REST Resources</display-name>
     <description>Coherence Metrics REST Resources</description>
   
     <servlet>
       <servlet-name>coherence.metrics.rest.Application</servlet-name>
       <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
         <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>com.tangosol.coherence.metrics.internal.MetricsResourceConfig</param-value>
        </init-param>
     </servlet>
   
     <servlet-mapping>
       <servlet-name>coherence.metrics.rest.Application</servlet-name>
       <url-pattern>/*</url-pattern>
     </servlet-mapping>
   </web-app>

   WEB-INF/weblogic.xml

   <?xml version="1.0" encoding="UTF-8"?>
   
   <weblogic-web-app
            xmlns="http://xmlns.oracle.com/weblogic/weblogic-web-app"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           
   xsi:schemaLocation="http://xmlns.oracle.com/weblogic/weblogic-web-app">
   
     <context-root>/coherence/metrics</context-root>
   
   </weblogic-web-app>

4. Webアプリケーション.warファイルを構築します。Webアプリケーションの親ディレクトリに移動し、次のコマンドを使用して.warファイルを作成します:

   $ jar cvf coherence-metrics-resource.war -C coherence-metrics-resource

5. coherence-metrics-resource.warファイルを管理対象Coherenceサーバーにデプロイします。

Webアプリケーションを介してメトリックにアクセスするには、管理対象Coherenceサーバー(WebLogic Server)のリスニング・ポートを使用します。

たとえば、WebLogic Serverがポート7002でリスニングしている場合、メトリックにアクセスするためのURLは次のようになります:

http://<Host>:7002/coherence/metrics