BREAKING: Introduce common url.* attributes, and improve use of namespacing under http.* (open-telemetry#3355)

Author: lmolkova

schemas/1.21.0

@@ -36,6 +36,15 @@ versions:
               net.host.carrier.mcc: network.carrier.mcc
               net.host.carrier.mnc: network.carrier.mnc
               net.host.carrier.icc: network.carrier.icc
+        # https://github.com/open-telemetry/opentelemetry-specification/pull/3355
+        - rename_attributes:
+            attribute_map:
+              http.method: http.request.method
+              http.status_code: http.response.status_code
+              http.scheme: url.scheme
+              http.url: url.full
+              http.request_content_length: http.request.body.size
+              http.response_content_length: http.response.body.size  
   1.20.0:
     spans:
       changes:

semantic_conventions/deprecated/http.yaml

@@ -0,0 +1,41 @@
+groups:
+  - id: attributes.http.deprecated
+    type: attribute_group
+    brief: "Describes deprecated HTTP attributes."
+    prefix: http
+    attributes:
+      - id: method
+        type: string
+        brief: 'Deprecated, use `http.request.method` instead.'
+        stability: deprecated
+        examples: ["GET", "POST", "HEAD"]
+      - id: status_code
+        type: int
+        brief: 'Deprecated, use `http.response.status_code` instead.'
+        stability: deprecated
+        examples: [200]
+      - id: scheme
+        type: string
+        brief: 'Deprecated, use `url.scheme` instead.'
+        stability: deprecated
+        examples: ['http', 'https']
+      - id: url
+        type: string
+        brief: 'Deprecated, use `url.full` instead.'
+        stability: deprecated
+        examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv']
+      - id: target
+        type: string
+        brief: 'Deprecated, use `url.path` and `url.query` instead.'
+        stability: deprecated
+        examples: ['/search?q=OpenTelemetry#SemConv']
+      - id: request_content_length
+        type: int
+        brief: 'Deprecated, use `http.request.body.size` instead.'
+        stability: deprecated
+        examples: 3495
+      - id: response_content_length
+        type: int
+        brief: 'Deprecated, use `http.response.body.size` instead.'
+        stability: deprecated
+        examples: 3495

semantic_conventions/http-common.yaml

@@ -4,12 +4,12 @@ groups:
     brief: "Describes HTTP attributes."
     prefix: http
     attributes:
-      - id: method
+      - id: request.method
         type: string
         requirement_level: required
         brief: 'HTTP request method.'
         examples: ["GET", "POST", "HEAD"]
-      - id: status_code
+      - id: response.status_code
         type: int
         requirement_level:
           conditionally_required: If and only if one was received/sent.
@@ -53,11 +53,6 @@ groups:
     type: attribute_group
     brief: 'HTTP Server spans attributes'
     attributes:
-      - id: scheme
-        type: string
-        brief: 'The URI scheme identifying the used protocol.'
-        requirement_level: required
-        examples: ["http", "https"]
       - id: route
         type: string
         requirement_level:
@@ -96,3 +91,6 @@ groups:
           - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
           - Port identifier of the `Host` header
+      - ref: url.scheme
+        requirement_level: required
+        examples: ["http", "https"]

semantic_conventions/metrics/http.yaml

@@ -8,8 +8,8 @@ groups:
     extends: attributes.http.server
     attributes:
       # todo (lmolkova) build tools don't populate grandparent attributes
-      - ref: http.method
-      - ref: http.status_code
+      - ref: http.request.method
+      - ref: http.response.status_code
       - ref: network.protocol.name
       - ref: network.protocol.version
 
@@ -20,8 +20,10 @@ groups:
     instrument: updowncounter
     unit: "{request}"
     attributes:
-      - ref: http.method
-      - ref: http.scheme
+      - ref: http.request.method
+      - ref: url.scheme
+        requirement_level: required
+        examples: ["http", "https"]
       - ref: server.address
         requirement_level: required
         brief: >
@@ -60,8 +62,8 @@ groups:
     # TODO (trask) below attributes are identical to above in metric.http.server.duration
     attributes:
       # todo (lmolkova) build tools don't populate grandparent attributes
-      - ref: http.method
-      - ref: http.status_code
+      - ref: http.request.method
+      - ref: http.response.status_code
       - ref: network.protocol.name
       - ref: network.protocol.version
 
@@ -74,8 +76,8 @@ groups:
     extends: attributes.http.server
     # TODO (trask) below attributes are identical to above in metric.http.server.duration
     attributes:
-      - ref: http.method
-      - ref: http.status_code
+      - ref: http.request.method
+      - ref: http.response.status_code
       - ref: network.protocol.name
       - ref: network.protocol.version
 
@@ -87,12 +89,11 @@ groups:
     unit: "s"
     extends: attributes.http.client
     attributes:
-      - ref: http.method
-      - ref: http.status_code
+      - ref: http.request.method
+      - ref: http.response.status_code
       - ref: network.protocol.name
       - ref: network.protocol.version
       - ref: server.socket.address
-
   - id: metric.http.client.request.size
     type: metric
     metric_name: http.client.request.size
@@ -102,8 +103,8 @@ groups:
     extends: attributes.http.client
     # TODO (trask) below attributes are identical to above in metric.http.client.duration
     attributes:
-      - ref: http.method
-      - ref: http.status_code
+      - ref: http.request.method
+      - ref: http.response.status_code
       - ref: network.protocol.name
       - ref: network.protocol.version
       - ref: server.socket.address
@@ -117,8 +118,8 @@ groups:
     extends: attributes.http.client
     # TODO (trask) below attributes are identical to above in metric.http.client.duration
     attributes:
-      - ref: http.method
-      - ref: http.status_code
+      - ref: http.request.method
+      - ref: http.response.status_code
       - ref: network.protocol.name
       - ref: network.protocol.version
       - ref: server.socket.address

semantic_conventions/trace/http.yaml

@@ -8,21 +8,21 @@ groups:
         These conventions can be used for http and https schemes
         and various HTTP versions like 1.1, 2 and SPDY.
     attributes:
-      - id: request_content_length
+      - id: request.body.size
         type: int
         brief: >
           The size of the request payload body in bytes. This is the number of bytes transferred excluding headers and
           is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length)
           header. For requests using transport encoding, this should be the compressed size.
         examples: 3495
-      - id: response_content_length
+      - id: response.body.size
         type: int
         brief: >
           The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and
           is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length)
           header. For requests using transport encoding, this should be the compressed size.
         examples: 3495
-      - ref: http.method
+      - ref: http.request.method
         sampling_relevant: true
       - ref: network.transport
         requirement_level:
@@ -37,17 +37,6 @@ groups:
     span_kind: client
     brief: 'Semantic Convention for HTTP Client'
     attributes:
-      - id: url
-        type: string
-        requirement_level: required
-        brief: >
-            Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`.
-            Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless.
-        note: >
-          `http.url` MUST NOT contain credentials passed via URL in form of `https://username:[email protected]/`.
-          In such case the attribute's value should be `https://www.example.com/`.
-        sampling_relevant: true
-        examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv']
       - id: resend_count
         type: int
         brief: >
@@ -85,6 +74,10 @@ groups:
       - ref: server.socket.domain
       - ref: server.socket.address
       - ref: server.socket.port
+      - ref: url.full
+        sampling_relevant: true
+        requirement_level: required
+
 
   - id: trace.http.server
     prefix: http
@@ -93,14 +86,6 @@ groups:
     span_kind: server
     brief: 'Semantic Convention for HTTP Server'
     attributes:
-      - id: target
-        type: string
-        brief: 'The full request target as passed in a HTTP request line or equivalent.'
-        requirement_level: required
-        sampling_relevant: true
-        examples: ['/users/12314/?q=ddds']
-      - ref: http.scheme
-        sampling_relevant: true
       - ref: server.address
         requirement_level: required
         sampling_relevant: true
@@ -149,3 +134,12 @@ groups:
             Otherwise, the immediate client peer port.
       - ref: client.socket.address
       - ref: client.socket.port
+      - ref: url.path
+        requirement_level: required
+        sampling_relevant: true
+      - ref: url.query
+        sampling_relevant: true
+      - ref: url.scheme
+        sampling_relevant: true
+        requirement_level: required
+        examples: ["http", "https"]

semantic_conventions/url.yaml

@@ -0,0 +1,39 @@
+groups:
+  - id: url
+    brief: Attributes describing URL.
+    type: attribute_group
+    prefix: url
+    attributes:
+      - id: scheme
+        type: string
+        brief: 'The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol.'
+        examples: ["https", "ftp", "telnet"]
+      - id: full
+        type: string
+        brief: Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986)
+        note: >
+          For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment
+          is not transmitted over HTTP, but if it is known, it should be included nevertheless.
+
+          `url.full` MUST NOT contain credentials passed via URL in form of `https://username:[email protected]/`.
+          In such case username and password should be redacted and attribute's value should be `https://REDACTED:[email protected]/`.
+
+          `url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed)
+          and SHOULD NOT be validated or modified except for sanitizing purposes.
+        examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv', '//localhost']
+        tag: sensitive-information
+      - id: path
+        type: string
+        brief: 'The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component'
+        examples: ['/search']
+        note: When missing, the value is assumed to be `/`
+      - id: query
+        type: string
+        brief: 'The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component'
+        examples: ["q=OpenTelemetry"]
+        note: Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it.
+        tag: sensitive-information
+      - id: fragment
+        type: string
+        brief: 'The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component'
+        examples: ["SemConv"]