proper warning and review

Author: lmolkova

docs/http/http-metrics.md

@@ -126,10 +126,14 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
 **[5]:** `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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
 
 **[6]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-> **Warning**: since this attribute may be based on HTTP headers, opting in to it may allow an attacker to trigger cardinality limits, degrading the usefulness of the metric.
+> **Warning**
+> Since this attribute may be based on HTTP headers, opting in to it may allow an attacker
+> to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[7]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-> **Warning**: since this attribute may be based on HTTP headers, opting in to it may allow an attacker to trigger cardinality limits, degrading the usefulness of the metric.
+> **Warning**
+> Since this attribute may be based on HTTP headers, opting in to it may allow an attacker
+> to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[8]:** The scheme of the original client request, if known (e.g. from [Forwarded](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
 
@@ -191,14 +195,14 @@ Instrumentations for specific web frameworks that consider HTTP methods to be ca
 Tracing instrumentations that do so, MUST also set `http.request.method_original` to the original value.
 
 **[2]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-
-> **Warning**: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
-to trigger cardinality limits, degrading the usefulness of the metric.
+> **Warning**
+> Since this attribute may be based on HTTP headers, opting in to it may allow an attacker
+> to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[3]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-
-> **Warning**: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
-to trigger cardinality limits, degrading the usefulness of the metric.
+> **Warning**
+> Since this attribute may be based on HTTP headers, opting in to it may allow an attacker
+> to trigger cardinality limits, degrading the usefulness of the metric.
 
 `http.request.method` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
 
@@ -283,10 +287,14 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
 **[5]:** `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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
 
 **[6]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-> **Warning**: since this attribute may be based on HTTP headers, opting in to it may allow an attacker to trigger cardinality limits, degrading the usefulness of the metric.
+> **Warning**
+> Since this attribute may be based on HTTP headers, opting in to it may allow an attacker
+> to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[7]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-> **Warning**: since this attribute may be based on HTTP headers, opting in to it may allow an attacker to trigger cardinality limits, degrading the usefulness of the metric.
+> **Warning**
+> Since this attribute may be based on HTTP headers, opting in to it may allow an attacker
+> to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[8]:** The scheme of the original client request, if known (e.g. from [Forwarded](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
 
@@ -379,10 +387,14 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin
 **[5]:** `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 has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
 
 **[6]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-> **Warning**: since this attribute may be based on HTTP headers, opting in to it may allow an attacker to trigger cardinality limits, degrading the usefulness of the metric.
+> **Warning**
+> Since this attribute may be based on HTTP headers, opting in to it may allow an attacker
+> to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[7]:** See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-> **Warning**: since this attribute may be based on HTTP headers, opting in to it may allow an attacker to trigger cardinality limits, degrading the usefulness of the metric.
+> **Warning**
+> Since this attribute may be based on HTTP headers, opting in to it may allow an attacker
+> to trigger cardinality limits, degrading the usefulness of the metric.
 
 **[8]:** The scheme of the original client request, if known (e.g. from [Forwarded](https://developer.mozilla.org/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-Proto](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Forwarded-Proto), or a similar header). Otherwise, the scheme of the immediate peer request.
 

docs/http/http-spans.md

@@ -301,13 +301,13 @@ HTTP requests sent to the same domain name may be handled by multiple applicatio
 For example, different versions of the same web-application can run side-by-side as independent applications behind the reverse proxy which routes request to one or another based on the request path.
 
 Instances of different HTTP server applications may run on the same physical host and share the same IP address, but listen to different TCP/UDP ports.
-In order to route request to a specific application, reverse proxies usually modify the [HTTP Host header][Host and authority] replacing the original value provided by the client with an actual proxied server name. This behavior depends on the reverse proxy configuration. In some cases, `Host` header is not used when routing request to a specific application, making it prone to having bogus content.
+In order to route the request to a specific application, reverse proxies usually modify the [HTTP Host header][Host and authority] replacing the original value provided by the client with an actual proxied server name. This behavior depends on the reverse proxy configuration. In some cases, the `Host` header is not used when routing request to a specific application, making it prone to having bogus content.
 
 HTTP server frameworks and their instrumentations have limited knowledge about the HTTP infrastructure and intermediaries that requests go through. In a general case, they can only use HTTP request properties such as request target or headers to populate `server.*` attributes.
 
 #### Setting `server.address` and `server.port` attributes
 
-In the context of HTTP server, `server.address` and `server.port` attributes capture the original host name and port. The are intended, whenever possible, to be the same on the client and server sides.
+In the context of HTTP server, `server.address` and `server.port` attributes capture the original host name and port. They are intended, whenever possible, to be the same on the client and server sides.
 
 HTTP server instrumentations SHOULD do the best effort when populating `server.address` and `server.port` attributes and SHOULD determine them by using the first of the following that applies:
 

model/metrics/http.yaml

@@ -6,18 +6,18 @@ groups:
     attributes:
       - ref: server.address
         requirement_level: opt_in
-        note: >
+        note: |
           See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-
-          > **Warning**: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
-          to trigger cardinality limits, degrading the usefulness of the metric.
+          > **Warning**
+          > Since this attribute may be based on HTTP headers, opting in to it may allow an attacker
+          > to trigger cardinality limits, degrading the usefulness of the metric.
       - ref: server.port
         requirement_level: opt_in
-        note: >
+        note: |
           See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-
-          > **Warning**: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
-          to trigger cardinality limits, degrading the usefulness of the metric.
+          > **Warning**
+          > Since this attribute may be based on HTTP headers, opting in to it may allow an attacker
+          > to trigger cardinality limits, degrading the usefulness of the metric.
   - id: metric_attributes.http.client
     type: attribute_group
     brief: 'HTTP client attributes'
@@ -52,18 +52,18 @@ groups:
           Name of the local HTTP server that received the request.
         note: |
           See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-
-          > **Warning**: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
-          to trigger cardinality limits, degrading the usefulness of the metric.
+          > **Warning**
+          > Since this attribute may be based on HTTP headers, opting in to it may allow an attacker
+          > to trigger cardinality limits, degrading the usefulness of the metric.
       - ref: server.port
         requirement_level: opt_in
         brief: >
           Port of the local HTTP server that received the request.
         note: |
           See [Setting `server.address` and `server.port` attributes](/docs/http/http-spans.md#setting-serveraddress-and-serverport-attributes).
-
-          > **Warning**: since this attribute may be based on HTTP headers, opting in to it may allow an attacker
-          to trigger cardinality limits, degrading the usefulness of the metric.
+          > **Warning**
+          > Since this attribute may be based on HTTP headers, opting in to it may allow an attacker
+          > to trigger cardinality limits, degrading the usefulness of the metric.
 
   - id: metric.http.server.request.body.size
     type: metric