Moved HTTP semantic conventions to a dedicated topic-based structure (#…

…141)
open-telemetry · Jun 28, 2023 · cdaccc8 · cdaccc8
1 parent 3d1fe42
commit cdaccc8
Show file tree

Hide file tree

Showing 12 changed files with 137 additions and 81 deletions.
diff --git a/semantic_conventions/http-common.yaml b/semantic_conventions/http-common.yaml
@@ -111,14 +111,14 @@ groups:
         note: >
           MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
 
-          SHOULD include the [application root](/specification/trace/semantic_conventions/http.md#http-server-definitions) if there is one.
+          SHOULD include the [application root](/specification/http/http-spans.md#http-server-definitions) if there is one.
       - ref: server.address
         brief: >
           Name of the local HTTP server that received the request.
         note: |
           Determined by using the first of the following that applies
 
-          - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only
+          - The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
             include host identifier.
           - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
@@ -132,7 +132,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host.
+          - Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host.
           - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
           - Port identifier of the `Host` header

diff --git a/semantic_conventions/metrics/http.yaml b/semantic_conventions/metrics/http.yaml
@@ -11,7 +11,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only
+          - The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
             include host identifier.
           - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
@@ -26,7 +26,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host.
+          - Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host.
           - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
           - Port identifier of the `Host` header
@@ -74,7 +74,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only
+          - The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
             include host identifier.
           - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
@@ -89,7 +89,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host.
+          - Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host.
           - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
           - Port identifier of the `Host` header

diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml
@@ -100,7 +100,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - The [primary server name](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host. MUST only
+          - The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
             include host identifier.
           - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
@@ -116,7 +116,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - Port identifier of the [primary server host](/specification/trace/semantic_conventions/http.md#http-server-definitions) of the matched virtual host.
+          - Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host.
           - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
           - Port identifier of the `Host` header

diff --git a/specification/README.md b/specification/README.md
@@ -0,0 +1,17 @@
+# OpenTelemetry Semantic Conventions
+
+The Semantic Conventions define a common set of (semantic) attributes which provide meaning to data when collecting, producing and consuming it.
+The Semantic Conventions specify among other things span names and kind, metric instruments and units as well as attribute names, types, meaning and valid values. For a detailed definition of the Semantic Conventions' scope see [Semantic Conventions Stability](https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#semantic-conventions-stability).
+The benefit to using Semantic Conventions is in following a common naming scheme that can be standardized across a codebase, libraries, and platforms. This allows easier correlation and consumption of data.
+
+Semantic Conventions are defined for the following areas:
+
+* [HTTP](http/README.md): Semantic Conventions for HTTP client and server operations.
+* *Other areas can be found in the signal specific Semantic Conventions below*
+
+Semantic Conventions by signals:
+
+* [Resource](resource/semantic_conventions/README.md): Semantic Conventions for resources.
+* [Trace](trace/semantic_conventions/README.md): Semantic Conventions for traces and spans.
+* [Metrics](metrics/semantic_conventions/README.md): Semantic Conventions for metrics.
+* [Logs](logs/semantic_conventions/README.md): Semantic Conventions for logs and event data.
diff --git a/specification/http/README.md b/specification/http/README.md
@@ -0,0 +1,39 @@
+# Semantic conventions for HTTP
+
+**Status**: [Experimental, Feature-freeze][DocumentStatus]
+
+This document defines semantic conventions for HTTP spans, metrics and logs.
+They can be used for http and https schemes
+and various HTTP versions like 1.1, 2 and SPDY.
+
+> **Warning**
+> Existing HTTP instrumentations that are using
+> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md)
+> (or prior):
+>
+> * SHOULD NOT change the version of the HTTP or networking attributes that they emit
+>   until the HTTP semantic conventions are marked stable (HTTP stabilization will
+>   include stabilization of a core set of networking attributes which are also used
+>   in HTTP instrumentations).
+> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
+>   in the existing major version which is a comma-separated list of values.
+>   The only values defined so far are:
+>   * `http` - emit the new, stable HTTP and networking attributes,
+>     and stop emitting the old experimental HTTP and networking attributes
+>     that the instrumentation emitted previously.
+>   * `http/dup` - emit both the old and the stable HTTP and networking attributes,
+>     allowing for a seamless transition.
+>   * The default behavior (in the absence of one of these values) is to continue
+>     emitting whatever version of the old experimental HTTP and networking attributes
+>     the instrumentation was emitting previously.
+> * SHOULD maintain (security patching at a minimum) the existing major version
+>   for at least six months after it starts emitting both sets of attributes.
+> * SHOULD drop the environment variable in the next major version (stable
+>   next major version SHOULD NOT be released prior to October 1, 2023).
+
+Semantic conventions for HTTP are defined for the following signals:
+
+* [HTTP Spans](http-spans.md): Semantic Conventions for HTTP client and server *spans*.
+* [HTTP Metrics](http-metrics.md): Semantic Conventions for HTTP client and server *metrics*.
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md