From d98019c07f6012e0067bb06f59764c89aacc8c5c Mon Sep 17 00:00:00 2001
From: Trask Stalnaker <trask.stalnaker@gmail.com>
Date: Fri, 27 Oct 2023 13:34:08 -0700
Subject: [PATCH] Update body size attribute and metric definitions

---
 CHANGELOG.md             |  2 ++
 model/metrics/http.yaml  | 16 ++++------------
 model/registry/http.yaml | 16 ++++++++--------
 3 files changed, 14 insertions(+), 20 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c85977b6f9..9a72c721bf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,6 +30,8 @@ release.
   ([#384](https://github.com/open-telemetry/semantic-conventions/pull/384))
 - BREAKING: Remove `total` from list of well-known values of `system.memory.state` attribute.
   ([#409](https://github.com/open-telemetry/semantic-conventions/pull/409))
+- Updates HTTP body size attributes and metric definitions to be the number of bytes transferred.
+  ([#461](https://github.com/open-telemetry/semantic-conventions/pull/461))
 
 ### Features
 
diff --git a/model/metrics/http.yaml b/model/metrics/http.yaml
index b1801ed20b..116631abde 100644
--- a/model/metrics/http.yaml
+++ b/model/metrics/http.yaml
@@ -73,9 +73,7 @@ groups:
     instrument: histogram
     unit: "By"
     note: >
-      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.
+      This is the same as the `Content-Length` header value when that header is present and when the response body was fully transferred.
     extends: metric_attributes.http.server
 
   - id: metric.http.server.response.body.size
@@ -85,9 +83,7 @@ groups:
     instrument: histogram
     unit: "By"
     note: >
-      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.
+      This is the same as the `Content-Length` header value when that header is present and when the response body was fully transferred.
     extends: metric_attributes.http.server
 
   - id: metric.http.client.request.duration
@@ -105,9 +101,7 @@ groups:
     instrument: histogram
     unit: "By"
     note: >
-      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.
+      This is the same as the `Content-Length` header value when that header is present and when the request body was fully transferred.
     extends: metric_attributes.http.client
 
   - id: metric.http.client.response.body.size
@@ -117,7 +111,5 @@ groups:
     instrument: histogram
     unit: "By"
     note: >
-      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.
+      This is the same as the `Content-Length` header value when that header is present and when the response body was fully transferred.
     extends: metric_attributes.http.client
diff --git a/model/registry/http.yaml b/model/registry/http.yaml
index 4264ae3251..c63ef7bf72 100644
--- a/model/registry/http.yaml
+++ b/model/registry/http.yaml
@@ -6,11 +6,11 @@ groups:
     attributes:
       - 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.
+        brief: Size of the HTTP request body.
         examples: 3495
+        stability: experimental # this should not be marked stable with other HTTP attributes
+        note: >
+          This is the same as the `Content-Length` header value when that header is present and when the request body was fully transferred.
       - id: request.header
         type: template[string[]]
         brief: >
@@ -92,11 +92,11 @@ groups:
         examples: 3
       - 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.
+        brief: Size of the HTTP response body.
         examples: 3495
+        stability: experimental # this should not be marked stable with other HTTP attributes
+        note: >
+          This is the same as the `Content-Length` header value when that header is present and when the response body was fully transferred.
       - id: response.header
         type: template[string[]]
         brief: >