第25章 Eclipse MicroProfile

設定データは動的に変更でき、アプリケーションはサーバーを再起動せずに最新の設定情報にアクセスできる必要があります。Eclipse MicroProfile Config は設定データのポータブルな外部化を実現します。これにより、変更や再パッケージ化を必要とせずに、アプリケーションとマイクロサービスを複数の環境で実行するよう設定することができます。Eclipse MicroProfile Config 機能は、SmallRye Config を使用して JBoss EAP に実装され、microprofile-config-smallrye サブシステムによって提供されます。このサブシステムはデフォルトの JBoss EAP 7.4 設定に含まれています。

形式や元の場所が異なることがある MicroProfile Config 設定プロパティーは、org.eclipse.microprofile.config.spi.ConfigSource インターフェースの実装である ConfigSources によって提供されます。

MicroProfile Config 仕様は、設定値を取得するために、以下のデフォルト ConfigSource 実装を提供します。

microprofile-config-smallrye サブシステムは、設定値を取得するために ConfigSource リソースの以下の追加タイプをサポートします。

MicroProfile Config SmallRye サブシステムの設定に使用できる属性のリストは「MicroProfile Config SmallRye サブシステムの属性」を参照してください。

プロパティーからの ConfigSource 設定の取得

ConfigSource のアクセス用にプロパティーを直接保存するには、config-source 属性を追加し、properties をリストとして指定します。

以下の管理 CLI コマンドは property1 および property2 プロパティーの設定データが含まれる ConfigSource を作成します。

/subsystem=microprofile-config-smallrye/config-source=props:add(properties={property1=value1,property2=value2})

このコマンドを実行すると、microprofile-config-smallrye サブシステムに以下の XML 設定が指定されます。

<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0">
    <config-source name="props">
        <property name="property1" value="value1"/>
        <property name="property2" value="value2"/>
    </config-source>
</subsystem>

ディレクトリーからの ConfigSource 設定の取得

ConfigSource を作成してディレクトリーのファイルからプロパティーを読み取りするには、config-source 属性を追加して、ファイルが含まれるディレクトリーを指定します。dir ディレクトリーの各ファイルの名前はプロパティーの名前で、ファイルの内容はプロパティーの値になります。

以下の CLI コマンドは、/etc/config/numbers-app/ ディレクトリーのファイルから設定プロパティーを読み取る ConfigSource を作成します。

/subsystem=microprofile-config-smallrye/config-source=file-props:add(dir={path=/etc/config/numbers-app})

このコマンドを実行すると、microprofile-config-smallrye サブシステムに以下の XML 設定が指定されます。

<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0">
    <config-source name="file-props">
        <dir path="/etc/config/numbers-app"/>
    </config-source>
</subsystem>

この構造は、OpenShift の ConfigMaps によって使用される構造に対応します。dir の値は、OpenShift または Kubernetes の ConfigMap 定義にある mountPath に対応します。

JBoss EAP にデプロイされたすべてのアプリケーションは、ディレクトリーに保存されたプロパティーにプログラムを使用してアクセスできます。

/etc/config/numbers-app/ ディレクトリーに以下の 2 つのファイルが含まれていることを仮定します。

以下のコード例では、num.size は 5 を返し、num.max は 100 を返します。

@Inject
@ConfigProperty(name = "num.size")
int numSize;

@Inject
@ConfigProperty(name = "num.max")
int numMax;

ConfigSource クラスからの ConfigSource 設定の取得

カスタムの org.eclipse.microprofile.config.spi.ConfigSource 実装クラスを作成および設定して、設定値のソースを提供することができます。

以下の管理 CLI コマンドは、org.example という名前の JBoss Module によって提供される、org.example.MyConfigSource という名前の実装クラスの ConfigSource を作成します。

/subsystem=microprofile-config-smallrye/config-source=my-config-source:add(class={name=org.example.MyConfigSource, module=org.example})

このコマンドを実行すると、microprofile-config-smallrye サブシステムに以下の XML 設定が指定されます。

<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0">
    <config-source name="my-config-source">
        <class name="org.example.MyConfigSource" module="org.example"/>
    </config-source>
</subsystem>

この ConfigSource クラスによって提供されるプロパティーはすべての JBoss EAP デプロイメントで使用できます。

JBoss EAP サーバーにグローバルモジュールを追加する方法は「グローバルモジュールの定義」を参照してください。

ConfigSourceProvider クラスからの ConfigSource 設定の取得

複数の ConfigSource インスタンスの実装を登録する、カスタムの org.eclipse.microprofile.config.spi.ConfigSourceProvider 実装クラスを作成および設定できます。

以下の管理 CLI コマンドは、org.example という名前の JBoss Module によって提供される、org.example.MyConfigSourceProvider という名前の実装クラスの config-source-provider を作成します。

/subsystem=microprofile-config-smallrye/config-source-provider=my-config-source-provider:add(class={name=org.example.MyConfigSourceProvider, module=org.example})

このコマンドを実行すると、microprofile-config-smallrye サブシステムに以下の XML 設定が指定されます。

<subsystem xmlns="urn:wildfly:microprofile-config-smallrye:1.0">
    <config-source-provider name="my-config-source-provider">
         <class name="org.example.MyConfigSourceProvider" module="org.example"/>
    </config-source-provider>
</subsystem>

ConfigSourceProvider 実装によって提供されるプロパティーはすべての JBoss EAP デプロイメントで使用できます。

JBoss EAP サーバーにグローバルモジュールを追加する方法は「グローバルモジュールの定義」を参照してください。

Java コードで MicroProfile Config にアクセスするアプリケーションは、CDI を有効にする必要があります。 これには、デプロイメントアーカイブに META-INF/beans.xml または WEB-INF/beans.xml ファイルが含まれるようにするか、CDI bean アノテーションが含まれるようにします。

CDI の詳細は、JBoss EAP 『開発ガイド』 の「 コンテキストおよび依存関係の挿入(CDI) 」を参照してください。

サービス境界全体でリクエストをトレースする機能は、ライフサイクル中にリクエストが複数のサービスを通過するマイクロサービス環境で特に重要となります。Eclipse Microprofile OpenTracing 仕様は、Jakarta RESTful Web Services アプリケーション内の Open Tacing 対応の Tracer オブジェクトにアクセスするための、動作および API を定義します。動作は、送受信リクエストに対してどのように Open Tracing Spans が自動的に作成されるかを指定します。API は、指定のエンドポイントのトレースをどのように明示的に無効または有効にするかを定義します。

Eclipse MicroProfile Open Tracing 機能は、SmallRye OpenTracing コンポーネントを使用して JBoss EAP に実装され、microprofile-opentracing-smallrye サブシステムによって提供されます。このサブシステムは、JAX-RS エンドポイントへのリクエストのトレースと CDI bean のサポートが含まれる Microprofile 1.3.0 を実装し、デフォルトの JBoss EAP 7.4 設定に含まれています。

microprofile-opentracing-smallrye には Jaeger Client がデフォルトのトレーサーとして同梱されています。また、Jakarta RESTful Web Services や Contexts and Dependency Injection など Jakarta EE アプリケーションで一般的に使用されるコンポーネントのインスツルメンテーションライブラリーのセットも含まれています。JBoss EAP サーバーに自動的にデプロイされた各 WAR は、独自の Tracer インスタンスを持ちます。EAR 内の各 WAR は個別の WAR として扱われ、各 WAR には独自の Tracer インスタンスがあります。デフォルトでは、Jaeger Client と使用されるサービス名はデプロイメントの名前から派生し、通常これは WAR ファイル名になります。

microprofile-opentracing-smallrye サブシステムは、デフォルトの JBoss EAP 7.4 設定に含まれています。有効な OpenTracing にはメモリーまたはパフォーマンスコストが関係するため、このサブシステムを無効にしたい場合があります。

以下の管理 CLI コマンドを使用してサーバー設定からサブシステムを削除し、サーバーインスタンスに対して MicroProfile Open Tracing 機能をグローバルに無効にします。

以下の管理 CLI コマンドを使用してサーバー設定にサブシステムを追加し、サーバーインスタンスに対して MicroProfile Open Tracing 機能をグローバルに有効にします。

microprofile-opentracing-smallrye サブシステムに使用できる別の設定オプションはありません。代わりに、システムプロパティーまたは環境変数を設定して Jaeger Client を設定します。Jaeger Client の設定方法に関する詳細は、Jaeger のドキュメント を参照してください。有効なシステムプロパティーのリストは Jaeger ドキュメントの「Configuration via Environment」を参照してください。

デフォルトトレーサーをオーバーライドする方法と、CDI bean のトレース方法に関する詳細は、『開発ガイド』 の「 Eclipse MicroProfile OpenTracing を使用したリクエストのトレース 」を参照してください。

JBoss EAP には、microprofile-health-smallrye サブシステムを使用して Eclipse MicroProfile Health 機能を提供する SmallRye Health コンポーネントが含まれています。このサブシステムは、JBoss EAP インスタンスが想定どおりに応答しているかどうかを判断するために使用され、デフォルトで有効になっています。

Microprofile Health は、JBoss EAP をスタンドアロンサーバーとして実行している場合のみ利用できます。

ヘルスチェックは管理 CLI を使用して確認できます。

/subsystem=microprofile-health-smallrye:check
{
    "outcome" => "success",
    "result" => {
        "outcome" => "UP",
        "checks" => []
    }
}

/subsystem=microprofile-health-smallrye:check-live
{
    "outcome" => "success",
    "result" => {
        "outcome" => "UP",
        "checks" => []
    }
}

/subsystem=microprofile-health-smallrye:check-ready
{
    "outcome" => "success",
    "result" => {
        "outcome" => "UP",
        "checks" => []
    }
}

管理コンソールには、ヘルスチェックとグローバルの結果をブール値として表示するチェックランタイム操作が含まれます。

管理コンソールからサーバーの現在の状態を取得するには、以下を実行します。

ヘルスチェックは自動的に JBoss EAP の health コンテキストにデプロイされます。

That means that in addition to being able to examine it using the management CLI, you can also obtain the current health using the HTTP endpoint. The default address for the `/health` endpoint, accessible from the management interfaces, is `http://127.0.0.1:9990/health`.

http://HOST:9990/health

このコンテキストにアクセスすると、サーバーの正常性を示すヘルスチェックが JSON 形式で表示されます。このエンドポイントは liveness プローブと readiness プローブの両方の正常性を確認します。

http://HOST:9990/health/live

http://HOST:9990/health/ready

:empty-readiness-checks-status および :empty-liveness-checks-status は、readiness プローブまたは liveness プローブが定義されていない場合のグローバルステータスを指定する管理属性です。これらの属性により、アプリケーションは、そのアプリケーションが ready/live であることをプローブが確認するまで、’DOWN’ を報告できるようになります。デフォルトでは、これらの属性は ’UP’ を報告します。

/subsystem=microprofile-health-smallrye:read-attribute(name=empty-readiness-checks-status)
{
    "outcome" => "success",
    "result" => expression "${env.MP_HEALTH_EMPTY_READINESS_CHECKS_STATUS:UP}"
}

/subsystem=microprofile-health-smallrye:read-attribute(name=empty-liveness-checks-status)
{
    "outcome" => "success",
    "result" => expression "${env.MP_HEALTH_EMPTY_LIVENESS_CHECKS_STATUS:UP}"
}

readiness および liveness プローブの両方を確認する /health HTTP エンドポイントと :check 操作は、これらの属性も考慮します。

health コンテキストを設定すると、このコンテキストへのアクセスにユーザーの認証を必要とすることができます。

このエンドポイントで認証を有効にするには、以下の手順に従います。

health エンドポイントにアクセスしようとすると、認証プロンプトが表示されるようになります。

JBoss EAP では、microprofile-metrics-smallrye サブシステムを使用して Eclipse MicroProfile Metrics 機能を提供する SmallRye Metrics コンポーネントが含まれるようになりました。このサブシステムは、JBoss EAP インスタンスのモニタリングデータを提供するために使用されます。これはデフォルトで有効です。

メトリクスは JBoss EAP 管理インターフェースで自動的に利用できるようになり、以下のコンテキストを使用できます。

JBoss EAP サブシステムメトリクスは Prometheus 形式で公開されます。

メトリクス名はサブシステムと属性名に基づきます。たとえば、サブシステム undertow は、アプリケーションデプロイメントのすべてのサーブレットのメトリクス属性 request-count を公開します。このメトリクスの名前は jboss_undertow_request_count です。接頭辞 jboss はメトリクスソースを特定するのに役立ちます。

EAP で公開されるメトリクスの一覧を表示するには、CLI で以下のコマンドを実行します。

$ curl -v http://localhost:9990/metrics | grep -i type

helloworld-rs クイックスタートの request-count メトリックを確認するには、以下の手順に従います。

管理コンソールでは、以下の設定を実行できます。

管理コンソールを使用して MicroProfile メトリクスを設定するには、以下の手順に従います。

metroics コンテキストおよびすべてのサブコンテキストは、コンテキストのアクセスにユーザー許可を必須にするように設定できます。以下の手順は、このエンドポイントで認証を有効にします。

サブシステムが metrics エンドポイントにアクセスを試みると、認証プロンプトが表示されるようになりました。