clean up and add env var

open-telemetry · Jun 15, 2023 · badf3de · badf3de
1 parent 1cdd204
commit badf3de
Show file tree

Hide file tree

Showing 4 changed files with 83 additions and 55 deletions.
diff --git a/semantic_conventions/http-common.yaml b/semantic_conventions/http-common.yaml
@@ -37,19 +37,22 @@ groups:
               brief: 'TRACE method.'
             - id: other
               value: "other"
-              brief: 'Any custom HTTP method that the instrumentation has no prior knowledge of.'
+              brief: 'Any HTTP method that the instrumentation has no prior knowledge of.'
         requirement_level: required
         brief: '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.method` attribute to `other` and SHOULD
-          populate the exact method passed by client on `http.request.original_method` attribute.
+          
+          General-purpose HTTP instrumentations SHOULD allow overriding the list of known HTTP methods with OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS environment variable,
+          containing a comma-separated list of case-sensitive known HTTP methods.
 
-          HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly.
+          If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `other` and, if it reports spans, MUST
+          populate the exact method passed in the request line on `http.request.method_original` span attribute.
+
+          HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly.
+          Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
       - id: response.status_code
         type: int
         requirement_level:

diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml
@@ -8,7 +8,7 @@ groups:
         These conventions can be used for http and https schemes
         and various HTTP versions like 1.1, 2 and SPDY.
     attributes:
-      - id: request.original_method
+      - id: request.method_original
         type: string
         requirement_level:
           conditionally_required: If and only if it's different than `http.request.method`.

diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md
@@ -86,12 +86,15 @@ SHOULD include the [application root](/specification/trace/semantic_conventions/
 
 **[2]:** 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.method` attribute to `other` and SHOULD
-populate the exact method passed by client on `http.request.original_method` attribute.
 
-HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly.
+General-purpose HTTP instrumentations SHOULD allow overriding the list of known HTTP methods with OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS environment variable,
+containing a comma-separated list of case-sensitive known HTTP methods.
+
+If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `other` and, if it reports spans, MUST
+populate the exact method passed in the request line on `http.request.method_original` span attribute.
+
+HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly.
+Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
 
 **[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
 
@@ -127,7 +130,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 | `POST` | POST method. |
 | `PUT` | PUT method. |
 | `TRACE` | TRACE method. |
-| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. |
+| `other` | Any HTTP method that the instrumentation has no prior knowledge of. |
 <!-- endsemconv -->
 
 ### Metric: `http.server.active_requests`
@@ -150,12 +153,15 @@ This metric is optional.
 
 **[1]:** 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.method` attribute to `other` and SHOULD
-populate the exact method passed by client on `http.request.original_method` attribute.
 
-HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly.
+General-purpose HTTP instrumentations SHOULD allow overriding the list of known HTTP methods with OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS environment variable,
+containing a comma-separated list of case-sensitive known HTTP methods.
+
+If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `other` and, if it reports spans, MUST
+populate the exact method passed in the request line on `http.request.method_original` span attribute.
+
+HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly.
+Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
 
 **[2]:** Determined by using the first of the following that applies
 
@@ -189,7 +195,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 | `POST` | POST method. |
 | `PUT` | PUT method. |
 | `TRACE` | TRACE method. |
-| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. |
+| `other` | Any HTTP method that the instrumentation has no prior knowledge of. |
 <!-- endsemconv -->
 
 ### Metric: `http.server.request.size`
@@ -219,12 +225,15 @@ SHOULD include the [application root](/specification/trace/semantic_conventions/
 
 **[2]:** 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.method` attribute to `other` and SHOULD
-populate the exact method passed by client on `http.request.original_method` attribute.
 
-HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly.
+General-purpose HTTP instrumentations SHOULD allow overriding the list of known HTTP methods with OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS environment variable,
+containing a comma-separated list of case-sensitive known HTTP methods.
+
+If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `other` and, if it reports spans, MUST
+populate the exact method passed in the request line on `http.request.method_original` span attribute.
+
+HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly.
+Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
 
 **[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
 
@@ -260,7 +269,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 | `POST` | POST method. |
 | `PUT` | PUT method. |
 | `TRACE` | TRACE method. |
-| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. |
+| `other` | Any HTTP method that the instrumentation has no prior knowledge of. |
 <!-- endsemconv -->
 
 ### Metric: `http.server.response.size`
@@ -290,12 +299,15 @@ SHOULD include the [application root](/specification/trace/semantic_conventions/
 
 **[2]:** 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.method` attribute to `other` and SHOULD
-populate the exact method passed by client on `http.request.original_method` attribute.
 
-HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly.
+General-purpose HTTP instrumentations SHOULD allow overriding the list of known HTTP methods with OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS environment variable,
+containing a comma-separated list of case-sensitive known HTTP methods.
+
+If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `other` and, if it reports spans, MUST
+populate the exact method passed in the request line on `http.request.method_original` span attribute.
+
+HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly.
+Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
 
 **[3]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
 
@@ -331,7 +343,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi
 | `POST` | POST method. |
 | `PUT` | PUT method. |
 | `TRACE` | TRACE method. |
-| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. |
+| `other` | Any HTTP method that the instrumentation has no prior knowledge of. |
 <!-- endsemconv -->
 
 ## HTTP Client
@@ -365,12 +377,15 @@ of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5,
 
 **[1]:** 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.method` attribute to `other` and SHOULD
-populate the exact method passed by client on `http.request.original_method` attribute.
 
-HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly.
+General-purpose HTTP instrumentations SHOULD allow overriding the list of known HTTP methods with OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS environment variable,
+containing a comma-separated list of case-sensitive known HTTP methods.
+
+If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `other` and, if it reports spans, MUST
+populate the exact method passed in the request line on `http.request.method_original` span attribute.
+
+HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly.
+Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
 
 **[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
 
@@ -399,7 +414,7 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup.
 | `POST` | POST method. |
 | `PUT` | PUT method. |
 | `TRACE` | TRACE method. |
-| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. |
+| `other` | Any HTTP method that the instrumentation has no prior knowledge of. |
 <!-- endsemconv -->
 
 ### Metric: `http.client.request.size`
@@ -425,12 +440,15 @@ This metric is optional.
 
 **[1]:** 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.method` attribute to `other` and SHOULD
-populate the exact method passed by client on `http.request.original_method` attribute.
 
-HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly.
+General-purpose HTTP instrumentations SHOULD allow overriding the list of known HTTP methods with OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS environment variable,
+containing a comma-separated list of case-sensitive known HTTP methods.
+
+If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `other` and, if it reports spans, MUST
+populate the exact method passed in the request line on `http.request.method_original` span attribute.
+
+HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly.
+Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
 
 **[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
 
@@ -459,7 +477,7 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup.
 | `POST` | POST method. |
 | `PUT` | PUT method. |
 | `TRACE` | TRACE method. |
-| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. |
+| `other` | Any HTTP method that the instrumentation has no prior knowledge of. |
 <!-- endsemconv -->
 
 ### Metric: `http.client.response.size`
@@ -485,12 +503,15 @@ This metric is optional.
 
 **[1]:** 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.method` attribute to `other` and SHOULD
-populate the exact method passed by client on `http.request.original_method` attribute.
 
-HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a standard (or documented elsewhere) HTTP method name exactly.
+General-purpose HTTP instrumentations SHOULD allow overriding the list of known HTTP methods with OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS environment variable,
+containing a comma-separated list of case-sensitive known HTTP methods.
+
+If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `other` and, if it reports spans, MUST
+populate the exact method passed in the request line on `http.request.method_original` span attribute.
+
+HTTP method names are case-sensitive and `http.request.method` attribute value MUST match a known HTTP method name exactly.
+Instrumentations for specific web frameworks that consider HTTP methods to be case insensitive, SHOULD populate a canonical equivalent.
 
 **[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
 
@@ -519,7 +540,7 @@ SHOULD NOT be set if capturing it would require an extra DNS lookup.
 | `POST` | POST method. |
 | `PUT` | PUT method. |
 | `TRACE` | TRACE method. |
-| `other` | Any custom HTTP method that the instrumentation has no prior knowledge of. |
+| `other` | Any HTTP method that the instrumentation has no prior knowledge of. |
 <!-- endsemconv -->
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md