注意制限事項: WebOTX Application Server Manual

WebOTX Manual V10.4 (第4版)

目次を表示

23. マイクロサービス

マイクロサービスに関する注意・制限事項について説明します。

23.1. MicroProfile OpenTracing

23.1.1. 注意事項

23.1.1.1. 同梱するOSSのバージョンについて

本バージョンで同梱している OpenTracing 関連 OSS と、そのバージョンは、次の通りです。

OpenTracing 関連 OSS バージョン
OSS	グループID:アーティファクトID	バージョン
OpenTracing API	io.opentracing:opentracing-api	0.33.0
OpenTracing NoOp	io.opentracing:opentracing-noop	0.33.0
OpenTracing Utilities	io.opentracing:opentracing-util	0.33.0
OpenTracing JAXRS2	io.opentracing.contrib:opentracing-jaxrs2	1.0.0
OpenTracing Web Servlet Filter	io.opentracing.contrib:opentracing-web-servlet-filter	0.4.1
OpenTracing Concurrent	io.opentracing.contrib:opentracing-concurrent	0.4.0
Tracer Resolver	io.opentracing.contrib:opentracing-tracerresolver	0.1.8

本バージョンの MicroProfile OpenTracing は、トレーサー実装として Jaeger に対応しており、バージョン 1.21.0 にて動作確認を行っています。また、トレース採取に必要な Jaeger Client と、それが依存する OSS を同梱しています。各 OSS のバージョンは次の通りです。アプリケーションで、独自に、これらの OSS を利用する場合は、同梱している同じバージョンのものを利用してください。

Jaeger Client で利用する OSS
OSS	グループID:アーティファクトID	バージョン
Jaeger Client	io.jaegertracing:jaeger-client	1.4.0
	io.jaegertracing:jaeger-core	1.4.0
	io.jaegertracing:jaeger-thrift	1.4.0
	io.jaegertracing:jaeger-tracerresolver	1.4.0
Apache Thrift	org.apache.thrift:libthrift	0.13.0
OkHttp	com.squareup.okhttp3:okhttp	4.2.2
Okio	com.squareup.okio:okio	2.2.2
Kotlin Stdlib	org.jetbrains.kotlin:kotlin-stdlib	1.3.50
Kotlin Stdlib Common	org.jetbrains.kotlin:kotlin-stdlib-common	1.3.50
JetBrains Java Annotations	org.jetbrains:annotations	13
Gson	com.google.code.gson:gson	2.8.6
SLF4J API Module	org.slf4j:slf4j-api	1.7.28
SLF4J Simple Binding	org.slf4j:slf4j-simple	1.7.28

23.1.1.2. Jaeger 利用時の JAEGER_PASSWORD の設定値について

JAEGER_PASSWORD には、運用管理コマンド (otxadmin) の encrypt コマンドで暗号化した値を設定してください。なお、運用管理コマンドは、WebOTX Application Server がインストールされていない環境でも、WebOTX Developer や、ライセンス不要の WebOTX Client をインストールすることで利用可能です。

23.1.2. 制限事項

制限事項はありません。

23.2. MicroProfile Fault Tolerance

23.2.1. 注意事項

注意事項はありません。

23.2.2. 制限事項

23.2.2.1. アプリケーション配備解除時のMicroProfile Fault Tolerance 動作への影響

複数アプリケーションを配備している場合、アプリケーションの配備解除時に、その他のアプリケーションでのMicroProfile Fault Toleranceの処理が重なると、以下のような影響があります。

「@Asynchronous」アノテーションを付与したメソッドの処理中は、処理が完了するまでの間、アプリケーション配備解除の待ち合わせが発生します。
アプリケーションの配備解除中、「@Timeout」「@Asynchronous」アノテーションを付与したメソッドが実行エラー（500 Internal Server Error）となりますが、配備解除完了後は正常に実行可能です。
「@CircuitBreaker」アノテーションを使用している場合、アプリケーションの配備解除を行うと配備されている全てのアプリケーションのCircuitBreakerがClose状態に戻り、実行回数・異常発生回数のカウントが0に戻ります。

上記事象については、次の回避策があります。

アプリケーションの配備解除や再配備を行う際は、Webサーバを一時的に停止してクライアントからMicroProfile Fault Toleranceを利用するアプリケーションへのアクセスが来ない状態にするか、運用に支障のない時間帯に行ってください。
MicroProfile Fault Toleranceのアノテーションを使用するアプリケーションを、他のアプリケーションとは異なるプロセスグループに配備している場合は、影響ありません。

23.2.2.2. 同一メソッドを実装するアプリケーションを複数配備した場合のMicroProfile Fault Tolerance 動作への影響

複数アプリケーション間で「パッケージ名」＋「クラス名」＋「メソッド名」の組み合わせが完全に一致するメソッドが存在する場合、当該メソッドで次の事象が発生します。

MicroProfile Metrics 機能を用いてメトリクス情報を取得する際、対象アプリケーションが判別できません。
「@Bulkhead」アノテーションを付与している場合、同時実行数および待機キューが複数アプリケーション間で共有されます。
例）
アプリケーションＡとアプリケーションＢに、下記アノテーションを付与した同一メソッドが存在する場合
```
@Asynchronous
@Bulkhead(value=2, waitingTaskQueue=1)
```
アプリケーションＡの当該メソッドに3件のリクエストを同時実行すると、同時実行可能数：2件から溢れた1件のリクエストを待機キューにキューイングします。
その状態でアプリケーションＢの当該メソッドにリクエストを実行すると、本来はリクエストを受け付ける必要がありますが、同時実行数および待機キューが最大であると判断し、BulkheadExceptionが発生します。
「@CircuitBreaker」を付与している場合、CircuitBreakerの情報（実行回数、異常発生回数、連続成功回数、遅延時間）が、複数アプリケーション間で共有されます。
例）
アプリケーションＡとアプリケーションＢに、下記アノテーションを付与した同一メソッドが存在する場合
```
@CircuitBreaker(requestVolumeThreshold=4, failureRatio=0.5)
```
アプリケーションＡの当該メソッドが直近4回リクエスト中3回成功・1回失敗の状態、およびアプリケーションＢの当該メソッドが直近4回リクエスト中4回成功・失敗なしの状態で、アプリケーションＢの当該メソッドが1回失敗した際、4回中1回失敗の状態となる為、本来はサーキットブレーカーを閉じた状態のままである必要がありますが、 4回中2回失敗したと判断し、サーキットブレーカーが開いた状態となります。
「@Timeout」「@Bulkhead」「@CircuitBreaker」アノテーションいずれかを付与している場合、WebOTXのサービス起動後に最初に動作したアプリケーションの設定値が優先されます。（後に動作したアプリケーションは最初に動作したアプリケーションの設定値で動作します。）

上記事象については、次の回避策があります。

複数アプリケーション間で「パッケージ名」＋「クラス名」＋「メソッド名」の組み合わせが完全に一致するメソッドが存在する場合は、「パッケージ名」・「クラス名」・「メソッド名」のいずれかを変更してください。
同一の組み合わせを持つアプリケーションを、それぞれ異なるプロセスグループに配備している場合は、影響ありません。

23.3. MicroProfile OpenAPI

23.3.1. 注意事項

本製品の内蔵WebサーバでCORSフィルタ(org.apache.catalina.filters.CorsFilter)を使用する場合、<filter-mapping>属性の<url-pattern>に /* を指定することは推奨していません。（セキュリティ観点）
開発・評価用に一時的に使用するなど、使用方法にご注意ください。

23.3.2. 制限事項

23.3.2.1. @DiscriminatorMappingの使用に関して

本製品では未サポートの機能となります。
代替手段として静的ファイル (openapi.yaml等) で直接OpenAPIドキュメントを作成し、その中で discriminator属性を定義してください。
または、フィルタ機能を使用して、discriminator属性を定義してください。

23.4. MicroProfile Config

23.4.1. 注意事項

同じシステムにWebOTXの複数バージョンをインストールした場合の注意点
同じシステムにWebOTXの複数バージョンをインストールした場合、MicroProfile Configの環境変数を利用したプロパティがシステム内で共有されることに注意してください。

23.4.2. 制限事項

制限事項はありません。

23.5. MicroProfile Health

23.5.1. 注意事項

ブラウザでのMicroProfile Health Checkレスポンス受信
マイクロサービス環境のMicroProfile Health Check(/health エンドポイント)にInternet Explorerブラウザよりアクセスした場合レスポンス結果をファイルに保存しようとします。この時、Health Checkの結果がネガティブでありレスポンスのステータスコードが 503であった場合、ブラウザのファイルへの保存処理が終了しない現象が発生する場合があります。この現象はInternet Explorerブラウザ固有の動作であり回避する方法はありません。ブラウザからHealth Check結果を確認する必要がある場合は他のブラウザからアクセスしてください。

/healthエンドポイントについて
full-profile環境ではマイクロサービスのヘルスチェック機能が動作するため /healthエンドポイントを使用します。しかし、マイクロサービスが有効な状態でアプリケーションのコンテキストルートを/healthで配備した場合、リクエストは配備したアプリケーションが優先されます。マイクロサービスのヘルスチェック機能を使用する場合、コンテキストルートに/healthを使用しないでください。

ユーザが作成するMicroProfile Healthはエージェントプロセス上でのみ動作する
ユーザが作成するMicroProfile Healthを実装したアプリケーションはエージェントプロセス上でのみ動作します。このため、プロセスグループに配備しても情報応答クラス(*1)の情報は収集しません。
(*1)
- org.eclipse.microprofile.health.HealthCheck を継承し以下のアノテーションを定義したクラス
  - org.eclipse.microprofile.health.Health

23.5.2. 制限事項

制限事項はありません。

23.6. MicroProfile Metrics

23.6.1. 注意事項

/metricsエンドポイントについて
full-profile環境ではマイクロサービスのメトリクス機能が動作するため /metricsエンドポイントを使用します。しかし、マイクロサービスが有効な状態でアプリケーションのコンテキストルートを/metricsで配備した場合、リクエストは配備したアプリケーションが優先されます。マイクロサービスのメトリクス機能を使用する場合、コンテキストルートに/metricsを使用しないでください。

同じシステムにWebOTXの複数バージョンをインストールした場合の注意点
同じシステムにWebOTXの複数バージョンをインストールした場合、MicroProfile Metricsのグローバルタグを指定する環境変数MP_METRICS_TAGSがシステム内で共有されることに注意してください。

ユーザが作成するMicroProfile Metricsはエージェントプロセス上でのみ動作する
ユーザが作成するMicroProfile Metricsを実装したアプリケーションはエージェントプロセス上でのみ動作します。このため、プロセスグループに配備しても情報応答クラス(*1)の情報は収集しません。
(*1)
- org.eclipse.microprofile.metrics.annotation.XXXX アノテーションを定義したクラス

23.6.2. 制限事項

制限事項はありません。

23.7. マイクロサービスプロファイル(Uber JAR)

23.7.1. 注意事項

23.7.1.1. マイクロサービスプロファイル(Uber JAR)はフォアグラウンドプロセスとして起動される

マイクロサービスプロファイル(Uber JAR)を以下のコマンドで起動すると、フォアグラウンドのプロセスとして起動します。そのため、起動したプロセスが終了するまで制御は戻ってきません。プロセスを終了するには、Ctrl+C で終了します。

java -jar <WebOTX Uber JARファイル名>

バックグラウンドで実行するには、各OSのバックグラウンドプロセスを起動する方法でjavaコマンドを実行してください。例えば、Windowsのコマンドプロンプトではstartコマンドで、PowerShellではStart-Processコマンドでバックグラウンドプロセスを起動できます。また、Linuxのbashでは起動コマンドの最後に & を付けることでバックグラウンドプロセスを起動できます。

23.7.1.2. マイクロサービスプロファイル(Uber JAR)の展開先ディレクトリにマルチバイト文字を含むパスを使用することはできない

マイクロサービスプロファイル(Uber JAR)の展開先ディレクトリにマルチバイト文字を含むパスを使用することはできません。
展開先ディレクトリは、起動時の--basedirオプションで指定します。指定が無い場合、標準の一時ディレクトリに展開されます。
標準の一時ディレクトリのパスにマルチバイト文字が含まれる場合は、--basedirオプションでマルチバイト文字を含まないパスを展開先ディレクトリとして指定する必要があります。

展開先ディレクトリにマルチバイト文字を含むパスを使用すると、アプリケーションのロードに失敗するため、アプリケーションにアクセスすると 404 エラーとなります。
また、起動時に下記のログが出力されます。
出力先ログファイルは <展開先ディレクトリ>/WebOTX/domains/domain1/logs/agent.log です。 --log-to-stdio オプションを指定した場合は標準出力にログが出力されます。

ERROR    DEPLOY   - OTX03010194: 配備に失敗しました。: 配備処理中にエラーが発生しました: アプリケーション [<アプリケーション名>] の配備中に例外が発生しました。 : org.xml.sax.SAXParseExceptionpublicId: file:/<展開先ディレクトリ>/WebOTX/lib/schemas/web-app_3_1.xsd; lineNumber: 281; columnNumber: 47; Deployment descriptor file WEB-INF/web.xml in archive [<アプリケーション名>].  src-resolve: 名前'javaee:web-commonType'を'group'コンポーネントに解決できません。 [main]

23.7.2. 制限事項

制限事項はありません。