Merge branch 'main' into feat/rpc-metrics-yaml

CHANGELOG.md

@@ -7,8 +7,6 @@ release.
 
 ## Unreleased
 
-- Updated AWS Java Lambda guidance - using system properties.
-
 ### Semantic Conventions
 
 - Add GCP Bare Metal Solution as a cloud platform
@@ -36,7 +34,7 @@ release.
   ([#3402](https://github.com/open-telemetry/opentelemetry-specification/pull/3402))
     BREAKING: rename `net.peer.name` to `server.address` on client side and to `client.address` on server side,
      `net.peer.port` to `server.port` on client side and to `client.port` on server side,
-     `net.host.name` and `net.host.port` to `server.name` and `server.port` (since `net.host.*` attributes only applied to server instrumentation)
+     `net.host.name` and `net.host.port` to `server.address` and `server.port` (since `net.host.*` attributes only applied to server instrumentation),
      `net.sock.peer.addr` to `server.socket.address` on client side and to `client.socket.address` on server side,
      `net.sock.peer.port` to `server.socket.port` on client side and to `client.socket.port` on server side,
      `net.sock.peer.name` to `server.socket.domain` (since `net.sock.peer.name` only applied to client instrumentation),
@@ -89,3 +87,12 @@ release.
 - Change `server.address` and `server.port` requirement levels on HTTP server metrics
   from `required` to `opt_in`.
   ([#109](https://github.com/open-telemetry/semantic-conventions/pull/109))
+- Updated AWS Java Lambda guidance - using system properties.
+  ([#27](https://github.com/open-telemetry/semantic-conventions/pull/27))
+- Limit `http.request.method` values to a closed set of known values,
+  introduce `http.request.method_original` for the original value.
+  ([#17](https://github.com/open-telemetry/opentelemetry-specification/pull/17))
+- Mark service.version as stable.
+  ([#106](https://github.com/open-telemetry/semantic-conventions/pull/106))
+- Mark initial set of HTTP semantic conventions as frozen
+  ([#105](https://github.com/open-telemetry/semantic-conventions/pull/105))  

semantic_conventions/http-common.yaml

@@ -5,10 +5,58 @@ groups:
     prefix: http
     attributes:
       - id: request.method
-        type: string
+        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 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 value SHOULD be "known" to the instrumentation.
+          By default, this convention defines "known" methods as the ones listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
+          and the PATCH method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html).
+
+          If the HTTP request method is not known to instrumentation, it MUST set the `http.request.method` attribute to `_OTHER` and, except if reporting a metric, MUST
+          set the exact method received in the request line as value of the `http.request.method_original` attribute.
+
+          If the HTTP instrumentation could end up converting valid HTTP request methods to `_OTHER`, then it MUST provide a way to override
+          the list of known HTTP methods. If this override is done via environment variable, then the environment variable MUST be named
+          OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS and support a comma-separated list of case-sensitive known HTTP methods
+          (this list MUST be a full override of the default known method, it is not a list of known methods in addition to the defaults).
+
+          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.
+          Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
       - id: response.status_code
         type: int
         requirement_level:
@@ -25,7 +73,7 @@ groups:
   - id: attributes.http.client
     prefix: http
     type: attribute_group
-    brief: 'HTTP client attributes'
+    brief: 'HTTP Client attributes'
     attributes:
       - ref: server.address
         requirement_level: required
@@ -51,7 +99,7 @@ groups:
   - id: attributes.http.server
     prefix: http
     type: attribute_group
-    brief: 'HTTP server attributes'
+    brief: 'HTTP Server attributes'
     attributes:
       - id: route
         type: string

semantic_conventions/metrics/process-runtime-jvm-metrics-experimental.yaml

@@ -10,7 +10,7 @@ groups:
   - id: metric.process.runtime.jvm.system.cpu.utilization
     type: metric
     metric_name: process.runtime.jvm.system.cpu.utilization
-    brief: "Recent CPU utilization for the whole system."
+    brief: "Recent CPU utilization for the whole system as reported by the JVM."
     note: >
       The value range is [0.0,1.0].
       This utilization is not defined as being for the specific interval since last measurement
@@ -22,7 +22,7 @@ groups:
   - id: metric.process.runtime.jvm.system.cpu.load_1m
     type: metric
     metric_name: process.runtime.jvm.system.cpu.load_1m
-    brief: "Average CPU load of the whole system for the last minute."
+    brief: "Average CPU load of the whole system for the last minute as reported by the JVM."
     note: >
       The value range is [0,n], where n is the number of CPU cores - or a negative number if the value is not available.
       This utilization is not defined as being for the specific interval since last measurement

semantic_conventions/metrics/process-runtime-jvm-metrics.yaml

@@ -117,14 +117,14 @@ groups:
   - id: metric.process.runtime.jvm.cpu.time
     type: metric
     metric_name: process.runtime.jvm.cpu.time
-    brief: "CPU time used by the process."
+    brief: "CPU time used by the process as reported by the JVM."
     instrument: counter
     unit: "s"
 
   - id: metric.process.runtime.jvm.cpu.recent_utilization
     type: metric
     metric_name: process.runtime.jvm.cpu.recent_utilization
-    brief: "Recent CPU utilization for the process."
+    brief: "Recent CPU utilization for the process as reported by the JVM."
     note: >
       The value range is [0.0,1.0].
       This utilization is not defined as being for the specific interval since last measurement

semantic_conventions/resource/service.yaml

@@ -16,3 +16,8 @@ groups:
           with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`.
           If `process.executable.name` is not available, the value MUST be set to `unknown_service`.
         examples: ["shoppingcart"]
+      - id: version
+        type: string
+        brief: >
+          The version string of the service API or implementation. The format is not defined by these conventions.
+        examples: ["2.0.0", "a01dbef8a"]

semantic_conventions/resource/service_experimental.yaml

@@ -35,8 +35,3 @@ groups:
           (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122
           for more recommendations).
         examples: ["my-k8s-pod-deployment-1", "627cc493-f310-47de-96bd-71410b7dec09"]
-      - id: version
-        type: string
-        brief: >
-          The version string of the service API or implementation.
-        examples: ["2.0.0"]

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_original
+        type: string
+        requirement_level:
+          conditionally_required: If and only if it's different than `http.request.method`.
+        brief: Original HTTP method sent by the client in the request line.
+        examples: ["GeT", "ACL", "foo"]
       - id: request.body.size
         type: int
         brief: >
@@ -87,7 +93,7 @@ groups:
     brief: 'Semantic Convention for HTTP Server'
     attributes:
       - ref: server.address
-        requirement_level: required
+        requirement_level: recommended
         sampling_relevant: true
         brief: >
           Name of the local HTTP server that received the request.
@@ -104,7 +110,7 @@ groups:
       - ref: server.port
         sampling_relevant: true
         requirement_level:
-          conditionally_required: If not default (`80` for `http` scheme, `443` for `https`).
+          recommended: If not default (`80` for `http` scheme, `443` for `https`).
         brief: >
           Port of the local HTTP server that received the request.
         note: |