Deprecate tls.client.server_name attribute in favor of common `serv…

…er.address` (open-telemetry#1216) Co-authored-by: Joao Grassi <[email protected]>
maryliag · Jul 30, 2024 · dc21e82 · dc21e82
1 parent 3472ed2
commit dc21e82
Show file tree

Hide file tree

Showing 5 changed files with 31 additions and 6 deletions.
diff --git a/.chloggen/1216.yaml b/.chloggen/1216.yaml
@@ -0,0 +1,5 @@
+change_type: breaking
+component: tls
+note: >
+  Deprecate `tls.client.server_name attribute` in favor of common `server.address`.
+issues: [ 1211, 1216 ]
diff --git a/docs/attributes-registry/tls.md b/docs/attributes-registry/tls.md
@@ -6,6 +6,9 @@
 
 # TLS
 
+- [Tls](#tls-attributes)
+- [Tls Deprecated](#tls-deprecated-attributes)
+
 ## TLS Attributes
 
 This document defines semantic convention attributes in the TLS namespace.
@@ -22,7 +25,6 @@ This document defines semantic convention attributes in the TLS namespace.
 | `tls.client.ja3`               | string   | A hash that identifies clients based on how they perform an SSL/TLS handshake.                                                                                                                                                      | `d4e5b18d6b55c71272893221c96ba240`                                                            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `tls.client.not_after`         | string   | Date/Time indicating when client certificate is no longer considered valid.                                                                                                                                                         | `2021-01-01T00:00:00.000Z`                                                                    | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `tls.client.not_before`        | string   | Date/Time indicating when client certificate is first considered valid.                                                                                                                                                             | `1970-01-01T00:00:00.000Z`                                                                    | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| `tls.client.server_name`       | string   | Also called an SNI, this tells the server which hostname to which the client is attempting to connect to.                                                                                                                           | `opentelemetry.io`                                                                            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `tls.client.subject`           | string   | Distinguished name of subject of the x.509 certificate presented by the client.                                                                                                                                                     | `CN=myclient, OU=Documentation Team, DC=example, DC=com`                                      | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `tls.client.supported_ciphers` | string[] | Array of ciphers offered by the client during the client hello.                                                                                                                                                                     | `["TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "..."]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `tls.curve`                    | string   | String indicating the curve used for the given cipher, when applicable                                                                                                                                                              | `secp256r1`                                                                                   | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -50,3 +52,11 @@ This document defines semantic convention attributes in the TLS namespace.
 | ----- | ----------- | ---------------------------------------------------------------- |
 | `ssl` | ssl         | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `tls` | tls         | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+## TLS Deprecated Attributes
+
+Describes deprecated `tls` attributes.
+
+| Attribute                | Type   | Description                               | Examples           | Stability                                                                                   |
+| ------------------------ | ------ | ----------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------- |
+| `tls.client.server_name` | string | Deprecated, use `server.address` instead. | `opentelemetry.io` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `server.address. |
diff --git a/model/registry/deprecated/tls.yaml b/model/registry/deprecated/tls.yaml
@@ -0,0 +1,11 @@
+groups:
+  - id: registry.tls.deprecated
+    type: attribute_group
+    brief: Describes deprecated `tls` attributes.
+    attributes:
+      - id: tls.client.server_name
+        type: string
+        stability: experimental
+        deprecated: "Replaced by `server.address."
+        brief: "Deprecated, use `server.address` instead."
+        examples: ["opentelemetry.io"]
diff --git a/model/registry/tls.yaml b/model/registry/tls.yaml
@@ -74,11 +74,6 @@ groups:
         stability: experimental
         brief: "Date/Time indicating when client certificate is first considered valid."
         examples: ["1970-01-01T00:00:00.000Z"]
-      - id: client.server_name
-        type: string
-        stability: experimental
-        brief: "Also called an SNI, this tells the server which hostname to which the client is attempting to connect to."
-        examples: ["opentelemetry.io"]
       - id: client.subject
         type: string
         stability: experimental

diff --git a/schema-next.yaml b/schema-next.yaml
@@ -4,6 +4,10 @@ versions:
   next:
     all:
       changes:
+        # https://github.com/open-telemetry/semantic-conventions/pull/1216
+        - rename_attributes:
+          attribute_map:
+            tls.client.server_name: server.address
         # https://github.com/open-telemetry/semantic-conventions/pull/1075
         - rename_attributes:
             attribute_map: