Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

BREAKING: Fix server.address vs all other address attributes inconsistency #290

Closed
wants to merge 3 commits into from
Closed

BREAKING: Fix server.address vs all other address attributes inconsistency #290

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ee36ca7
Fix inconsistency in server.address
Oberon00 Aug 29, 2023
1146d7f
Adapt other conventions
Oberon00 Aug 29, 2023
854165c
Schema
Oberon00 Aug 29, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,8 @@ release.
([#252](https://github.com/open-telemetry/semantic-conventions/pull/252))
- Simplify HTTP metric briefs.
([#276](https://github.com/open-telemetry/semantic-conventions/pull/276))
- BREAKING: Split server.domain from server.address, no longer allow domain name
in address.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
in address.
in address.
([#290](https://github.com/open-telemetry/semantic-conventions/pull/290))


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

Expand Down
20 changes: 12 additions & 8 deletions docs/database/database-spans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,26 +68,30 @@ Some database systems may allow a connection to switch to a different `db.user`,
| `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`. |
| [`server.address`](../general/attributes.md) | string | Server address - IP address or Unix domain socket name. [1] | `127.0.0.1` | Conditionally Required: See alternative attributes below. |
| [`server.domain`](../general/attributes.md) | string | Name of the database host. [2] | `example.com` | Conditionally Required: See alternative attributes below. |
| [`server.port`](../general/attributes.md) | int | Server port number [3] | `80`; `8080`; `443` | Conditionally Required: [4] |
| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [5] | `10.5.3.2` | See below |
| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [6] | `16456` | Recommended: If different than `server.port`. |

**[1]:** 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.
**[2]:** Should only be set to an actual domain name if available without reverse DNS lookup.

**[3]:** If using a port other than the default port for this DBMS and if `server.address` is set.
**[3]:** 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, this SHOULD represent the immediate server peer address.
**[4]:** If using a port other than the default port for this DBMS and if `server.address` is set.

**[5]:** 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.
**[6]:** 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:

* [`server.domain`](../general/attributes.md)
* [`server.address`](../general/attributes.md)
* [`server.socket.address`](../general/attributes.md)

Expand Down
2 changes: 1 addition & 1 deletion docs/database/elasticsearch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ in order to map the path part values to their names.
| [`db.operation`](database-spans.md) | string | The endpoint identifier for the request. [1] | `search`; `ml.close_job`; `cat.aliases` | Required |
| [`db.statement`](database-spans.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [2] |
| `http.request.method` | string | HTTP request method. [3] | `GET`; `POST`; `HEAD` | Required |
| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [4] | `example.com` | See below |
| [`server.address`](../general/attributes.md) | string | Server address - IP address or Unix domain socket name. [4] | `127.0.0.1` | See below |
| [`server.port`](../general/attributes.md) | int | Server port number [5] | `80`; `8080`; `443` | Recommended |
| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [6] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required |

Expand Down
27 changes: 15 additions & 12 deletions docs/general/attributes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,27 +55,30 @@ if they do not cause breaking changes to HTTP semantic conventions.
<!-- semconv server -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `server.address` | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended |
| `server.port` | int | Server port number [2] | `80`; `8080`; `443` | Recommended |
| `server.socket.domain` | string | Immediate server peer's domain name if available without reverse DNS lookup [3] | `proxy.example.com` | Recommended: If different than `server.address`. |
| `server.socket.address` | string | Server address of the socket connection - IP address or Unix domain socket name. [4] | `10.5.3.2` | Recommended: If different than `server.address`. |
| `server.socket.port` | int | Server port number of the socket connection. [5] | `16456` | Recommended: If different than `server.port`. |
| `server.address` | string | Server address - IP address or Unix domain socket name. [1] | `127.0.0.1` | Recommended |
| `server.domain` | string | Domain name of the server. May be set to an address if a domain is required but not available. [2] | `example.com` | Recommended |
| `server.port` | int | Server port number [3] | `80`; `8080`; `443` | Recommended |
| `server.socket.domain` | string | Immediate server peer's domain name if available without reverse DNS lookup [4] | `proxy.example.com` | Recommended: If different than `server.address`. |
| `server.socket.address` | string | Server address of the socket connection - IP address or Unix domain socket name. [5] | `10.5.3.2` | Recommended: If different than `server.address`. |
| `server.socket.port` | int | Server port number of the socket connection. [6] | `16456` | Recommended: If different than `server.port`. |

**[1]:** 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.
**[2]:** Should only be set to an actual domain name if available without reverse DNS lookup.

**[3]:** Typically observed from the client side, and represents a proxy or other intermediary domain name.
**[3]:** 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, this SHOULD represent the immediate server peer address.
**[4]:** Typically observed from the client side, and represents a proxy or other intermediary domain name.

**[5]:** 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.
**[6]:** 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.
<!-- endsemconv -->

`server.address` and `server.port` represent logical server name and port. Semantic conventions that refer to these attributes SHOULD
`server.domain`, `server.address` and `server.port` represent logical server name, address and port. Semantic conventions that refer to these attributes SHOULD
specify what these attributes mean in their context.

Semantic conventions and instrumentations that populate both logical (`server.address` and `server.port`) and socket-level (`server.socket.*`) attributes SHOULD set socket-level attributes only when they don't match logical ones. For example, when direct connection to the remote destination is established and `server.address` is populated, `server.socket.domain` SHOULD NOT be set. Check out [Connecting through intermediary](#connecting-through-intermediary) for more information.
Expand Down Expand Up @@ -223,7 +226,7 @@ This also covers unidirectional UDP flows and peer-to-peer communication where t
<!-- semconv source -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `source.domain` | string | The domain name of the source system. [1] | `foo.example.com` | Recommended |
| `source.domain` | string | The domain name of the source system. May be set to an address if a domain is required but not available. [1] | `foo.example.com` | Recommended |
| `source.address` | string | Source address, for example IP address or Unix socket name. | `10.5.3.2` | Recommended |
| `source.port` | int | Source port number | `3389`; `2888` | Recommended |

Expand All @@ -237,7 +240,7 @@ Destination fields capture details about the receiver of a network exchange/pack
<!-- semconv destination -->
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `destination.domain` | string | The domain name of the destination system. [1] | `foo.example.com` | Recommended |
| `destination.domain` | string | The domain name of the destination system. May be set to an address if a domain is required but not available. [1] | `foo.example.com` | Recommended |
| `destination.address` | string | Destination address, for example IP address or UNIX socket name. | `10.5.3.2` | Recommended |
| `destination.port` | int | Destination port number | `3389`; `2888` | Recommended |

Expand Down
Loading