Limit HTTP request method cardinality: canonical method (Option B/D)

semantic_conventions/deprecated/http.yaml

@@ -6,7 +6,7 @@ groups:
     attributes:
       - id: method
         type: string
-        brief: 'Deprecated, use `http.request.method` instead.'
+        brief: 'Deprecated, use `http.request.canonical_method` and `http.request.method` instead.'
         stability: deprecated
         examples: ["GET", "POST", "HEAD"]
       - id: status_code

semantic_conventions/http-common.yaml

@@ -4,11 +4,51 @@ groups:
     brief: "Describes HTTP attributes."
     prefix: http
     attributes:
-      - id: request.method
-        type: string
-        requirement_level: required
-        brief: 'HTTP request method.'
+      - id: request.canonical_method
+        type:
+          allow_custom_values: true
+          members:
+            - id: connect
+              value: "CONNECT"
+              brief: 'CONNECT method.'
+            - id: delete
+              value: "DELETE"
+              brief: 'DELETE method.'
+            - id: get
+              value: "GET"
+              brief: 'GET method.'
+            - id: head
+              value: "HEAD"
+              brief: 'HEAD method.'
+            - id: options
+              value: "OPTIONS"
+              brief: 'OPTIONS method.'
+            - id: patch
+              value: "PATCH"
+              brief: 'PATCH method.'
+            - id: post
+              value: "POST"
+              brief: 'POST method.'
+            - id: put
+              value: "PUT"
+              brief: 'PUT method.'
+            - id: trace
+              value: "TRACE"
+              brief: 'TRACE method.'
+            - id: other
+              value: "other"
+              brief: 'Any custom HTTP method that the instrumentation has no prior knowledge of.'
+        brief: 'Canonical HTTP request method.'
         examples: ["GET", "POST", "HEAD"]
+        note: |
+          HTTP request method SHOULD be one of the methods defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
+          or the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
+          Instrumentation MAY additionally support the closed set of custom HTTP methods defined in
+          [HTTP method registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) or a private registry.
+          If the HTTP request method is not known to the instrumentation, it MUST set the `http.request.canonical_method` attribute to `other` and SHOULD
+          populate the exact method passed by client on `http.request.method` attribute.
+
+          HTTP method names are case-sensitive and `http.request.canonical_method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly.
       - id: response.status_code
         type: int
         requirement_level:

semantic_conventions/metrics/http.yaml

@@ -8,7 +8,8 @@ groups:
     extends: attributes.http.server
     attributes:
       # todo (lmolkova) build tools don't populate grandparent attributes
-      - ref: http.request.method
+      - ref: http.request.canonical_method
+        requirement_level: required
       - ref: http.response.status_code
       - ref: network.protocol.name
       - ref: network.protocol.version
@@ -20,7 +21,8 @@ groups:
     instrument: updowncounter
     unit: "{request}"
     attributes:
-      - ref: http.request.method
+      - ref: http.request.canonical_method
+        requirement_level: required
       - ref: url.scheme
         requirement_level: required
         examples: ["http", "https"]
@@ -62,7 +64,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.request.method
+      - ref: http.request.canonical_method
+        requirement_level: required
       - ref: http.response.status_code
       - ref: network.protocol.name
       - ref: network.protocol.version
@@ -76,7 +79,8 @@ groups:
     extends: attributes.http.server
     # TODO (trask) below attributes are identical to above in metric.http.server.duration
     attributes:
-      - ref: http.request.method
+      - ref: http.request.canonical_method
+        requirement_level: required
       - ref: http.response.status_code
       - ref: network.protocol.name
       - ref: network.protocol.version
@@ -89,7 +93,8 @@ groups:
     unit: "s"
     extends: attributes.http.client
     attributes:
-      - ref: http.request.method
+      - ref: http.request.canonical_method
+        requirement_level: required
       - ref: http.response.status_code
       - ref: network.protocol.name
       - ref: network.protocol.version
@@ -103,7 +108,8 @@ groups:
     extends: attributes.http.client
     # TODO (trask) below attributes are identical to above in metric.http.client.duration
     attributes:
-      - ref: http.request.method
+      - ref: http.request.canonical_method
+        requirement_level: required
       - ref: http.response.status_code
       - ref: network.protocol.name
       - ref: network.protocol.version
@@ -118,7 +124,8 @@ groups:
     extends: attributes.http.client
     # TODO (trask) below attributes are identical to above in metric.http.client.duration
     attributes:
-      - ref: http.request.method
+      - ref: http.request.canonical_method
+        requirement_level: required
       - ref: http.response.status_code
       - ref: network.protocol.name
       - ref: network.protocol.version

semantic_conventions/trace/http.yaml

@@ -8,6 +8,12 @@ groups:
         These conventions can be used for http and https schemes
         and various HTTP versions like 1.1, 2 and SPDY.
     attributes:
+      - id: request.method
+        type: string
+        requirement_level:
+          conditionally_required: If different than `http.request.canonical_method`, recommended otherwise.
+        brief: Original HTTP method sent by the client in the request line.
+        examples: ["GET", "ACL", "Patch"]
       - id: request.body.size
         type: int
         brief: >
@@ -22,7 +28,8 @@ groups:
           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.request.method
+      - ref: http.request.canonical_method
+        requirement_level: required
         sampling_relevant: true
       - ref: network.transport
         requirement_level: