10.3.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を取得します。

図10‒17　取得イメージ図

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

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

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

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

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

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

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

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

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

  図10‒18　例1タイマ処理

電文送信処理

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

図10‒19　通信処理

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

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

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

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

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

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

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

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

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

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

コンポーネント共通

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

• Tags

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

  項番	情報名	設定する情報値の説明
  1	root-xid	ルートXIDをbase64エンコードした値を設定します。 ルートXIDとブランチXIDのうち、ルートXIDを使用する処理の場合に設定します。
  2	branch-xid	ブランチXIDをbase64エンコードした値を設定します。 ルートXIDとブランチXIDのうち、ブランチXIDを使用する処理の場合に設定します。
  3	thread-name	スレッド名を設定します。
  4	otel.library.name	Spanが取得されたライブラリの名称を設定します。 HMP-PCTOのライブラリで取得されたSpanの場合、「HMP-PCTO」が設定されます。
  5	otel.library.version	Spanが取得されたライブラリのバージョンを設定します。

• Logs

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

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

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

• Process

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

  項番	情報名	設定する情報値の説明
  1	hostname	コンポーネントのホスト名を設定します。
  2	ip	コンポーネントのIPアドレスを設定します。
  3	jaeger.version	HMP-PCTOが使用しているOpenTelemetryのライブラリを設定します。 「opentelemetry-java」が設定されます。
  4	otel.library.name	Spanが取得されたライブラリの名称を設定します。 HMP-PCTOのライブラリで取得されたSpanの場合、「HMP-PCTO」が設定されます。
  5	otel.library.version	Spanが取得されたライブラリのバージョンを設定します。
  6	service.name	HMP-PCTOのjp.co.Hitachi.soft.hmppcto.tracing.instance-idパラメタに設定した値が設定されます。
  7	telemetry.sdk.language	HMP-PCTOが使用しているOpenTelemetryのライブラリの言語を設定します。 「java」が設定されます。
  8	telemetry.sdk.name	HMP-PCTOが使用しているOpenTelemetryのライブラリの名称を設定します。 「opentelemetry」が設定されます。
  9	telemetry.sdk.version	HMP-PCTOが使用しているOpenTelemetryのバージョンを設定します。 HMP-PCTO 01-01では、「1.38.0」が設定されます。

REST通信

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

• Tags

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

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

• Logs

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

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

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

• Process

  付加情報はありません。

gRPC通信

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

• Tags

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

  項番	項目名	説明
  1	network.peer.address	ネットワーク接続先のIPアドレスを設定します。
  2	network.peer.port	ネットワーク接続先のポート番号を設定します。
  3	network.type	ネットワークの種別を設定します。 「ipv4」を設定します。
  4	rpc.grpc.status_code	gRPCのステータスコードを設定します。
  5	rpc.method	gRPCのメソッドを設定します。
  6	rpc.service	gRPCのサービスを設定します。
  7	rpc.system	RPCの種別を設定します。 「grpc」が設定されます。
  8	server.address	gRPCサーバのIPアドレスまたはホスト名を設定します。
  9	server.port	gRPCサーバのポート番号を設定します。
  10	span.kind	Span種別を設定します。 gRPCサーバの場合：「server」が設定されます。 gRPCクライアントの場合：「client」が設定されます。
  11	otel.scope.name	Spanが取得されたライブラリの名称を設定します。 「io.opentelemetry.grpc-1.6」が設定されます。
  12	otel.scope.version	Spanが取得されたライブラリのバージョンを設定します。

• Logs

  表10‒13　gRPC通信の付加情報（Logs）

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

• Process

  付加情報はありません。

Orchestrator

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

• Tags

  表10‒14　Orchestratorの付加情報（Tags）

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

• Logs

  表10‒15　Orchestratorの付加情報（Logs）

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

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

• Process

  付加情報はありません。

Entity-ServiceまたはEntity-Module

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

• Tags

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

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

• Logs

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

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

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

• Process

  付加情報はありません。

SQL-Participant

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

• Tags

  表10‒18　SQL-Participantの付加情報（Tags）

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

• Logs

  表10‒19　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 finished	タイムアウト前に分散合意が完了していたことを意味します。	情報なし	−
  6	start:jdbc	ParticipantでのJDBCメソッド開始を意味します。	情報なし	−
  7	end:jdbc	ParticipantでのJDBCメソッド終了を意味します。	情報なし	−

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

• Process

  付加情報はありません。

TCC-Participant

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

• Tags

  表10‒20　TCC-Participantの付加情報（Tags）

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

• Logs

  表10‒21　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 finished	タイムアウト前に分散合意が完了していたことを意味します。	情報なし	−
  6	start:try	Try開始を意味します。	情報なし	−
  7	end:try	Try終了を意味します。	情報なし	−
  8	start:confirm	confirm開始を意味します。	情報なし	−
  9	end:confirm	confirm終了を意味します。	情報なし	−
  10	start:cancel	cancel開始を意味します。	情報なし	−
  11	end:cancel	cancel終了を意味します。	情報なし	−

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

• Process

  付加情報はありません。

TP1-Bridge

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

• Tags

  表10‒22　TP1-Bridgeの付加情報（Tags）

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

• Logs

  表10‒23　TP1-Bridgeの付加情報（Logs）

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

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

• Process

  付加情報はありません。

Mediator

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

• Tags

  表10‒24　Mediatorの付加情報（Logs）

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

• Logs

  表10‒25　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名>.<ネームスペース名>））の一覧の保存の終了を意味します。	情報なし	−

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

• Process

  付加情報はありません。

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

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

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

図10‒20　取得する情報

(a)　取得個所

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

(b)　取得する情報

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

• Tags

  なし。

• Logs

  表10‒26　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

  表10‒27　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	例外の詳細メッセージ文字列