Hitachi

uCosminexus Application Runtime for Spring Boot ユーザーズガイド

付録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の取扱説明書を参照してください。

図D‒2　本製品と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に送信」を参照してください。

表D‒1　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内の処理で例外またはエラーが発生した場合：1

  • 上記以外の場合：0

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内の処理で例外またはエラーが発生した場合：1

  • 上記以外の場合：0

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内の処理で例外またはエラーが発生した場合：1

  • 上記以外の場合：0

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に送信するには，ログ取得レベルを次のどれかに設定してください。

また，次のトレースはHMP-ADIFに送信しません。

HMP-ADIFのトレース情報はSpanとして抽象化されています。SpanはHMP-ADIFのトレースの単位であり，ネストにできます。HMP-ADIFは本製品のSpanを親Spanとして，ハンドラのSpanを生成します。そのあとHMP-ADIFは仕様に従い，子Spanを生成します。本製品はHMP-ADIFが生成したSpanを親Spanとして，HMP-ADIFのハンドラに呼び出された処理のSpanを生成します。Spanの親子関係のイメージを次に示します。

図D‒4　Spanの親子関係のイメージ

[図データ]

トレース情報をHMP-ADIFに送信する場合のSpanの名前を次の表に示します。

表D‒3　トレース情報をHMP-ADIFに送信する場合のSpanの名前

送信するケース

Spanの名前

名前の例

トレース情報をHMP-ADIFに送信する場合

ucartrace：＜Spanの開始に対応するトレース取得ポイントのイベントID＞

ucartrace：0xe230

トレース情報をHMP-ADIFに送信する場合，次に示すトレース情報の内容が，1つのSpanのメタデータとして含まれます。

ただし，トレース情報の項目に情報がない場合，対応するSpanのメタデータは付与しません。

Spanのメタデータは，キーバリュー形式です。Spanのメタデータのキー名は次の規則で決定されます。

"ucar.<タイミング>.<トレース情報の項目を示す文字列>"

＜タイミング＞は，Spanの開始に対応するトレース情報の場合は“start”，Spanの終了に対応するトレース情報の場合は“finish”となります。＜トレース情報の項目を示す文字列＞は，メタデータが含むトレース情報の項目によって異なります。トレース情報の項目およびタイミングと，メタデータのキー名の対応は「表D-4　トレース情報の項目およびタイミングとメタデータのキー名の対応」を参照してください。

メタデータの値の形式は，トレースログに出力される形式と同一です。ただし，トレースログに""で囲んで出力される項目の出力内容は，""で囲まれない形式でメタデータの値に設定されます。

トレース情報の項目およびタイミングと，メタデータのキー名の対応は，次のとおりです。

表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の取扱説明書を参照してください。

メタデータの出力形式はトレース管理基盤およびトレース取得ポイントによって異なり，次の形式で出力します。

表D‒5　メタデータの出力形式

トレース

管理基盤

トレース取得ポイント

メタデータの出力形式

Jaeger

すべてのトレース取得ポイント

Jaegerのタグとして出力されます。タグのキーとタグの値が，メタデータのキー名とメタデータの値に一致するように出力します。

AWS X-Ray

  • HTTPリクエストを受信した直後(0xe230)

  • HTTPレスポンスを送信する直前(0xe231)

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で１つ以上の分散トレース管理基盤が利用できる

これによって，トレースログに出力されたトレース情報と，分散トレーシングで可視化されたトレース情報の紐づけが容易にでき，可読性が向上します。

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の取扱説明書を参照してください。

ページの先頭へ

All Rights Reserved. Copyright (C) 2023, 2024, Hitachi, Ltd.