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

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

General attributes

ステータス: Development

この節で説明する属性は、特定の操作に固有のものではなく、汎用的なものです。 これらは、適用可能なあらゆるスパンで使用できます。 個々の操作は、これらの属性のいくつかを参照または要求することがあります。

サーバー、クライアント、共有ネットワーク属性

理想的な状況（プロキシや複数のIPアドレス・ホスト名がない状況）では、server.* 属性はクライアント側とサーバー側で同じです。

アドレスとポートの属性

すべてのIPベースのプロトコルにおいて、「アドレス」はIPレベルのアドレスのみとするべきです。 プロトコル固有のアドレス部分は、適用可能な場合、TCPとUDPの「ポート」属性のような別の属性に分割されます。 このようなトランスポート固有の情報が収集され、かつ属性名からトランスポートが一意に識別できない場合は、特に network.transport を設定することが推奨されます。

サーバー属性

Status:

これらの属性は、接続を開始する側であるクライアントが存在する、接続ベースのネットワーク相互作用においてサーバーを記述するために使用できます。これは、TCPが接続ベースであり一方の側が接続を開始するため、すべてのTCPネットワーク相互作用に当てはまります（例外として、プロトコル・APIの「ユーザー向け」の表面にクライアントとサーバーの明確な区別がないTCP上のピアツーピア通信があります）。これは、一方の側が相互作用を開始するUDPネットワーク相互作用（QUIC（HTTP/3）やDNSなど）にも当てはまります。

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
server.address		Recommended	string	利用可能であればリバースDNSルックアップなしのサーバードメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[1]	example.com; 10.1.2.80; /tmp/my.sock
server.port		Recommended	int	サーバーのポート番号。[2]	80; 8080; 443

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

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

server.address と server.port は、論理的なサーバー名とポートを表します。 これらの属性を参照するセマンティック規約は、それぞれの文脈でこれらの属性が何を意味するのかを規定すべきです（SHOULD）。

server.address

IPベースの通信の場合、名前はサービスのDNSホスト名であるべきです。 クライアント側ではリモートサービス名と一致し、サーバー側では外部のクライアントから見えるローカルサービス名を表します。

URL https://example.com/foo に接続する場合、server.address はクライアント側とサーバー側の両方で "example.com" と一致します。

クライアント側では、通常はURL、接続文字列、ホスト名などの形式で渡されます。 ホスト名が、DNS名またはIPアドレスを含みうる文字列として計装にしか渡されないこともあります。 server.address は、利用可能な既知のホスト名に設定すべきです（SHOULD）（例えば、URL https://127.0.0.1/foo に接続する場合は "127.0.0.1"）。

IPアドレスしか利用できない場合は、それを server.address に設定すべきです。 DNS名の取得にリバースDNSルックアップを使用すべきではありません（SHOULD NOT）。

network.transport が "pipe" の場合、それを表すファイルの絶対パスを server.address として使用すべきです。 そのようなファイルがない場合（例えば無名パイプの場合）、名前が単に不明であるケースや計装で対応されていないケースと区別するために、明示的に空文字列に設定すべきです。

UNIXドメインソケットの場合、server.address 属性は、クライアント側ではリモートエンドポイントのアドレスを、サーバー側ではローカルエンドポイントのアドレスを表します。

クライアント属性

Status:

これらの属性は、接続を開始する側であるクライアントが存在する、接続ベースのネットワーク相互作用においてクライアントを記述するために使用できます。これは、TCPが接続ベースであり一方の側が接続を開始するため、すべてのTCPネットワーク相互作用に当てはまります（例外として、プロトコル・APIの「ユーザー向け」の表面にクライアントとサーバーの明確な区別がないTCP上のピアツーピア通信があります）。これは、一方の側が相互作用を開始するUDPネットワーク相互作用（QUIC（HTTP/3）やDNSなど）にも当てはまります。

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
client.address		Recommended	string	クライアントアドレス。利用可能であればリバースDNSルックアップなしのドメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[1]	client.example.com; 10.1.2.80; /tmp/my.sock
client.port		Recommended	int	クライアントのポート番号。[2]	65123

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

[2] client.port: サーバー側から観測し、かつ中継者（例えばプロキシ）を経由して通信している場合、client.port は、利用可能であれば、その中継者の背後にあるクライアントポートを表すべきです（SHOULD）。

送信元と宛先の属性

送信元

Status:

これらの属性は、ネットワーク交換・パケットの送信者を記述するために使用できます。これらは、両者の間にクライアント・サーバーの関係がない場合、またはその関係が不明な場合に使用すべきです。これは、接続があったかどうか、どちらの側が開始したかが分からない低レベルのネットワーク相互作用（パケットトレースなど）に当てはまります。これは、単方向のUDPフローや、プロトコル・APIの「ユーザー向け」の表面にクライアントとサーバーの明確な区別がないピアツーピア通信にも当てはまります。

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
source.address		Recommended	string	送信元アドレス。利用可能であればリバースDNSルックアップなしのドメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[1]	source.example.com; 10.1.2.80; /tmp/my.sock
source.port		Recommended	int	送信元のポート番号	3389; 2888

[1] source.address: 宛先側から観測し、かつ中継者（例えばプロキシ）を経由して通信している場合、source.address は、利用可能であれば、その中継者の背後にある送信元アドレスを表すべきです（SHOULD）。

宛先

Status:

これらの属性は、ネットワーク交換・パケットの受信者を記述するために使用できます。これらは、両者の間にクライアント・サーバーの関係がない場合、またはその関係が不明な場合に使用すべきです。これは、接続があったかどうか、どちらの側が開始したかが分からない低レベルのネットワーク相互作用（パケットトレースなど）に当てはまります。これは、単方向のUDPフローや、プロトコル・APIの「ユーザー向け」の表面にクライアントとサーバーの明確な区別がないピアツーピア通信にも当てはまります。

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
destination.address		Recommended	string	宛先アドレス。利用可能であればリバースDNSルックアップなしのドメイン名。それ以外の場合はIPアドレスまたはUNIXドメインソケット名。[1]	destination.example.com; 10.1.2.80; /tmp/my.sock
destination.port		Recommended	int	宛先のポート番号	3389; 2888

[1] destination.address: 送信元側から観測し、かつ中継者（例えばプロキシ）を経由して通信している場合、destination.address は、利用可能であれば、その中継者の背後にある宛先アドレスを表すべきです（SHOULD）。

その他のネットワーク属性

[!IMPORTANT] この節の属性は、HTTPセマンティック規約で使用されています。 HTTPセマンティック規約が安定版として宣言された後は、この節の属性への変更は、HTTPセマンティック規約に破壊的変更をもたらさない場合にのみ許可されます。

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
network.local.address		Recommended	string	ネットワーク接続のローカルアドレス。IPアドレスまたはUNIXドメインソケット名。	10.1.2.80; /tmp/my.sock
network.local.port		Recommended	int	ネットワーク接続のローカルポート番号。	65123
network.peer.address		Recommended	string	ネットワーク接続のピアアドレス。IPアドレスまたはUNIXドメインソケット名。	10.1.2.80; /tmp/my.sock
network.peer.port		Recommended	int	ネットワーク接続のピアポート番号。	65123
network.protocol.name		Recommended	string	OSIアプリケーション層またはそれに相当する非OSI層。[1]	amqp; http; mqtt
network.protocol.version		Recommended	string	ネットワーク通信で使用されているプロトコルの実際のバージョン。[2]	1.1; 2
network.transport		Recommended	string	OSIトランスポート層またはプロセス間通信方式。[3]	tcp; udp
network.type		Recommended	string	OSIネットワーク層またはそれに相当する非OSI層。[4]	ipv4; ipv6

[1] network.protocol.name: 値は小文字に正規化すべきです（SHOULD）。

[2] network.protocol.version: プロトコルバージョンが（例えばALPNを使って）ネゴシエーションされる場合、この属性はネゴシエーションされたバージョンに設定すべきです（SHOULD）。実際のプロトコルバージョンが不明な場合、この属性は設定するべきではありません（SHOULD NOT）。

[3] network.transport: 値は小文字に正規化すべきです（SHOULD）。

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

[4] network.type: 値は小文字に正規化すべきです（SHOULD）。

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

Value	Description	Stability
pipe	名前付きまたは無名のパイプ。
quic	QUIC
tcp	TCP
udp	UDP
unix	UNIXドメインソケット

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

Value	Description	Stability
ipv4	IPv4
ipv6	IPv6

network.peer.* と network.local.* 属性

これらの属性は、互いに直接接続されているネットワークピアを識別します。

network.peer.address と network.local.address は、IPアドレス、UNIXドメインソケット名、またはネットワーク種別に固有の他のアドレスであるべきです。

注: ソケットレベルの属性を取得するための具体的な構造体やメソッドは、あくまで例として挙げているに過ぎません。計装は通常、実行環境やソケット実装が提供するSocket APIを使用します。

AF_INET アドレスファミリーで connect(2)（LinuxまたはPOSIX系 / Windows)や bind(2)（LinuxまたはPOSIX系 / Windows)を使って接続する場合、network.peer.address と network.peer.port は、sockaddr_in 構造体の sin_addr と sin_port フィールドを表します。

network.peer.address と network.peer.port は、getpeername メソッド（LinuxまたはPOSIX系 / Windows）を呼び出すことで取得できます。

network.local.address と network.local.port は、getsockname メソッド（LinuxまたはPOSIX系 / Windows）を呼び出すことで取得できます。

network.peer.* を使ったクライアント・サーバーの例

これらの例には network.local.* 属性が含まれていない点に注意してください。これらの属性は通常Opt-Inだからです。

シンプルなクライアント・サーバーの例

リバースプロキシを使ったクライアント・サーバーの例

フォワードプロキシを使ったクライアント・サーバーの例

ネットワーク接続とキャリアの属性

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
network.carrier.icc		Recommended	string	モバイルキャリアネットワークに関連付けられたISO 3166-1 alpha-2の2文字国コード。	DE
network.carrier.mcc		Recommended	string	モバイルキャリアの国コード。	310
network.carrier.mnc		Recommended	string	モバイルキャリアのネットワークコード。	001
network.carrier.name		Recommended	string	モバイルキャリアの名前。	sprint
network.connection.subtype		Recommended	string	接続に関するさらなる詳細を記述します。セルラー技術の接続タイプの場合もありますが、Wi-Fi接続の詳細を記述するために使われることもあります。	LTE
network.connection.type		Recommended	string	インターネット接続の種類。	wifi

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

Value	Description	Stability
cdma	CDMA
cdma2000_1xrtt	CDMA2000 1XRTT
edge	EDGE
ehrpd	EHRPD
evdo_0	EVDO Rel. 0
evdo_a	EVDO Rev. A
evdo_b	EVDO Rev. B
gprs	GPRS
gsm	GSM
hsdpa	HSDPA
hspa	HSPA
hspap	HSPAP
hsupa	HSUPA
iden	IDEN
iwlan	IWLAN
lte	LTE
lte_ca	LTE CA
nr	5G NR（New Radio）
nrnsa	5G NRNSA（New Radio Non-Standalone）
td_scdma	TD-SCDMA
umts	UMTS

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

Value	Description	Stability
cell	セル
unavailable	利用不可
unknown	不明
wifi	Wi-Fi
wired	有線

UNIX と pipe の場合、接続はファイルシステム経由であり既知のピアへの直接接続ではないため、通常意味をなす属性は server.address だけです（後述の server.address の説明を参照してください）。

汎用のリモートサービス属性

サービスピア

service.peer.* 名前空間の属性は、何らかのリモートサービスにアクセスするあらゆる操作で使用できます。 ユーザーは、自身の分散システムにおける独自のセマンティクスに基づいて、サービス名が何であるかを定義できます。

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
service.peer.name		Opt-In	string	接続の相手側にあるサービスの論理名。リモートサービスの実際のservice.nameリソース属性と等しくあるべきです（SHOULD）。	shoppingcart
service.peer.namespace		Opt-In	string	接続の相手側にあるサービスの論理名前空間。リモートサービスの実際のservice.namespaceリソース属性と等しくあるべきです（SHOULD）。	Shop

汎用のスレッド属性

これらの属性は、スパンを開始したスレッドの情報を保存するために、あらゆる操作で使用できます。

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
thread.id		Recommended	int	現在の「マネージド」スレッドID（OSスレッドIDとは異なる）。[1]	42
thread.name		Recommended	string	現在のスレッド名。[2]	main

[1] thread.id: 値を取得できる箇所の例:

[2] thread.name: 値を取得できる箇所の例:

ソースコード属性

ステータス: Release Candidate

多くの場合、スパンはその操作を処理する責任を論理的に持つ特定のコード単位（通常はスパンを開始するメソッド）と密接に結び付いています。 例えばHTTPサーバーのスパンでは、それは受信したリクエストを処理する関数です。 code属性を使うと、このコード単位を報告でき、より多くのコンテキストを提供できます。