9.2.4　取得方針

(a)　取得個所方針

HMP-PCTOではSpanを一般的な取得個所と、製品保守観点での取得個所で取得します。

一般的な取得個所でのSpanと、製品保守観点での取得個所でのSpanを、Spanに付与するオペレーション名で区別できます。オペレーション名は、各コンポーネント内の特定処理（オペレーション）を特定するため、製品のJavaクラス名やメソッド名などを組み合わせた文字列です。一般的な取得個所のSpanは、オペレーション名冒頭に「Recv」を付与します。なお、ここで示す図はSQL-Participantを使用する場合です。TCC-Participantを使用する場合、Entity-ServiceをEntity-Moduleと読み替えてください。

一般的な取得個所

分散トレースは一般的に、マイクロサービス間の情報を把握するために1回のサービス呼び出しで1Span取得します。HMP-PCTOでも、各コンポーネントでの処理開始時の上位処理でSpanを取得します。上位処理から呼び出す下位処理では別途Spanは取得しません。例外として、「製品保守観点での取得個所」に示す個所でSpanを取得します。

図9‒12　取得イメージ図

製品保守観点での取得個所

一般的なSpanの取得個所で情報を取得できない処理について、製品処理の調査のため別途Spanを取得します。

上位処理とは非同期に処理を実行する場合

タイマ処理など、他コンポーネントから要求の延長で実施した処理から登録し、別スレッドで実施する処理があります。これらの処理は登録元の処理が完了しても処理は続行するため、処理の終了時などの情報を、登録元のSpanへ登録できません。

そのため、コンポーネント内処理に応じて、次のどれかで取得します。

• 処理途中および終了時の情報を取得する場合（他コンポーネントや他製品と連携する場合など）

  登録元処理のSpanを親Spanとした新たなSpanを作成します。

• 起動時の情報だけを取得する場合（処理途中、終了時情報が不要の場合）

  登録元処理のSpanに、情報を付加します。

  図9‒13　例1タイマ処理

電文送信処理

HMP-PCTOでは、複数の通信相手へ複数スレッドで同時送信する処理があります（OrchestratorからMediatorへのトランザクション決着要求など）。送信先の情報だけでは、ネットワーク遅延などが起きた場合に原因調査が難しいため、送信元での電文送受信時の情報（宛先、送受信時刻など）を取得したいため、送信先数分の情報取得が必要です。それらを1つのSpanで管理すると、宛先ごとの情報の確認がしづらくなります。そのため、送信先ごとに子Spanを取得し、送信先ごとの情報を子Spanで取得します。

図9‒14　通信処理

(b)　取得する付加情報方針

HMP-PCTOが取得する付加情報について説明します。

次の観点で付加情報を取得します。

• 他トラブルシュート情報との紐づけ情報（ルートXID/ブランチXIDなど）

• 対象処理がどこで実施した処理かの識別情報（ホスト名、スレッド名など）

• 通信先の情報（送信先のIPアドレス、ポート番号など）

• 通信データ（他コンポーネントへの指示内容（Commit/rollback要求）など）

• 対象処理の結果（commit/rollbackなど）

• 実行時間情報（ユーザアプリ、ファイルI/Oなど開始終了時間など）

付加する情報の一覧を次に示します。

コンポーネント共通

HMP-PCTOのコンポーネントが、共通でSpanに付加する情報の一覧を次に示します。

• Tags

  表9‒6　コンポーネント共通の付加情報（Tags）

  項番	情報名	設定する情報値の説明
  1	root-xid	ルートXIDをbase64エンコードした値を設定します。 ルートXIDとブランチXIDのうち、ルートXIDを使用する処理の場合に設定します。
  2	branch-xid	ブランチXIDをbase64エンコードした値を設定します。 ルートXIDとブランチXIDのうち、ブランチXIDを使用する処理の場合に設定します。
  3	thread-name	スレッド名を設定します。
  4	host-name	自ホストのホスト名を設定します。 ホスト名の取得に失敗した場合は「localhost」を設定します。

• Logs

  表9‒7　コンポーネント共通の付加情報（Logs）

  項番	情報説明名	意味	追加情報名	設定する情報値の説明
  1	start:operation	Spanで取得する処理が開始したことを意味します。 親処理と異なるスレッドで実行する処理で、スレッド割り当てなどが完了し、実際の処理開始時に取得します。	情報なし	−
  2	End:operation	Spanで取得する処理の終了を意味します。	情報なし	−

  （凡例）−：該当しません。

REST通信

コンポーネント共通の情報に加えて、REST通信を実施する際にSpanに付加する情報の一覧を次に示します。

• Tags

  表9‒8　REST通信の付加情報（Tags）

  項番	項目名	説明
  1	http-method	リクエストのHTTPメソッド。 例：POST、GETなど
  2	http-url	リクエストのURL。
  3	http-status-code	レスポンスのHTTPステータスコード 通信障害でレスポンスが受信できなかった場合、この項目は設定されません。

• Logs

  表9‒9　REST通信の付加情報（Logs）

  項番	情報説明名	意味	追加情報名	設定する情報値の説明
  1	start:rest	REST通信の開始（リクエストの送信）を意味します。	情報なし	−
  2	end:rest	REST通信の終了（レスポンスの受信）を意味します。	情報なし	−

  （凡例）−：該当しません。

gRPC通信

コンポーネント共通の情報に加えて、gRPC通信を実施する際にSpanに付加する情報の一覧を次に示します。

• Tags

  表9‒10　gRPC通信の付加情報（Tags）

  項番	項目名	説明
  1	previous-rpc-attempts	grpc送信の再試行時に設定します。 前回のgrpc試行回数を設定します。
  2	transparent-retry	grpc送信の再試行時に設定します。 Transparent retryかどうか true transparent retry false transparent retryではない
  3	local-address	ローカルのIPアドレスとgrpcポート番号の組み合わせです。 次の形式で設定します。 IPアドレス:grpcポート番号
  4	remote-address	リモートのIPアドレスとgrpcポート番号の組み合わせです。 次の形式で設定します。 IPアドレス:grpcポート番号

• Logs

  表9‒11　gRPC通信の付加情報（Logs）

  項番	項目名	説明	追加情報名	設定する情報値の説明
  1	sent message	gRPCのメッセージ送信が行われたことを意味します。	compressed_size	圧縮した電文サイズ。 この値が0の時、非圧縮電文サイズと同値です。
  2			uncompressed_size	非圧縮の電文サイズ。 この値が0の時、圧縮電文サイズと同値です。
  3			id	0固定。
  4	sent message(hmppcto)		json-convert	JSON形式の出力か、protobuf形式での出力か。のステータスを表します。 true: JSON形式 false: protobuf形式
  5			message-value	電文内容。 電文の先頭から256文字の情報を表示します。 256文字を超過する電文内容の場合、超過した部分は、分散トレースに登録しません。 また、電文内容がすべて出力されていないことを表すため、分散トレースに登録される電文内容の終端3文字を"…"へと置換します。
  6	received message	gRPCのメッセージ受信が行われたことを意味します。	compressed_size	圧縮した電文サイズ。 この値が0の時、非圧縮電文サイズと同値です。
  7			uncompressed_size	非圧縮の電文サイズ。 この値が0の時、圧縮電文サイズと同値です。
  8			id	0固定。
  9	received message(hmppcto)		json-convert	JSON形式の出力か、protobuf形式での出力か。のステータスを表します。 true: JSON形式 false: protobuf形式
  10			message-value	電文内容。 電文の先頭から256文字の情報を表示します。 256文字を超過する電文内容の場合、超過した部分は、分散トレースに登録しません。 また、電文内容がすべて出力されていないことを表すため、分散トレースに登録される電文内容の終端3文字を"…"へと置換します。

Orchestrator

コンポーネント共通の情報に加えて、OrchestratorがSpanに付加する情報の一覧を次に示します。

• Tags

  表9‒12　Orchestratorの付加情報（Tags）

  項番	情報名	設定する情報値の説明
  1	result	グローバルトランザクション決着結果 Commit コミット Rollback ロールバック Failure トランザクション決着失敗

• Logs

  表9‒13　Orchestratorの付加情報（Logs）

  項番	情報説明名	意味	追加情報名	設定する情報値の説明
  1	start:service	Orchestratorのアプリケーション開始を意味します。	情報なし	−
  2	end:service	Orchestratorのアプリケーション終了を意味します。	情報なし	−

  （凡例）−：該当しません。

Entity-ServiceまたはEntity-Module

コンポーネント共通の情報に加えて、Entity-ServiceまたはEntity-ModuleがSpanに付加する情報の一覧を次に示します。

• Tags

  表9‒14　Entity-ServiceまたはEntity-Moduleの付加情報（Tags）

  項番	情報名	設定する情報値の説明
  1	result	Orchestratorへのトランザクション結果 Commit コミット Rollback ロールバック
  2	prepare	先行prepareの実施有無 Y 実行 N 未実行

• Logs

  表9‒15　Entity-ServiceまたはEntity-Moduleの付加情報（Logs）

  項番	情報説明名	意味	追加情報名	設定する情報値の説明
  1	start:service	Entity-ServiceまたはEntity-Moduleのアプリケーション開始を意味します。	情報なし	−
  2	end:service	Entity-ServiceまたはEntity-Moduleのアプリケーション終了を意味します。	情報なし	−

  （凡例）−：該当しません。

SQL-Participant

コンポーネント共通の情報に加えて、SQL-ParticipantでSpanに付加する情報の一覧を次に示します。

• Tags

  表9‒16　SQL-Participantの付加情報（Tags）

  項番	情報名	設定する情報値の説明
  1	consensus-value	分散合意結果 Commit コミット Rollback ロールバック
  2	external-consensus	補助合意実施有無 Y 補助合意実施 N 補助合意未実施

• Logs

  表9‒17　SQL-Participantの付加情報（Logs）

  項番	情報説明名	意味	追加情報名	設定する情報値の説明
  1	learning log size m/n	LearningLog（Mediatorから受信した合意）の数、m:受信数、n:Mediator数です。	情報なし	−
  2	fast consensus	高速合意を実施を意味します。	情報なし	−
  3	skip consensus	分散合意条件を満たせないため、分散合意をスキップしたことを意味します。	情報なし	−
  4	external consensus	補助合意を実施を意味します。	情報なし	−
  5	consensus finnished	タイムアウト前に分散合意が完了していたことを意味します。	情報なし	−
  6	start:jdbc	ParticipantでのJDBCメソッド開始を意味します。	情報なし	−
  7	end:jdbc	ParticipantでのJDBCメソッド終了を意味します。	情報なし	−

  （凡例）−：該当しません。

TCC-Participant

コンポーネント共通の情報に加えて、TCC-ParticipantでSpanに付加する情報の一覧を次に示します。

• Tags

  表9‒18　TCC-Participantの付加情報（Tags）

  項番	情報名	設定する情報値の説明
  1	consensus-value	分散合意結果 Commit コミット Rollback ロールバック
  2	external-consensus	補助合意実施有無 Y 補助合意実施 N 補助合意未実施

• Logs

  表9‒19　TCC-Participantの付加情報（Logs）

  項番	情報説明名	意味	追加情報名	設定する情報値の説明
  1	learning log size m/n	LearningLog（Mediatorから受信した合意）の数、m:受信数、n:Mediator数です。	情報なし	−
  2	fast consensus	高速合意を実施を意味します。	情報なし	−
  3	skip consensus	分散合意条件を満たせないため、分散合意をスキップしたことを意味します。	情報なし	−
  4	external consensus	補助合意を実施を意味します。	情報なし	−
  5	consensus finnished	タイムアウト前に分散合意が完了していたことを意味します。	情報なし	−
  6	start:try	Try開始を意味します。	情報なし	−
  7	end:try	Try終了を意味します。	情報なし	−
  8	start:confirm	confirm開始を意味します。	情報なし	−
  9	end:confirm	confirm終了を意味します。	情報なし	−
  10	start:cancel	cancel開始を意味します。	情報なし	−
  11	end:cancel	cancel終了を意味します。	情報なし	−

  （凡例）−：該当しません。

Mediator

コンポーネント共通の情報に加えて、MediatorがSpanに付加する情報の一覧を次に示します。

• Tags

  表9‒20　Mediatorの付加情報（Logs）

  項番	情報名	設定する情報値の説明
  1	consensus-value	Participantでの分散合意結果 Commit コミット Rollback ロールバック
  2	consensus-id	ConsensusIdの値を設定します。

• Logs

  表9‒21　Mediatorの付加情報（Logs）

  項番	情報説明名	意味	追加情報名	設定する情報値の説明
  1	start:consensuslog	ConsensusLogへのアクセス(I/O)開始を意味します。	情報なし	−
  2	end:consensuslog	ConsensusLogへのアクセス(I/O)終了を意味します。	情報なし	−
  3	start:proposallog-add-propose	Proposal Logへのアクセス（投票内容保存）の開始を意味します。	propose-values	Proposal Logに保存した投票内容の一覧を設定します。 COMMIT_VOTE Commit投票 ROLLBACK_VOTE Rollback投票 一覧は上記の値を","（コンマ）区切りで設定します。
  4	end:proposallog-add-propose	Proposal Logへのアクセス（投票内容保存）の終了を意味します。	情報なし	−
  5	start:proposallog-add-propose-participant	Proposal Logへのアクセス（投票を受信したParticipant情報保存）の開始を意味します。	participants-value	Proposal Logに保存した投票を受信したParticipant情報（<Service名>.<ネームスペース名>）の一覧を設定します。 一覧は<Service名>.<ネームスペース名>を","（コンマ）区切りで設定します。
  6	end:proposallog-add-propose-participant	Proposal Logへのアクセス（投票を受信したParticipant情報保存）の終了を意味します。	情報なし	−
  7	start:proposallog-add-all-participants	Proposal Logへのアクセス（トランザクションに参加したParticipant情報（<Service名>.<ネームスペース名>））の一覧の保存の開始を意味します。	all-participants	Proposal Logに保存されたトランザクションに参加したParticipant情報（<Service名>.<ネームスペース名>）の一覧を設定します。 一覧は<Service名>.<ネームスペース名>を","（コンマ）区切りで設定します。
  8	end:proposallog-add-all-participants	Proposal Logへのアクセス（トランザクションに参加したParticipant情報（<Service名>.<ネームスペース名>））の一覧の保存の終了を意味します。	情報なし	−

  （凡例）−：該当しません。

(c)　情報を取得するSpanの方針

付加情報をどのSpanで取得するかについて説明します。

Spanに付加する情報は、全Span共通で付加するわけではなく、他コンポーネントから伝達された情報（ブランチXIDなど）やプロセスに関わる情報（ホスト名）などは、他コンポーネントから呼び出された先頭処理（主に受信処理）のSpanで取得します。先頭処理から生成/呼び出した処理は、先頭Spanと差異のある情報（スレッド名など）を取得します。次に示す図はSQL-Participantを使用する場合です。TCC-Participantを使用する場合、Entity-ServiceをEntity-Moduleと読み替えてください。

図9‒15　取得する情報

(a)　取得個所

EADS APIのcreateおよびget向けにParticipantから補助合意のためにEADS APIを呼び出す時にSpanを取得します。

(b)　取得する情報

コンポーネント共通の情報に加えて、EADS API向けのSpanで取得する情報を次に示します。

• Tags

  なし。

• Logs

  表9‒22　EADSの付加情報（Logs）

  項番	情報説明名	意味	追加情報名	設定する情報値の説明
  1	start:EADS API	EADSのAPIの呼び出しが行われたことを意味します。	API-name	呼び出すEADS API名 create createのEADS API get getのEADS API
  2			consensus	補助合意提案値。createの場合だけ出力する。 Commit コミット Rollback ロールバック
  3	end:EADS API	EADSのAPIの実行が終わったことを意味します。	API-name	実行が終わったEADS API名 create createのEADS API get getのEADS API
  4			ret	取得した補助合意提案値。getの場合だけ出力する。 Commit コミット Rollback ロールバック
  5	failed:EADS API	EADSのAPIの実行中に例外が発生したことを意味します。	API name	例外が発生したEADS API名 create createのEADS API get getのEADS API
  6			message	例外の詳細メッセージ文字列

(a)　取得個所

1. Participantで、Entity-ServiceからgRPC通信に初回のSQL実行が要求された時にSpanを取得します。

2. Participant初期化で、prepare済みのトランザクションを取得する時にSpanを取得します。

3. Participantで、CommitもしくはRollbackの通知のgRPC通信を受信した時のSpanにLogを追加します。

(b)　取得する情報

コンポーネント共通の情報に加えて、XA関数向けのSpanで取得する情報を次に示します。

• Tags

  なし。

• Logs

  表9‒23　XA関数の付加情報（Logs）

  項番	情報説明名	意味	追加情報名	設定する情報値の説明
  1	start: xa function	XA関数の呼び出しが行われたことを意味します。	xa-name	呼び出すXA関数名 xa_start xa_start関数 xa_end xa_end関数 xa_prepare xa_prepare関数 xa_commit xa_commit関数 xa_rollback xa_rollback関数 xa_recover xa_recover関数
  2	end: xa function	XA関数の実行が終わったことを意味します。	xa-name	実行が終わったXA関数名 xa_start xa_start関数 xa_end xa_end関数 xa_prepare xa_prepare関数 xa_commit xa_commit関数 xa_rollback xa_rollback関数 xa_recover xa_recover関数
  3	failed:xa function	XA関数の実行中に例外が発生したことを意味します。	xa-name	例外が発生したXA関数名 xa_start xa_start関数 xa_end xa_end関数 xa_prepare xa_prepare関数 xa_commit xa_commit関数 xa_rollback xa_rollback関数 xa_recover xa_recover関数
  4			message	例外の詳細メッセージ文字列