BREAKING: Introduce common url.* attributes, and improve use of nam…

…espacing under `http.*` (#3355)

CHANGELOG.md

@@ -78,6 +78,15 @@ release.
   `net.host.connection.*` to `network.connection.*`, and
   `net.host.carrier.*` to `network.carrier.*`.
   ([#3426](https://github.com/open-telemetry/opentelemetry-specification/pull/3426))
+- BREAKING: Adopt ECS attributes in HTTP semantic conventions.
+  Renames: `http.method` to `http.request.method`,
+  `http.status_code` to `http.response.status_code`,
+  `http.request_content_length` to `http.request.body.size`,
+  `http.response_content_length` to `http.response.body.size`,
+  `http.url` to `url.full`,
+  `http.scheme` to `url.scheme`,
+  and removes `http.target` breaking it down to `http.target` to `url.path`, `url.query`, and `url.fragment`.
+  ([#3355](https://github.com/open-telemetry/opentelemetry-specification/pull/3355))
 
 ### Compatibility
 

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"]

specification/common/attribute-naming.md

@@ -44,7 +44,7 @@ Names SHOULD follow these rules:
   purpose should primarily drive the decision about forming nested namespaces.
 
 - For each multi-word dot-delimited component of the attribute name separate the
-  words by underscores (i.e. use snake_case). For example `http.status_code`
+  words by underscores (i.e. use snake_case). For example `http.response.status_code`
   denotes the status code in the http namespace.
 
 - Names SHOULD NOT coincide with namespaces. For example if
@@ -96,8 +96,8 @@ denote old attribute names in rename operations).
 - Semantic conventions exist for four areas: for Resource, Span, Log, and Metric
   attribute names. In addition, for spans we have two more areas: Event and Link
   attribute names. Identical namespaces or names in all these areas MUST have
-  identical meanings. For example the `http.method` span attribute name denotes
-  exactly the same concept as the `http.method` metric attribute, has the same
+  identical meanings. For example the `http.request.method` span attribute name denotes
+  exactly the same concept as the `http.request.method` metric attribute, has the same
   data type and the same set of possible values (in both cases it records the
   value of the HTTP protocol's request method as a string).
 

specification/common/attribute-requirement-level.md

@@ -38,7 +38,7 @@ For example, [Database semantic convention](../trace/semantic_conventions/databa
 
 ## Required
 
-All instrumentations MUST populate the attribute. A semantic convention defining a Required attribute expects an absolute majority of instrumentation libraries and applications are able to efficiently retrieve and populate it, and can additionally meet requirements for cardinality, security, and any others specific to the signal defined by the convention. `http.method` is an example of a Required attribute.
+All instrumentations MUST populate the attribute. A semantic convention defining a Required attribute expects an absolute majority of instrumentation libraries and applications are able to efficiently retrieve and populate it, and can additionally meet requirements for cardinality, security, and any others specific to the signal defined by the convention. `http.request.method` is an example of a Required attribute.
 
 _Note: Consumers of telemetry can detect if a telemetry item follows a specific semantic convention by checking for the presence of a `Required` attribute defined by such convention. For example, the presence of the `db.system` attribute on a span can be used as an indication that the span follows database semantics._
 
@@ -71,4 +71,4 @@ Here are several examples of expensive operations to be avoided by default:
 
 - DNS lookups to populate `server.address` when only an IP address is available to the instrumentation. Caching lookup results does not solve the issue for all possible cases and should be avoided by default too.
 - forcing an `http.route` calculation before the HTTP framework calculates it
-- reading response stream to find `http.response_content_length` when `Content-Length` header is not available
+- reading response stream to find `http.response.body.size` when `Content-Length` header is not available

specification/common/url.md

@@ -0,0 +1,45 @@
+# Semantic conventions for URL
+
+**Status**: [Experimental](../document-status.md)
+
+This document defines semantic conventions that describe URL and its components.
+
+<details>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
+
+- [Attributes](#attributes)
+- [Sensitive information](#sensitive-information)
+
+<!-- tocstop -->
+
+</details>
+
+## Attributes
+
+<!-- semconv url -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Recommended |
+| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended |
+| `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` | Recommended |
+| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` | Recommended |
+| `url.fragment` | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | Recommended |
+
+**[1]:** 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.
+
+**[2]:** When missing, the value is assumed to be `/`
+
+**[3]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it.
+<!-- endsemconv -->
+
+## Sensitive information
+
+Capturing URL and its components MAY impose security risk. User and password information, when they are provided in [User Information](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1) subcomponent, MUST NOT be recorded.
+
+Instrumentations that are aware of specific sensitive query string parameters MUST scrub their values before capturing `url.query` attribute. For example, native instrumentation of a client library that passes credentials or user location in URL, must scrub corresponding properties.
+
+_Note: Applications and telemetry consumers should scrub sensitive information from URL attributes on collected telemetry. In systems unable to identify sensitive information, certain attribute values may be redacted entirely._