Merge branch 'main' into pod-annotations

open-telemetry · Nov 9, 2023 · 5523d93 · 5523d93
2 parents f5b5960 + 6a9acef
commit 5523d93
Show file tree

Hide file tree

Showing 21 changed files with 187 additions and 50 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,9 @@ release.
 - Adds `labels` attribute to `k8s.pod` resource
   ([#494](https://github.com/open-telemetry/semantic-conventions/pull/494))
 
+- Add `code.stacktrace` attribute
+  ([#435](https://github.com/open-telemetry/semantic-conventions/pull/435))
+
 ### Fixes
 
 ## v1.23.0 (2023-11-03)

diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
@@ -27,13 +27,17 @@ All registered attributes are listed by namespace in this registry.
 
 Currently, the following namespaces exist:
 
+* [Client](client.md)
 * [Cloud](cloud.md)
 * [Code](code.md)
 * [Container](container.md)
+* [Destination](destination.md)
 * [HTTP](http.md)
 * [Network](network.md)
 * [OCI](oci.md)
 * [RPC](rpc.md)
+* [Server](server.md)
+* [Source](source.md)
 * [Thread](thread.md)
 * [URL](url.md)
 * [User agent](user-agent.md)

diff --git a/docs/attributes-registry/client.md b/docs/attributes-registry/client.md
@@ -0,0 +1,23 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Client
+--->
+
+# Client Attributes
+
+These attributes may be used to describe the client in a connection-based network interaction
+where there is one side that initiates the connection (the client is the side that initiates the connection).
+This covers all TCP network interactions since TCP is connection-based and one side initiates the
+connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the
+protocol / API does not expose a clear notion of client and server).
+This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS.
+
+<!-- semconv client(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `client.address` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` |
+| `client.port` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Client port number. [2] | `65123` |
+
+**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries,  for example proxies, if it's available.
+
+**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries,  for example proxies, if it's available.
+<!-- endsemconv -->
diff --git a/docs/attributes-registry/code.md b/docs/attributes-registry/code.md
@@ -15,4 +15,5 @@ These attributes allow to report this unit of code and therefore to provide more
 | `code.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` |
 | `code.lineno` | int | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `42` |
 | `code.namespace` | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` |
+| `code.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` |
 <!-- endsemconv -->
diff --git a/docs/attributes-registry/destination.md b/docs/attributes-registry/destination.md
@@ -0,0 +1,21 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Destination
+--->
+
+# Destination Attributes
+
+These attributes may be used to describe the receiver of a network exchange/packet. These should be used
+when there is no client/server relationship between the two sides, or when that relationship is unknown.
+This covers low-level network interactions (e.g. packet tracing) where you don't know if
+there was a connection or which side initiated it.
+This also covers unidirectional UDP flows and peer-to-peer communication where the
+"user-facing" surface of the protocol / API does not expose a clear notion of client and server.
+
+<!-- semconv destination(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `destination.address` | string | Destination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `destination.example.com`; `10.1.2.80`; `/tmp/my.sock` |
+| `destination.port` | int | Destination port number | `3389`; `2888` |
+
+**[1]:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries, for example proxies, if it's available.
+<!-- endsemconv -->
diff --git a/docs/attributes-registry/server.md b/docs/attributes-registry/server.md
@@ -0,0 +1,23 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Server
+--->
+
+# Server Attributes
+
+These attributes may be used to describe the 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).
+This covers all TCP network interactions since TCP is connection-based and one side initiates the
+connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the
+protocol / API does not expose a clear notion of client and server).
+This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS.
+
+<!-- semconv server(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `server.address` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` |
+| `server.port` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Server port number. [2] | `80`; `8080`; `443` |
+
+**[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example 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, for example proxies, if it's available.
+<!-- endsemconv -->
diff --git a/docs/attributes-registry/source.md b/docs/attributes-registry/source.md
@@ -0,0 +1,21 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Source
+--->
+
+# Source Attributes
+
+These attributes may be used to describe the sender of a network exchange/packet. These should be used
+when there is no client/server relationship between the two sides, or when that relationship is unknown.
+This covers low-level network interactions (e.g. packet tracing) where you don't know if
+there was a connection or which side initiated it.
+This also covers unidirectional UDP flows and peer-to-peer communication where the
+"user-facing" surface of the protocol / API does not expose a clear notion of client and server.
+
+<!-- semconv source(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `source.address` | string | Source address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `source.example.com`; `10.1.2.80`; `/tmp/my.sock` |
+| `source.port` | int | Source port number | `3389`; `2888` |
+
+**[1]:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries, for example proxies, if it's available.
+<!-- endsemconv -->
diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md
@@ -71,8 +71,8 @@ Some database systems may allow a connection to switch to a different `db.user`,
 | [`network.peer.port`](../attributes-registry/network.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. |
 | [`network.transport`](../attributes-registry/network.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended |
 | [`network.type`](../attributes-registry/network.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`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
-| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
+| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
+| [`server.port`](../attributes-registry/server.md) | int | Server port number. [4] | `80`; `8080`; `443` | Conditionally Required: [5] |
 
 **[1]:** The value SHOULD be normalized to lowercase.
 

diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md
@@ -32,8 +32,8 @@ If the endpoint id is not available, the span name SHOULD be the `http.request.m
 | [`db.operation`](database-spans.md) | string | The endpoint identifier for the request. [4] | `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: [5] |
 | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [6] | `GET`; `POST`; `HEAD` | Required |
-| [`server.address`](../general/attributes.md) | string | Name of the database host. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
-| [`server.port`](../general/attributes.md) | int | Server port number. [8] | `80`; `8080`; `443` | Conditionally Required: [9] |
+| [`server.address`](../attributes-registry/server.md) | string | Name of the database host. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
+| [`server.port`](../attributes-registry/server.md) | int | Server port number. [8] | `80`; `8080`; `443` | Conditionally Required: [9] |
 | [`url.full`](../attributes-registry/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [10] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required |
 
 **[1]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header.

diff --git a/docs/general/attributes.md b/docs/general/attributes.md
@@ -66,11 +66,11 @@ identify the transport, then setting [`network.transport`](#other-network-attrib
 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 server -->
+<!-- semconv general.server -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `server.address` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
-| `server.port` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Server port number. [2] | `80`; `8080`; `443` | Recommended |
+| [`server.address`](../attributes-registry/server.md) | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
+| [`server.port`](../attributes-registry/server.md) | int | Server port number. [2] | `80`; `8080`; `443` | Recommended |
 
 **[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available.
 
@@ -103,11 +103,11 @@ For Unix domain socket, `server.address` attribute represents remote endpoint ad
 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 client -->
+<!-- semconv general.client -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `client.address` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
-| `client.port` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Client port number. [2] | `65123` | Recommended |
+| [`client.address`](../attributes-registry/client.md) | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
+| [`client.port`](../attributes-registry/client.md) | int | Client port number. [2] | `65123` | Recommended |
 
 **[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries,  for example proxies, if it's available.
 
@@ -125,11 +125,11 @@ This also covers unidirectional UDP flows and peer-to-peer communication where t
 
 #### Source
 
-<!-- semconv source -->
+<!-- semconv general.source -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `source.address` | string | Source address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `source.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
-| `source.port` | int | Source port number | `3389`; `2888` | Recommended |
+| [`source.address`](../attributes-registry/source.md) | string | Source address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `source.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
+| [`source.port`](../attributes-registry/source.md) | int | Source port number | `3389`; `2888` | Recommended |
 
 **[1]:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries, for example proxies, if it's available.
 <!-- endsemconv -->
@@ -138,11 +138,11 @@ This also covers unidirectional UDP flows and peer-to-peer communication where t
 
 Destination fields capture details about the receiver of a network exchange/packet.
 
-<!-- semconv destination -->
+<!-- semconv general.destination -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `destination.address` | string | Destination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `destination.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
-| `destination.port` | int | Destination port number | `3389`; `2888` | Recommended |
+| [`destination.address`](../attributes-registry/destination.md) | string | Destination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `destination.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended |
+| [`destination.port`](../attributes-registry/destination.md) | int | Destination port number | `3389`; `2888` | Recommended |
 
 **[1]:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries, for example proxies, if it's available.
 <!-- endsemconv -->
@@ -389,6 +389,7 @@ about the span.
 | [`code.function`](../attributes-registry/code.md) | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` | Recommended |
 | [`code.lineno`](../attributes-registry/code.md) | int | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `42` | Recommended |
 | [`code.namespace`](../attributes-registry/code.md) | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` | Recommended |
+| [`code.stacktrace`](../attributes-registry/code.md) | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | Opt-In |
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md