clean up

open-telemetry · Jun 10, 2022 · b2f2024 · b2f2024
1 parent 125f24a
commit b2f2024
Show file tree

Hide file tree

Showing 12 changed files with 125 additions and 89 deletions.
diff --git a/schemas/1.11.0 b/schemas/1.11.0
@@ -7,7 +7,7 @@ versions:
         - rename_attributes:
             attribute_map:
               net.peer.ip: net.sock.peer.addr
-              net.host.port: net.sock.host.port
+              net.host.ip: net.sock.host.addr
 
   1.10.0:
   1.9.0:

diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml
@@ -229,8 +229,6 @@ groups:
           conditional: Required if using a port other than the default port for this DBMS.
       - ref: net.sock.family
         tag: connection-level
-        required:
-          conditional: if applicable and if any of `net.sock.peer.addr` or `net.peer.name` are set.
       - ref: net.transport
         tag: connection-level
         required:
@@ -239,7 +237,6 @@ groups:
       - any_of:
           - 'net.peer.name'
           - 'net.sock.peer.addr'
-
   - id: db.mssql
     prefix: db.mssql
     extends: db
@@ -250,7 +247,7 @@ groups:
         tag: connection-level-tech-specific
         type: string
         note: >
-          If setting a `db.mssql.instance_name`, `net.sock.peer.port` is no longer
+          If setting a `db.mssql.instance_name`, `net.peer.port` is no longer
           required (but still recommended if non-standard).
         brief: >
           The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15)

diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml
@@ -39,7 +39,7 @@ groups:
         examples: ['127.0.0.1', '/tmp/mysql.sock' ]
       - id: sock.peer.port
         type: int
-        required: 
+        required:
           conditional: if `net.sock.peer.addr` is set and `net.sock.family` has a notion of port
         brief: 'Remote socket peer port (if defined for the address family).'
         examples: 16456
@@ -56,7 +56,7 @@ groups:
             - id: unix
               value: 'AF_UNIX'
               brief: "Unix domain socket path/"
-        required: 
+        required:
           conditional: if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set
         brief: >
           Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication.
@@ -71,24 +71,28 @@ groups:
         type: int
         brief: 'Logical remote port number'
         examples: [80, 8080, 443]
+      - id: host.name
+        type: string
+        brief: 'Logical local hostname or similar, see note below.'
+        examples: 'localhost'
+      - id: host.port
+        type: int
+        brief: 'Logical local port number, preferably the one that the peer used to connect'
+        examples: 8080
       - id: sock.host.addr
         type: string
         brief: 'Like `net.sock.peer.addr` but for the host IP. Useful in case of a multi-IP host.'
         note: >
-          Can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.htmll)
-          or [Windows](https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-getsockname)
+          Can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.html)
+          or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname)
           with format specific to protocol address family.
         examples: '192.168.0.1'
       - id: sock.host.port
         type: int
-        required: 
+        required:
           conditional: if `net.sock.host.addr` is set and `net.sock.family` has a notion of port
-        brief: 'Like `net.sock.peer.port` but for the host port.'
+        brief: 'Local socket peer port (if defined for the address family).'
         examples: 35555
-      - id: host.name
-        type: string
-        brief: 'Logical local hostname or similar, see note below.'
-        examples: 'localhost'
       - id: host.connection.type
         type:
           allow_custom_values: true

diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml
@@ -116,36 +116,36 @@ groups:
         examples: 3
       - ref: net.sock.peer.addr
       - ref: net.sock.peer.port
+      - ref: net.sock.family
+        required:
+          conditional: if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set
+    constraints:
+      - include: network
+
+  - id: http.client
+    prefix: http
+    extends: http
+    span_kind: client
+    brief: 'Semantic Convention for HTTP Client'
+    attributes:
       - ref: net.peer.name
         sampling_relevant: true
         brief: >
           Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to.
         note: >
-          When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set 
-          `net.peer.name` to the IP address provided in the host component.
-          When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` SHOULD match 
+          When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set
+          `net.peer.name` to the provided host component.
+          When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` SHOULD match
           URI host component, otherwise `Host` header host component SHOULD be used.
       - ref: net.peer.port
         sampling_relevant: true
         required:
-         conditional: if not default for request scheme.
+          conditional: if not default for request scheme.
         brief: >
           Port identifier of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to.
         note: >
-          When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match 
+          When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match
           URI port component, otherwise it MUST match `Host` header port component.
-
-    constraints:
-      - include: network
-
-  - id: http.client
-    prefix: http
-    extends: http
-    span_kind: client
-    brief: 'Semantic Convention for HTTP Client'
-    attributes:
-      - ref: net.peer.name
-        sampling_relevant: true
     constraints:
       - any_of:
           - [http.url]
@@ -191,12 +191,27 @@ groups:
             one is at least somewhat confident that the address is not that of
             the closest proxy.
         examples: '83.164.160.102'
+      - ref: net.host.name
+        sampling_relevant: true
+        brief: >
+          Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to.
+        note: >
+          When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set
+          `net.host.name` to the IP address provided in the host component.
+          When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.name` SHOULD match
+          URI host component, otherwise `Host` header host component SHOULD be used.
+      - ref: net.host.port
+        sampling_relevant: true
+        brief: >
+          Port component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to.
+        note: >
+          When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.port` SHOULD match
+          URI port component, otherwise `Host` header port component SHOULD be used.
       - ref: net.sock.host.addr
       - ref: net.sock.host.port
-
     constraints:
       - any_of:
           - [http.scheme, http.host, http.target]
-          - [http.scheme, http.server_name, net.sock.host.port, http.target]
-          - [http.scheme, net.host.name, net.sock.host.port, http.target]
+          - [http.scheme, http.server_name, net.host.port, http.target]
+          - [http.scheme, net.host.name, net.host.port, http.target]
           - [http.url]
diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml
@@ -55,8 +55,8 @@ groups:
         brief: >
           RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html).
         note: >
-          May contain server IP address, DNS name, or local socket name.  When host component is an IP address, 
-          instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set 
+          May contain server IP address, DNS name, or local socket name. When host component is an IP address,
+          instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set
           `net.peer.name` to the IP address provided in the host component.
       - ref: net.peer.port
         brief: >

diff --git a/specification/metrics/datamodel.md b/specification/metrics/datamodel.md
@@ -1292,7 +1292,7 @@ attributes, and MUST NOT be added as metric attributes:
 | OTLP Resource Attribute | Description |
 | ----------------------- | ----------- |
 | `net.host.name` | The `<host>` portion of the target's URL that was scraped |
-| `net.sock.host.port` | The `<port>` portion of the target's URL that was scraped |
+| `net.host.port` | The `<port>` portion of the target's URL that was scraped |
 | `http.scheme` | `http` or `https` |
 
 In addition to the attributes above, the

diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md
@@ -47,7 +47,7 @@ and whether they should be on server, client, or both types of HTTP metric event
 | `net.sock.peer.addr`      | `client`            | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes)                                                                                 |
 | `http.server_name` | `server`            | see [2] in [attribute alternatives](#attribute-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). |
 | `net.host.name`    | `server`            | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes)                                                                                 |
-| `net.sock.host.port`    | `server`            | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes)                                                                                 |
+| `net.host.port`    | `server`            | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes)                                                                                 |
 
 The following attributes SHOULD be included in the `http.server.active_requests` observation:
 
@@ -93,13 +93,12 @@ path.
 * `http.url`
 * `http.scheme`, `http.host`, `http.target`
 * `http.scheme`, `net.peer.name`, `net.peer.port`, `http.target`
-* `http.scheme`, `net.sock.peer.addr`, `net.peer.port`, `http.target`
 
 **[2]** For server metric attributes, `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. <https://github.com/open-telemetry/opentelemetry-python/pull/148>).
 It is thus preferred to supply the raw data that _is_ available.
 Namely, one of the following sets is RECOMMENDED (in order of usual preference unless for a particular web server/framework it is known that some other set is preferable for some reason; all strings must be non-empty):
 
 * `http.scheme`, `http.host`, `http.target`
-* `http.scheme`, `http.server_name`, `net.sock.host.port`, `http.target`
-* `http.scheme`, `net.host.name`, `net.sock.host.port`, `http.target`
+* `http.scheme`, `http.server_name`, `net.host.port`, `http.target`
+* `http.scheme`, `net.host.name`, `net.host.port`, `http.target`
 * `http.url`
diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md
@@ -75,7 +75,7 @@ or not they should be on the server, client or both.
 
 **[2]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
 
-**[3]:** May contain server IP address, DNS name, or local socket name.  When host component is an IP address,  instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set  `net.peer.name` to the IP address provided in the host component.
+**[3]:** May contain server IP address, DNS name, or local socket name.  When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `net.peer.name` to the IP address provided in the host component.
 
 **[4]:** Can be obtained by calling `getpeername` method on [Linux](https://man7.org/linux/man-pages/man2/getpeername.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername) with format specific to protocol address family.
 

diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md
@@ -43,21 +43,19 @@ Some database systems may allow a connection to switch to a different `db.user`,
 | `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | No |
 | `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | No |
 | [`net.peer.name`](span-general.md) | string | Database hostname. [1] | `example.com` | See below. |
-| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `AF_INET`; `AF_BLUETOOTH` | Conditional [2] |
+| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `AF_INET`; `AF_BLUETOOTH` | No |
 | [`net.sock.peer.addr`](span-general.md) | string | Remote socket peer address (IPv4 or IPv6 for internet protocols, path for local communication,
- [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). [3] | `127.0.0.1`; `/tmp/mysql.sock` | See below. |
-| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Conditional [4] |
-| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditional [5] |
+ [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). [2] | `127.0.0.1`; `/tmp/mysql.sock` | See below. |
+| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Conditional [3] |
+| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditional [4] |
 
 **[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup.
 
-**[2]:** if applicable and if any of `net.sock.peer.addr` or `net.peer.name` are set.
+**[2]:** Can be obtained by calling `getpeername` method on [Linux](https://man7.org/linux/man-pages/man2/getpeername.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername) with format specific to protocol address family.
 
-**[3]:** Can be obtained by calling `getpeername` method on [Linux](https://man7.org/linux/man-pages/man2/getpeername.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername) with format specific to protocol address family.
+**[3]:** Required if using a port other than the default port for this DBMS.
 
-**[4]:** Required if using a port other than the default port for this DBMS.
-
-**[5]:** Recommended in general, required for in-process databases (`"inproc"`).
+**[4]:** Recommended in general, required for in-process databases (`"inproc"`).
 
 **Additional attribute requirements:** At least one of the following sets of attributes is required:
 
@@ -143,7 +141,7 @@ When additional attributes are added that only apply to a specific DBMS, its ide
 | `db.jdbc.driver_classname` | string | The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | No |
 | `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | No |
 
-**[1]:** If setting a `db.mssql.instance_name`, `net.sock.peer.port` is no longer required (but still recommended if non-standard).
+**[1]:** If setting a `db.mssql.instance_name`, `net.peer.port` is no longer required (but still recommended if non-standard).
 <!-- endsemconv -->
 
 ## Call-level attributes