付録D.4 分散トレーシング機能との連携
HMP-ADIFは分散トレーシングに関する機能を提供します。本製品とHMP-ADIFの分散トレーシング機能を連携することによって,次のことを実現できます。
- HMP-ADIFのトレース情報を本製品のトレースログに出力
-
これによって,トレースログでは,Webアプリケーション実行基盤の処理に加え,HMP-ADIFを利用して開発したアプリケーションの処理も確認できます。
- 本製品がトレースログに出力するトレース情報をHMP-ADIFに送信
-
これによって,HMP-ADIFの分散トレーシング機能で,Webアプリケーション実行基盤の処理とHMP-ADIFの処理をまとめて可視化できます。
なお,分散トレーシングでは複数のマシンやコンテナ上で実行される,複数のサービスの処理が可視化されます。したがって,性能影響個所や障害発生個所のマシンやコンテナを特定することなく,トレースログを確認できます。
また,本製品のトレース情報をトレースログに出力する際,分散トレーシングでのTraceIDおよびSpanIDに相当する情報をトレース情報に付与して出力します。これによって,トレースログに出力されたトレース情報と,分散トレーシングで可視化されたトレース情報の紐づけが容易にでき,可読性が向上します。
本製品とHMP-ADIFを連携して使用した場合のイメージを次に示します。HMP-ADIFの分散トレーシング機能については,HMP-ADIFの取扱説明書を参照してください。
|
(1) HMP-ADIFのトレース情報をトレースログに出力
HMP-ADIFのトレース情報を本製品のトレースログに出力できます。出力対象となるHMP-ADIFのトレース情報は「表D-1 HMP-ADIFのトレース情報のトレース取得ポイント」に記載されたものに限ります。HMP-ADIFのトレース情報をトレースログに出力するには,tracer.hmp.adif.output-span-as-trace.enabledプロパティにtrueを指定してください。設定方法については「18.2.4(5) トレース機能に関するプロパティ」を参照してください。
HMP-ADIFのトレース情報はSpanとして抽象化されています。トレース取得ポイント,取得レベルや取得できるトレース情報の一覧を次に示します。Spanの詳細は「付録D.4(2) トレース情報をHMP-ADIFに送信」を参照してください。
シーケンス図と の対応 |
イベントID |
トレース取得ポイント |
取得レベル |
リターンコード(Rc) |
インターフェイス名(INT) |
オペレーション情報(OPR) |
ASCII |
---|---|---|---|---|---|---|---|
トレース1 |
0xe400 |
HMP-ADIFが独自トレース※1機能のSpanを開始した直後※2 |
FINE |
0 |
Spanの名前 |
- |
TraceIDおよびSpanIDに相当する情報※3 |
トレース2 |
0xe401 |
HMP-ADIFが独自トレース※1機能のSpanを終了した直後※2 |
FINE |
0 |
Spanの名前 |
- |
TraceIDおよびSpanIDに相当する情報※3 |
トレース3 |
0xe402 |
HMP-ADIFがハンドラの実行に対するSpanを開始した直後 |
FINE |
0 |
Spanの名前 |
- |
TraceIDおよびSpanIDに相当する情報※3 |
トレース4 |
0xe403 |
HMP-ADIFがハンドラの実行に対するSpanを終了した直後 |
FINE |
|
Spanの名前 |
- |
TraceIDおよびSpanIDに相当する情報※3 |
トレース5 |
0xe404 |
HMP-ADIFがISC機能による他サービス呼び出しに対するSpanを開始した直後 |
FINE |
0 |
Spanの名前 |
ISCコマンドの他サービスの名前 |
TraceIDおよびSpanIDに相当する情報※3 |
トレース6 |
0xe405 |
HMP-ADIFがISC機能による他サービス呼び出しに対するSpanを終了した直後 |
FINE |
|
Spanの名前 |
ISCコマンドの他サービスの名前 |
TraceIDおよびSpanIDに相当する情報※3 |
トレース7 |
0xe406 |
HMP-ADIFがISCキャッシュプラグインのキャッシュを使用した場合に対するSpanを開始した直後 |
FINE |
0 |
Spanの名前 |
ISCコマンドのキャッシュのキー名 |
TraceIDおよびSpanIDに相当する情報※3 |
トレース8 |
0xe407 |
HMP-ADIFがISCキャッシュプラグインのキャッシュを使用した場合に対するSpanを終了した直後 |
FINE |
0 |
Spanの名前 |
ISCコマンドのキャッシュのキー名 |
TraceIDおよびSpanIDに相当する情報※3 |
トレース9 |
0xe408 |
HMP-ADIFがキャッシュへのアクセスに対するSpanを開始した直後 |
FINE |
0 |
Spanの名前 |
- |
TraceIDおよびSpanIDに相当する情報※3 |
トレース10 |
0xe409 |
HMP-ADIFがキャッシュへのアクセスに対するSpanを終了した直後 |
FINE |
|
Spanの名前 |
- |
TraceIDおよびSpanIDに相当する情報※3 |
- 注※1
-
独自トレースとはHMP-ADIFのトレースを指します。
- 注※2
-
HMP-ADIFの仕様変更などによって,次に示すもの以外にHMP-ADIFのトレース情報を取得する場合,そのHMP-ADIFのトレース情報のSpanの開始と終了のタイミングで0xe400および0xe401がそれぞれ出力されます。
・ハンドラの実行
・ISC機能による他サービス呼び出し
・ISCキャッシュプラグインのキャッシュを使用
・キャッシュへのアクセス
- 注※3
-
HMP-ADIFのトレース情報に含まれている,TraceIDおよびSpanIDに相当する情報を出力します。
TraceIDに相当する情報とは,トレース管理基盤が定義するリクエストごとに一意のIDです。SpanIDに相当する情報とは,トレース管理基盤が定義するSpanごとに一意のIDです。
TraceIDおよびSpanIDに相当する情報はトレース管理基盤ごとに異なるため,詳細は使用するトレース管理基盤のドキュメントを参照してください。出力フォーマットは次のとおりです。
"<TraceIDに相当する情報のキー1>:<TraceIDに相当する情報の値1>,<TraceIDに相当する情報のキー2>:<TraceIDに相当する情報の値2>, (TraceIDに相当する情報が存在する分だけ繰り返し), <SpanIDに相当する情報のキー1>:<SpanIDに相当する情報の値1>,<SpanIDに相当する情報のキー2>:<SpanIDに相当する情報の値2>,(SpanIDに相当する情報が存在する分だけ繰り返し)"
次の詳細はHMP-ADIFの取扱説明書を参照してください。
・<TraceIDに相当する情報のキー>
・<TraceIDに相当する情報の値>
・<SpanIDに相当する情報のキー>
・<SpanIDに相当する情報の値>
- トレース取得シーケンス
-
HMP-ADIFのトレース取得シーケンスを次の図に示します。なお,図中の番号(トレース1など)は,「表D-1 HMP-ADIFのトレース情報のトレース取得ポイント」と対応しています。
図D‒3 HMP-ADIFのトレース取得シーケンス
(2) トレース情報をHMP-ADIFに送信
本製品がトレースログに出力するトレース情報をHMP-ADIFに送信します。送信したトレース情報はHMP-ADIFのトレース情報として分散トレーシングで可視化できます。この機能の目的は,リクエストの受信からレスポンスの送信までを可視化することです。
トレース情報をHMP-ADIFに送信するには,tracer.hmp-adif.send-trace-as-span.enabledプロパティにtrueを設定してください。設定方法については「18.2.4(5) トレース機能に関するプロパティ」を参照してください。
トレース情報をHMP-ADIFに送信するには,ログ取得レベルを次のどれかに設定してください。
-
FINE
-
FINER
-
FINEST
-
ALL
また,次のトレースはHMP-ADIFに送信しません。
-
ルートAP情報とクライアントAP情報のどちらも含まれていないトレース
-
「リクエストを処理するスレッド以外のスレッド」で実行された処理のトレース
-
「表D-2 HMP-ADIFに送信されないトレース」に該当するトレース
表D‒2 HMP-ADIFに送信されないトレース トレース名
イベントID
トレース取得ポイント
サーバ開始・終了時のトレース
0xe200
サーバが起動するとき
0xe201
サーバが終了するとき
Webアプリケーションのトレース
0xe210
Webアプリケーションが開始するとき
0xe211
Webアプリケーションが停止するとき
Beanのトレース
0xe310
SpringApplicationクラスが生成したApplicationContextによるBean生成直後
0xe311
SpringApplicationクラスが生成したApplicationContextによるBean破棄直前
ApplicationContext初期化・停止時のトレース
0xe320
SpringApplicationクラスが生成したApplicationContextの初期化,またはリフレッシュを完了したとき
0xe321
SpringApplicationクラスが生成したApplicationContextを停止するとき
HTTPリクエストのトレース
0xe230※1
HTTPリクエストを受信した直後
0xe231※1
HTTPレスポンスを送信する直前
0xe240※1
最初のサーブレットまたはフィルタを呼び出す直前
0xe241※1
最後のサーブレットの処理,または最初のフィルタの処理が完了した直後
0xe330※2
javax.servlet.Filterまたはorg.springframework.web.server.WebFilterを最初に呼び出す直前
0xe331※2
最初に呼び出したjavax.servlet.Filterまたはorg.springframework.web.server.WebFilterが完了した直後
0xe332
org.springframework.web.servlet.DispatcherServletによってHandlerを実行する前
0xe333
org.springframework.web.servlet.DispatcherServletによってHandlerを実行したあと
0xe334
org.springframework.web.servlet.DispatcherServletによってViewレンダリングしたあと
0xe335
org.springframework.web.servlet.DispatcherServletによって非同期HTTPリクエスト処理を開始したあと
HTTPセッションのトレース
0xe250
HTTPセッションが作成された直後
0xe251
HTTPセッションが無効にされる直前
JAX-RSクライアントのトレース
0xe260
JAX-RSクライアントでHTTPリクエストが発行される前
0xe261
JAX-RSクライアントでHTTPリクエストが発行され,HTTPレスポンスを受け取ったあと
WebClientのトレース
0xe350
org.springframework.web.reactive.function.client.WebClientによってHTTPリクエストを送信するとき
0xe351
org.springframework.web.reactive.function.client.WebClientによってHTTPレスポンスを受信するとき
Tomcat JDBC Connection Poolのトレース
0xe270
javax.sql.DataSource.getConnectionメソッドの呼び出しでコネクション取得に成功した直後
HMP-ADIFのトレース情報のトレース
0xe400
HMP-ADIFが独自トレース機能のSpanを開始した直後
0xe401
HMP-ADIFが独自トレース機能のSpanを終了した直後
0xe402
HMP-ADIFがハンドラの実行に対するSpanを開始した直後
0xe403
HMP-ADIFがハンドラの実行に対するSpanを終了した直後
0xe404
HMP-ADIFがISC機能による他サービス呼び出しに対するSpanを開始した直後
0xe405
HMP-ADIFがISC機能による他サービス呼び出しに対するSpanを終了した直後
0xe406
HMP-ADIFがISCキャッシュプラグインのキャッシュを使用した場合に対するSpanを開始した直後
0xe407
HMP-ADIFがISCキャッシュプラグインのキャッシュを使用した場合に対するSpanを終了した直後
0xe408
HMP-ADIFがキャッシュへのアクセスに対するSpanを開始した直後
0xe409
HMP-ADIFがキャッシュへのアクセスに対するSpanを終了した直後
- 注※1
-
非同期リクエストの場合だけHMP-ADIFに送信しません。
- 注※2
-
org.springframework.web.server.WebFilter使用するときだけHMP-ADIFに送信しません。
HMP-ADIFのトレース情報はSpanとして抽象化されています。SpanはHMP-ADIFのトレースの単位であり,ネストにできます。HMP-ADIFは本製品のSpanを親Spanとして,ハンドラのSpanを生成します。そのあとHMP-ADIFは仕様に従い,子Spanを生成します。本製品はHMP-ADIFが生成したSpanを親Spanとして,HMP-ADIFのハンドラに呼び出された処理のSpanを生成します。Spanの親子関係のイメージを次に示します。
|
トレース情報をHMP-ADIFに送信する場合のSpanの名前を次の表に示します。
送信するケース |
Spanの名前 |
名前の例 |
---|---|---|
トレース情報をHMP-ADIFに送信する場合 |
ucartrace:<Spanの開始に対応するトレース取得ポイントのイベントID> |
ucartrace:0xe230 |
トレース情報をHMP-ADIFに送信する場合,次に示すトレース情報の内容が,1つのSpanのメタデータとして含まれます。
-
Spanの開始に対応するトレース情報の内容
-
Spanの終了に対応するトレース情報の内容
ただし,トレース情報の項目に情報がない場合,対応するSpanのメタデータは付与しません。
Spanのメタデータは,キーバリュー形式です。Spanのメタデータのキー名は次の規則で決定されます。
"ucar.<タイミング>.<トレース情報の項目を示す文字列>"
<タイミング>は,Spanの開始に対応するトレース情報の場合は“start”,Spanの終了に対応するトレース情報の場合は“finish”となります。<トレース情報の項目を示す文字列>は,メタデータが含むトレース情報の項目によって異なります。トレース情報の項目およびタイミングと,メタデータのキー名の対応は「表D-4 トレース情報の項目およびタイミングとメタデータのキー名の対応」を参照してください。
メタデータの値の形式は,トレースログに出力される形式と同一です。ただし,トレースログに""で囲んで出力される項目の出力内容は,""で囲まれない形式でメタデータの値に設定されます。
トレース情報の項目およびタイミングと,メタデータのキー名の対応は,次のとおりです。
トレース情報の項目 |
トレース情報の取得タイミング |
メタデータのキー名 |
値の例 |
---|---|---|---|
Process |
Span開始時 |
ucar.start.Process |
27476 |
Process |
Span終了時 |
ucar.finish.Process |
27476 |
Thread(hashcode) |
Span開始時 |
ucar.start.Thread |
20(0x6b21fae1) |
Thread(hashcode) |
Span終了時 |
ucar.finish.Thread |
20(0x6b21fae1) |
Trace |
Span開始時 |
ucar.start.Trace |
123 |
Trace |
Span終了時 |
ucar.finish.Trace |
162 |
Event |
Span開始時 |
ucar.start.Event |
0xe230 |
Event |
Span終了時 |
ucar.finish.Event |
0xe231 |
Date |
Span開始時 |
ucar.start.Date |
2024/07/15 |
Date |
Span終了時 |
ucar.finish.Date |
2024/07/15 |
TimeおよびTime(msec/usec/nsec)※ |
Span開始時 |
ucar.start.Time |
14:04:45.453/462/782 |
TimeおよびTime(msec/usec/nsec)※ |
Span終了時 |
ucar.finish.Time |
14:04:47.128/141/683 |
Rc |
Span開始時 |
ucar.start.Rc |
0 |
Rc |
Span終了時 |
ucar.finish.Rc |
0 |
ClientAP IP |
Span開始時 |
ucar.start.ClientAP_IP |
103.126.213.18 |
ClientAP IP |
Span終了時 |
ucar.finish.ClientAP_IP |
103.126.213.18 |
ClientAP PID |
Span開始時 |
ucar.start.ClientAP_PID |
27476 |
ClientAP PID |
Span終了時 |
ucar.finish.ClientAP_PID |
27476 |
ClientAP CommNo. |
Span開始時 |
ucar.start.ClientAP_CommNo |
0x0000000000000021 |
ClientAP CommNo. |
Span終了時 |
ucar.finish.ClientAP_CommNo |
0x0000000000000021 |
RootAP IP |
Span開始時 |
ucar.start.RootAP_IP |
103.126.213.18 |
RootAP IP |
Span終了時 |
ucar.finish.RootAP_IP |
103.126.213.18 |
RootAP PID |
Span開始時 |
ucar.start.RootAP_PID |
27476 |
RootAP PID |
Span終了時 |
ucar.finish.RootAP_PID |
27476 |
RootAP CommNo. |
Span開始時 |
ucar.start.RootAP_CommNo |
0x0000000000000021 |
RootAP CommNo. |
Span終了時 |
ucar.finish.RootAP_CommNo |
0x0000000000000021 |
INT |
Span開始時 |
ucar.start.INT |
GET |
INT |
Span終了時 |
ucar.finish.INT |
GET |
OPR |
Span開始時 |
ucar.start.OPR |
/myapplication |
OPR |
Span終了時 |
ucar.finish.OPR |
/myapplication |
ASCII |
Span開始時 |
ucar.start.ASCII |
JaegerTraceID:A1B2C3D4E5F6A7B8,JaegerSpanID:0F8D9E7C6B5A4321 |
ASCII |
Span終了時 |
ucar.finish.ASCII |
JaegerTraceID:A1B2C3D4E5F6A7B8,JaegerSpanID:0F8D9E7C6B5A4321 |
- 注※
-
メタデータの値はトレース情報のTimeとTime(msec/usec/nsec)の内容を結合した次の形式です。
"<Timeの出力内容>.<Time(msec/usec/nsec)の出力内容>"
0xe230(HTTPリクエストを受信した直後)および0xe231(HTTPレスポンスを送信する直前)に対応するトレース情報の場合,相関IDの情報をSpanのメタデータとして付与します。メタデータのキー名および値は次の形式です。
キー名: 相関IDのカスタム名 値: 相関IDの値
相関IDのカスタム名および相関IDの値の内容については,HMP-ADIFの取扱説明書を参照してください。
メタデータの出力形式はトレース管理基盤およびトレース取得ポイントによって異なり,次の形式で出力します。
トレース 管理基盤 |
トレース取得ポイント |
メタデータの出力形式 |
---|---|---|
Jaeger |
すべてのトレース取得ポイント |
Jaegerのタグとして出力されます。タグのキーとタグの値が,メタデータのキー名とメタデータの値に一致するように出力します。 |
AWS X-Ray |
|
AWS X-Rayのセグメントに付加される詳細情報として出力されます。次のフィールドに,フィールドの値としてメタデータの値を出力します。/はフィールド階層の区切りを表します。 Segments/Document/metadata/default/<メタデータのキー名> |
上記以外のトレース取得ポイント |
AWS X-Rayのセグメントに付加される詳細情報として出力されます。次のフィールドに,フィールドの値としてメタデータの値を出力します。/はフィールド階層の区切りを表します。 Segments/Document/<"subsegments/"をSegmentsに対応するSpanからのネスト分だけ繰り返し>metadata/default/<メタデータのキー名> |
- 次の条件を両方満たす場合,HMP-ADIFへ送信対象となる本製品のトレース取得ポイントのASCII項目に分散トレーシングのTraceIDおよびSpanIDに相当する情報を出力します。
-
-
tracer.hmp-adif.send-trace-as-span.enabledプロパティの指定値がtrueである
-
HMP-ADIFで1つ以上の分散トレース管理基盤が利用できる
-
これによって,トレースログに出力されたトレース情報と,分散トレーシングで可視化されたトレース情報の紐づけが容易にでき,可読性が向上します。
TraceIDに相当する情報とは,トレース管理基盤が定義するリクエストごとに一意のIDです。SpanIDに相当する情報とは,トレース管理基盤が定義するSpanごとに一意のIDです。
TraceIDおよびSpanIDに相当する情報はトレース管理基盤ごとに異なるため,詳細はHMP-ADIFの取扱説明書を参照してください。
トレース情報のASCII項目に次のフォーマットでTraceIDおよびSpanIDに相当する情報を追加し,トレースログに出力します。
"<TraceIDに相当する情報のキー1>:<TraceIDに相当する情報の値1>,<TraceIDに相当する情報のキー2>:<TraceIDに相当する情報の値2>, (TraceIDに相当する情報が存在する分だけ繰り返し), <SpanIDに相当する情報のキー1>:<SpanIDに相当する情報の値1>,<SpanIDに相当する情報のキー2>:<SpanIDに相当する情報の値2>,(SpanIDに相当する情報が存在する分だけ繰り返し)"
次の詳細はHMP-ADIFの取扱説明書を参照してください。
-
<TraceIDに相当する情報のキー>
-
<TraceIDに相当する情報の値>
-
<SpanIDに相当する情報のキー>
-
<SpanIDに相当する情報の値>