Yoshi Yamaguchi

この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/dotnet/dotnet-network-traces/

翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）

.NETが発行するネットワークスパンに関するセマンティック規約

ステータス: Mixed

この記事では、.NETが発行するHTTPクライアント、DNS、TLSのスパンに関するセマンティック規約を定義します。

.NETのHttpClientは、HTTPセマンティック規約に従って、HTTPクライアントリクエストスパンを報告します。

安定版のHTTPクライアントリクエストスパンに加えて、HTTPクライアントハンドラーは、HTTP接続の確立とそのステージを記述する実験的なスパンを報告します。

接続の寿命は通常分単位で計測されるため、アプリケーションに負荷がかかっていても接続プールに過負荷がかかっていない場合、接続関連のスパンの発生率はHTTPクライアントリクエストスパンの発生率よりもかなり低くなることが予想されます。

アプリケーションは、本番環境でHTTPクライアントリクエストスパンをデフォルトで有効にすることが推奨されます。

接続レベルのスパンは実験的であり、将来的にその意味が破壊的に変更される可能性があります。 本番環境で接続レベルの計装を使用する場合は、適切な検証を行った上で実施すべきです。

接続関連のスパンは、特定のプラットフォームではサポートされていない場合や、特定のアプリケーションで使用されない場合があるHttpClientHandlerとSocketsHttpHandlerによってのみ報告されます。

HTTPクライアントリクエスト

ステータス: Stable

.NETのHttpClientは、次の固有の詳細を伴って、HTTPクライアントセマンティック規約に従ってクライアントリクエストスパンを報告します。

  • network.protocol.name属性、network.peer.port属性、http.request.resend_count属性は報告されません。
  • url.fullはデフォルトでリダクトされます。クエリパラメータの値は*に置き換えられます。このリダクトは、AppContextスイッチSystem.Net.Http.DisableQueryRedactionをtrueに設定することで無効にできます。
  • error.type属性が報告される場合、それにはHTTP Request errorsのいずれかをsnake_caseにしたもの、完全な例外型名、または受信したステータスコードの文字列表現が含まれます。
  • すべての属性は、Activityが開始された後に報告され、作成時に提供される属性はありません。
  • リダイレクトが発生した場合、リダイレクトされた各リクエストは別々のスパンとして報告されます。
  • SocketsHttpHandlerは、接続に失敗した際にリクエストを再試行することがあります。このような再試行は、別々のスパンとして報告されません。

対応するActivity.OperationNameはSystem.Net.Http.HttpRequestOut、ActivitySource名はSystem.Net.Httpです。 HTTPセマンティクスを持つスパンは.NET 9で追加されました。

HTTPクライアントリクエストの接続待機

Status: Development

このスパンは、HTTPリクエストが接続プールから接続を取得するまでの時間を記述します。

このスパンは、リクエストが開始された時点で接続がすぐに利用可能でなかった場合にのみ報告されます。 これはHTTPクライアントリクエストスパンの子として報告されます。

このスパンは、接続が取得された時点で終了します。これは、既存の接続が利用可能になった時点、または新しい接続が確立された時点で発生する可能性があるため、接続待機スパンの持続時間は、HTTP接続のセットアップスパンの持続時間とは異なります。

プールから接続を取得するまでの時間は、http.client.request.time_in_queueメトリクスによっても報告されます。

対応するActivity.OperationNameはExperimental.System.Net.Http.Connections.WaitForConnection、ActivitySource名はExperimental.System.Net.Httpです。 .NET 9で追加されました。

スパン名はHTTP wait_for_connection {server.address}:{server.port}であるべきです（SHOULD）。

スパン種別はINTERNALであるべきです（SHOULD）。

スパンステータスはエラーの記録文書に従うべきです（SHOULD）。

Attributes:

KeyStabilityRequirement LevelValue TypeDescriptionExample Values
error.typeStableConditionally Required if and only if an error has occurred.stringHTTP Request errorsのいずれかをsnake_caseにしたもの、または完全な例外型。version_negotiation_error; System.OperationCanceledException

error.typeには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

ValueDescriptionStability
_OTHER計装が独自の値を定義していない場合に使用するフォールバック用のエラー値。Stable

HTTP接続のセットアップ

Status: Development

このスパンは、HTTP接続の確立を記述します。これには、DNSの解決、ソケット接続の確立、TLSハンドシェイクの実行にかかる時間が含まれます。

HTTPクライアントリクエストスパンとHTTP接続のセットアップスパンの間に、親子関係はありません。 後者は常にルートスパンとなり、別のトレースを定義します。

しかし、HTTP接続のセットアップスパンが表す接続の試行がHTTP接続の確立に成功し、その接続がそれを処理するリクエストによって取得された場合、計装はHTTPクライアントリクエストスパンに、そのHTTP接続セットアップスパンを指すリンクを追加します。 つまり、各リクエストは、そのリクエストを処理した接続にリンクされます。

対応するActivity.OperationNameはExperimental.System.Net.Http.Connections.ConnectionSetup、ActivitySource名はExperimental.System.Net.Http.Connectionsです。 .NET 9で追加されました。

スパン名はHTTP connection_setup {server.address}:{server.port}であるべきです（SHOULD）。

スパン種別はINTERNALであるべきです（SHOULD）。

スパンステータスはエラーの記録文書に従うべきです（SHOULD）。

Attributes:

KeyStabilityRequirement LevelValue TypeDescriptionExample Values
error.typeStableConditionally Required if and only if an error has occurred.stringHTTP Request errorsのいずれかをsnake_caseにしたもの、または完全な例外型。name_resolution_error; System.OperationCanceledException
network.peer.addressStableRecommendedstringソケット接続のピアIPアドレス。[1]10.1.2.80; /tmp/my.sock
server.addressStableRecommendedstring逆引きDNSルックアップなしで利用可能な場合のサーバーのドメイン名。そうでない場合はIPアドレスまたはUNIXドメインソケット名。[2]example.com; 10.1.2.80; /tmp/my.sock
server.portStableRecommendedintサーバーのポート番号。[3]80; 8080; 443
url.schemeStableRecommendedstring使用されているプロトコルを識別するURIスキームの構成要素。https; ftp; telnet

[1] network.peer.address: network.peer.address属性は、接続が正常に確立された場合、かつIPソケットの場合にのみ利用可能です。

[2] server.address: クライアント側から観測し、かつ中間サーバーを介して通信している場合、server.addressは、（利用可能であれば）プロキシなどの中間サーバーの背後にあるサーバーのアドレスを表すべきです（SHOULD）。

[3] server.port: クライアント側から観測し、かつ中間サーバーを介して通信している場合、server.portは、（利用可能であれば）プロキシなどの中間サーバーの背後にあるサーバーのポートを表すべきです（SHOULD）。

error.typeには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

ValueDescriptionStability
_OTHER計装が独自の値を定義していない場合に使用するフォールバック用のエラー値。Stable

DNSルックアップ

Status: Development

このスパンは、System.Net.Dnsクラスのいずれかのメソッドで実行される、DNSルックアップまたは逆引きルックアップを記述します。

DNSスパンは、物理的なDNS呼び出しではなく論理的な操作を追跡し、実際の挙動はリゾルバーの実装に依存します。この実装は、今後の.NETのバージョンで変更される可能性があります。 .NET 9はOSのDNSリゾルバーを使用しており、1回のAPI呼び出しに対して0回以上の物理的なルックアップを行う場合があります。

DNSルックアップスパンがHTTP接続のセットアップスパンおよびソケット接続スパンとともに報告される場合、DNSルックアップスパンはHTTP接続のセットアップの子となり、ソケット接続の兄弟となります。

DNSルックアップの持続時間は、dns.lookup.durationメトリクスによっても報告されます。

対応するActivity.OperationNameはExperimental.System.Net.NameResolution.DnsLookup、ActivitySource名はExperimental.System.Net.NameResolutionです。 .NET 9で追加されました。

スパン名は、DNSルックアップ（ホスト名からIPアドレス）の場合はDNS lookup {dns.question.name}、逆引きルックアップ（IPアドレスからホスト名）の場合はDNS reverse lookup {dns.question.name}であるべきです（SHOULD）。

スパン種別はINTERNALであるべきです（SHOULD）。

スパンステータスはエラーの記録文書に従うべきです（SHOULD）。

Attributes:

KeyStabilityRequirement LevelValue TypeDescriptionExample Values
error.typeStableConditionally Required if and only if an error has occurred.stringSystem.Net.Dnsが返すエラーコードまたは例外名。[1]host_not_found; try_again
dns.answersDevelopmentRecommended if DNS lookup was successful.string[]（DNSルックアップの場合）解決されたIPアドレスの一覧、または（逆引きルックアップの場合）ドメイン名を含む単一の要素。["10.0.0.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"]
dns.question.nameDevelopmentRecommendedstringクエリの対象となるドメイン名またはIPアドレス。www.example.com; opentelemetry.io

[1] error.type: 次のエラーが報告されます。

  • host_not_found
  • try_again
  • no_recovery
  • address_family_not_supported
  • 完全な例外型名

詳細はSocketErrorを参照してください。

error.typeには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

ValueDescriptionStability
_OTHER計装が独自の値を定義していない場合に使用するフォールバック用のエラー値。Stable

ソケット接続

Status: Development

このスパンは、ソケット接続の確立を記述します。

これは、DNSルックアップとTLSハンドシェイクも対象とするHTTP接続のセットアップスパンとは異なります。

ソケット接続スパンがHTTP接続のセットアップスパンとともに報告される場合、ソケットのスパンはHTTP接続のセットアップの子となります。

対応するActivity.OperationNameはExperimental.System.Net.Sockets.Connect、ActivitySource名はExperimental.System.Net.Socketsです。 .NET 9で追加されました。

スパン名は、ソケットのアドレスファミリーがポートの概念を持つ場合はsocket connect {network.peer.address}:{network.peer.port}、そうでない場合はsocket connect {network.peer.address}であるべきです（SHOULD）。

スパン種別はINTERNALであるべきです（SHOULD）。

スパンステータスはエラーの記録文書に従うべきです（SHOULD）。

Attributes:

KeyStabilityRequirement LevelValue TypeDescriptionExample Values
error.typeStableConditionally Required if and only if an error has occurred.stringソケットのエラーコード。[1]connection_refused; address_not_available
network.peer.addressStableRecommendedstringネットワーク接続のピアアドレス（IPアドレスまたはUNIXドメインソケット名）。10.1.2.80; /tmp/my.sock
network.peer.portStableRecommended [2]intネットワーク接続のピアのポート番号。65123
network.transportStableRecommended [3]stringOSIトランスポート層またはプロセス間通信の方式。[4]tcp; udp; unix
network.typeStableRecommended if network.peer.address is an IP address.stringOSIネットワーク層、または非OSIの同等の概念。[5]ipv4; ipv6

[1] error.type: 次のエラーコードが報告されます。

  • network_down
  • address_already_in_use
  • interrupted
  • in_progress
  • already_in_progress
  • address_not_available
  • address_family_not_supported
  • connection_refused
  • fault
  • invalid_argument
  • is_connected
  • network_unreachable
  • host_unreachable
  • no_buffer_space_available
  • timed_out
  • access_denied
  • protocol_type

詳細は、WindowsとLinuxのソケットエラーを参照してください。

[2] network.peer.port: ソケットのアドレスファミリーがポートをサポートしている場合。

[3] network.transport: 値がtcpでない場合。値が指定されていない場合、tcpであると仮定されます。

[4] network.transport: この値は小文字に正規化されるべきです（SHOULD）。

ポート番号を設定する際は、常にトランスポートも設定することを検討してください。トランスポートが分からなければ、ポート番号は曖昧になるためです。たとえば、異なるプロセスがTCPポート12345とUDPポート12345の両方でリスンしている場合があります。

[5] network.type: この値は小文字に正規化されるべきです（SHOULD）。

error.typeには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

ValueDescriptionStability
_OTHER計装が独自の値を定義していない場合に使用するフォールバック用のエラー値。Stable

network.transportには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

ValueDescriptionStability
pipe名前付き、または匿名のパイプ。Stable
quicQUICStable
tcpTCPStable
udpUDPStable
unixUNIXドメインソケットStable

network.typeには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

ValueDescriptionStability
ipv4IPv4Stable
ipv6IPv6Stable

TLSハンドシェイク

スパン名は、クライアント側で認証する場合はTLS client handshake {server.address}、サーバーを認証する場合はTLS server handshakeであるべきです（SHOULD）。 スパン種別は、いずれの場合もINTERNALであるべきです（SHOULD）。

Status: Development

このスパンは、System.Net.Security.SslStreamで実行される、TLSクライアントまたはサーバーのハンドシェイクを記述します。

クライアント側の認証についてTLSスパンがHTTP接続のセットアップスパンおよびソケット接続スパンとともに報告される場合、TLSスパンはHTTP接続のセットアップの子となります。

対応するActivity.OperationNameはExperimental.System.Net.Security.TlsHandshake、ActivitySource名はExperimental.System.Net.Securityです。 .NET 9で追加されました。

スパン名は、クライアント側で認証する場合はTLS client handshake {server.address}、サーバーを認証する場合はTLS server handshakeであるべきです（SHOULD）。

スパン種別は、いずれの場合もINTERNALであるべきです（SHOULD）。

スパンステータスはエラーの記録文書に従うべきです（SHOULD）。

Attributes:

KeyStabilityRequirement LevelValue TypeDescriptionExample Values
error.typeStableConditionally Required if and only if an error has occurred.string操作が終了したエラーのクラスを記述します。System.Net.Security.Authentication.AuthenticationException; System.OperationCanceledException
server.addressStableRecommended when authenticating the client.stringTLSハンドシェイク中の「Client Hello」メッセージで使用されるサーバー名表示（SNI）。[1]opentelemetry.io; example.com
tls.protocol.nameDevelopmentRecommended when availablestringネゴシエーションされたSSL/TLSプロトコルバージョンの元の文字列から解析された、正規化済みの小文字のプロトコル名。ssl; tls
tls.protocol.versionDevelopmentRecommended when availablestringネゴシエーションされたSSL/TLSプロトコルバージョンの元の文字列から解析された、バージョンの数値部分。1.2; 3

[1] server.address: クライアント側から観測し、かつ中間サーバーを介して通信している場合、server.addressは、（利用可能であれば）プロキシなどの中間サーバーの背後にあるサーバーのアドレスを表すべきです（SHOULD）。

error.typeには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

ValueDescriptionStability
_OTHER計装が独自の値を定義していない場合に使用するフォールバック用のエラー値。Stable

tls.protocol.nameには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

ValueDescriptionStability
sslSSLDevelopment
tlsTLSDevelopment

例

接続がすぐに利用可能な状態でHTTPリクエストが実行された場合

リクエストに対して接続がすぐに利用可能な場合、HttpClientはHTTPリクエスト用に1つのスパンを作成し、それをこの接続に関連付けられたHTTP connection_setupスパンにリンクします。

この時点で、HTTP connection_setupスパンはすでに終了しています。

<- HTTP connection_setup - (trace=t1, span=s1) ->
<--- DNS --->
             <--- socket connect --->
                                     <--- TLS -->
                                                  <--- GET / (INTERNAL, trace=t2, span=s2, link_to=t1,s1) --->

HTTPリクエストが接続のセットアップを待たなければならない場合

リクエストに対して接続がすぐに利用可能でなかった場合、HTTPクライアントとハンドラーは、HTTPリクエストスパンと接続待機スパンを作成します。この例では、新しい接続が作成され、その接続が作成された直後にリクエストがその接続上で実行されました。計装は、HTTPリクエストのGETスパンに、HTTP connection_setupスパンへのリンクを追加しています。

<--------- HTTP connection_setup (trace=t1, span=s1) -------->
<--- DNS --->
             <--------- socket connect -------->
                                                <--- TLS --->


<----------------------- GET / (trace=t2, span=s2, link_to=t1,s1) -------------------------------->
<--------- HTTP wait_for_connection (trace=t2, span=s3) ------>

HTTPリクエストが接続のセットアップと、その接続上の他のリクエストの完了を待たなければならない場合

リクエストに対して接続がすぐに利用可能でなかった場合、HTTPクライアントとハンドラーは、HTTPリクエストスパンと接続待機スパンを作成します。この例では、リクエストは既存の接続上で実行されましたが、この接続はこのリクエストに利用可能になる前に、キュー内の他のリクエストを処理していました。

<- HTTP connection_setup - (t1,s1) ->
                                        <--------------------- GET / (trace=t2, span=s2) ----------------------------------------->
                                        <---- HTTP wait_for_connection (trace=t2, span=s2, link_to=t1,s1) ---->

HTTP connection_setupスパンはこのリクエストより前に開始されており、対応する接続は、上記のGETリクエストに利用可能になるまで、他のリクエストを処理していました。

ここでの長い接続待機スパンは、リクエストのキューが存在し、プール内の接続への需要が高いことを示しています。

接続が確立できないためHTTPリクエストが失敗する場合

接続が確立される前にHTTPリクエストが失敗する場合、以下のようになります。

  • 接続を確立するすべての試行が、HTTP connection_setupスパンとして記録されます。
  • HTTPリクエストのGETスパンは、対応するエラー型とともに、接続待機スパンと合わせて記録されます。
  • HTTPリクエストのGETスパンは、これらの接続が対応するリクエストと関連付けられたことがないため、いずれのHTTP connection_setupスパンにもリンクされません。
<- HTTP connection_setup - (trace=t1, span=s1) - ERROR ->
<------------------- DNS - timeout ---------------->

<---------- GET / (trace=t2, span=s2) - ERROR ---------->
<- HTTP wait_for_connection (trace=t2, span=s3) - ERROR ->