Skip to content

Commit

Permalink
Merge branch 'main' into tyler/xray-env
Browse files Browse the repository at this point in the history
  • Loading branch information
@tylerbenson
tylerbenson authored Oct 2, 2023
2 parents 7e42a79 + 590aff7 commit 3d924e8
Show file tree
Hide file tree
Showing 13 changed files with 280 additions and 175 deletions.
8 changes: 8 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,14 @@ release.
([#318](https://github.com/open-telemetry/semantic-conventions/pull/318))
- Replace AWS X-Ray Environment Span Link section with AWS X-Ray `Active Tracing` Considerations
([#354](https://github.com/open-telemetry/semantic-conventions/pull/354))
- Encourage setting `network.transport` when reporting port numbers
([#289](https://github.com/open-telemetry/semantic-conventions/pull/289))
- BREAKING: Add `url.scheme` to `http.client.*` metrics
([#357](https://github.com/open-telemetry/semantic-conventions/pull/357))
- BREAKING: Remove `server.socket.address` from HTTP and RPC client metrics.
([#350](https://github.com/open-telemetry/semantic-conventions/pull/350))
- Improve network attribute briefs.
([#352](https://github.com/open-telemetry/semantic-conventions/pull/352))

## v1.21.0 (2023-07-13)

Expand Down
32 changes: 20 additions & 12 deletions docs/database/database-spans.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,24 +67,32 @@ Some database systems may allow a connection to switch to a different `db.user`,
| `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required |
| `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;` | Recommended |
| `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended |
| [`network.transport`](../general/attributes.md) | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| [`network.type`](../general/attributes.md) | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| [`server.address`](../general/attributes.md) | string | Name of the database host. [1] | `example.com` | Conditionally Required: See alternative attributes below. |
| [`server.port`](../general/attributes.md) | int | Server port number [2] | `80`; `8080`; `443` | Conditionally Required: [3] |
| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [4] | `10.5.3.2` | See below |
| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [5] | `16456` | Recommended: If different than `server.port`. |

**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent
| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended |
| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended |
| [`server.address`](../general/attributes.md) | string | Name of the database host. [3] | `example.com` | Conditionally Required: See alternative attributes below. |
| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [6] | `10.5.3.2` | See below |
| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [7] | `16456` | Recommended: If different than `server.port`. |

**[1]:** The value SHOULD be normalized to lowercase.

Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport, for example
different processes could be listening on TCP port 12345 and UDP port 12345.

**[2]:** The value SHOULD be normalized to lowercase.

**[3]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent
the server address behind any intermediaries (e.g. proxies) if it's available.

**[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available.
**[4]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available.

**[3]:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[5]:** If using a port other than the default port for this DBMS and if `server.address` is set.

**[4]:** When observed from the client side, this SHOULD represent the immediate server peer address.
**[6]:** When observed from the client side, this SHOULD represent the immediate server peer address.
When observed from the server side, this SHOULD represent the physical server address.

**[5]:** When observed from the client side, this SHOULD represent the immediate server peer port.
**[7]:** When observed from the client side, this SHOULD represent the immediate server peer port.
When observed from the server side, this SHOULD represent the physical server port.

**Additional attribute requirements:** At least one of the following sets of attributes is required:
Expand Down
101 changes: 62 additions & 39 deletions docs/general/attributes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,25 +15,29 @@ Particular operations may refer to or require some of these attributes.

<!-- toc -->

- [Server and client attributes](#server-and-client-attributes)
- [Server, client and shared network attributes](#server-client-and-shared-network-attributes)
* [Address and port attributes](#address-and-port-attributes)
* [Server attributes](#server-attributes)
+ [`server.address`](#serveraddress)
+ [`server.socket.*` attributes](#serversocket-attributes)
* [Client attributes](#client-attributes)
+ [Connecting through intermediary](#connecting-through-intermediary)
- [Network attributes](#network-attributes)
* [Source and destination attributes](#source-and-destination-attributes)
+ [Source](#source)
+ [Destination](#destination)
* [Network connection and carrier attributes](#network-connection-and-carrier-attributes)
* [Other network attributes](#other-network-attributes)
+ [Network connection and carrier attributes](#network-connection-and-carrier-attributes)
- [General remote service attributes](#general-remote-service-attributes)
- [General identity attributes](#general-identity-attributes)
- [General thread attributes](#general-thread-attributes)
- [Source Code Attributes](#source-code-attributes)

<!-- tocstop -->

## Server and client attributes
<!-- Keep old anchor IDs -->
<a name="server-and-client-attributes"></a>

## Server, client and shared network attributes

These attributes may be used to describe the client and server in a connection-based network interaction
where there is one side that initiates the connection (the client is the side that initiates the connection).
Expand All @@ -45,6 +49,13 @@ This also covers UDP network interactions where one side initiates the interacti
In an ideal situation, not accounting for proxies, multiple IP addresses or host names,
the `server.*` attributes are the same on the client and server.

### Address and port attributes

For all IP-based protocols, the "address" should be just the IP-level address.
Protocol-specific parts of an address are split into other attributes (when applicable) such as "port" attributes for
TCP and UDP. If such transport-specific information is collected and the attribute name does not already uniquely
identify the transport, then setting [`network.transport`](#other-network-attributes) is especially encouraged.

### Server attributes

> **Warning**
Expand Down Expand Up @@ -175,40 +186,6 @@ The `client.socket.address` and `client.socket.port` attributes then SHOULD cont

If only immediate peer information is available, it should be set on `client.address` and `client.port` and `client.socket.*` attributes SHOULD NOT be set.

## Network attributes

> **Warning**
> Attributes in this section are in use by the HTTP semantic conventions.
Once the HTTP semantic conventions are declared stable, changes to the attributes in this section will only be allowed
if they do not cause breaking changes to HTTP semantic conventions.

<!-- semconv network-core -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `network.transport` | string | [OSI Transport Layer](https://osi-model.com/transport-layer/) or [Inter-process Communication method](https://en.wikipedia.org/wiki/Inter-process_communication). The value SHOULD be normalized to lowercase. | `tcp`; `udp` | Recommended |
| `network.type` | string | [OSI Network Layer](https://osi-model.com/network-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `ipv4`; `ipv6` | Recommended |
| `network.protocol.name` | string | [OSI Application Layer](https://osi-model.com/application-layer/) or non-OSI equivalent. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended |
| `network.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended |

**[1]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.

`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

| Value | Description |
|---|---|
| `tcp` | TCP |
| `udp` | UDP |
| `pipe` | Named or anonymous pipe. See note below. |
| `unix` | Unix domain socket |

`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

| Value | Description |
|---|---|
| `ipv4` | IPv4 |
| `ipv6` | IPv6 |
<!-- endsemconv -->

### Source and destination attributes

These attributes may be used to describe the sender and receiver of a network exchange/packet. These should be used
Expand Down Expand Up @@ -244,7 +221,53 @@ Destination fields capture details about the receiver of a network exchange/pack
**[1]:** This value may be a host name, a fully qualified domain name, or another host naming format.
<!-- endsemconv -->

### Network connection and carrier attributes
<a name="network-attributes"></a>

### Other network attributes

> **Warning**
> Attributes in this section are in use by the HTTP semantic conventions.
Once the HTTP semantic conventions are declared stable, changes to the attributes in this section will only be allowed
if they do not cause breaking changes to HTTP semantic conventions.

<!-- semconv network-core -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended |
| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended |
| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `amqp`; `http`; `mqtt` | Recommended |
| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. [4] | `3.1.1` | Recommended |

**[1]:** The value SHOULD be normalized to lowercase.

Consider always setting the transport when setting a port number, since
a port number is ambiguous without knowing the transport, for example
different processes could be listening on TCP port 12345 and UDP port 12345.

**[2]:** The value SHOULD be normalized to lowercase.

**[3]:** The value SHOULD be normalized to lowercase.

**[4]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.

`network.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

| Value | Description |
|---|---|
| `tcp` | TCP |
| `udp` | UDP |
| `pipe` | Named or anonymous pipe. See note below. |
| `unix` | Unix domain socket |

`network.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.

| Value | Description |
|---|---|
| `ipv4` | IPv4 |
| `ipv6` | IPv6 |
<!-- endsemconv -->

#### Network connection and carrier attributes

<!-- semconv network-connection-and-carrier -->
| Attribute | Type | Description | Examples | Requirement Level |
Expand Down
Loading

0 comments on commit 3d924e8

Please sign in to comment.