docs: move semconv opt-in docs to HTTP instrumentations

Author: thakoreh

README.md

@@ -103,31 +103,6 @@ To release a package as `1.0` stable, the package:
 
 In our efforts to maintain optimal user experience and prevent breaking changes for transitioning into stable semantic conventions, OpenTelemetry Python is adopting the semantic convention migration plan for several instrumentations. Currently this plan is only being adopted for [HTTP-related instrumentations](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/non-normative/http-migration.md), but will eventually cover all types. Please refer to the `semconv status` column of the [instrumentation README](instrumentation/README.md) of the current status of instrumentations' semantic conventions. The possible values are `development`, `stable` and `migration` referring to [status](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.31.0/specification/document-status.md#lifecycle-status) of that particular semantic convention. `Migration` refers to an instrumentation that currently supports the migration plan.
 
-### Opting into stable semantic conventions
-
-You can control which semantic conventions are used by setting the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable. This is useful for transitioning from experimental to stable semantic conventions.
-
-For HTTP instrumentations, set `OTEL_SEMCONV_STABILITY_OPT_IN` to:
-
-- `http` - Emit the new, stable HTTP and networking conventions, and stop emitting the old experimental HTTP and networking conventions that the instrumentation emitted previously.
-- `http/dup` - Emit both the old and the stable HTTP and networking conventions, allowing for a seamless transition.
-
-By default (when the environment variable is not set), the old experimental HTTP and networking conventions are emitted.
-
-Example:
-```bash
-# Use stable HTTP conventions only
-export OTEL_SEMCONV_STABILITY_OPT_IN=http
-
-# Emit both old and new conventions for transition
-export OTEL_SEMCONV_STABILITY_OPT_IN=http/dup
-```
-
-You can also combine multiple opt-ins using commas:
-```bash
-export OTEL_SEMCONV_STABILITY_OPT_IN=http,database/dup
-```
-
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)

instrumentation/opentelemetry-instrumentation-aiohttp-client/src/opentelemetry/instrumentation/aiohttp_client/__init__.py

@@ -189,6 +189,23 @@ def response_hook(span: Span, params: typing.Union[
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
+Stable Semantic Conventions
+***************************
+
+This instrumentation supports the semantic convention migration plan. You can control
+which semantic conventions are emitted by setting the
+``OTEL_SEMCONV_STABILITY_OPT_IN`` environment variable.
+
+For HTTP instrumentations, set ``OTEL_SEMCONV_STABILITY_OPT_IN`` to:
+
+- ``http`` - emit the stable HTTP and networking conventions, and stop emitting
+  the old experimental HTTP and networking conventions.
+- ``http/dup`` - emit both the old experimental and stable HTTP and networking
+  conventions during a transition period.
+
+By default, when the environment variable is not set, the old experimental HTTP
+and networking conventions are emitted.
+
 API
 ---
 """

instrumentation/opentelemetry-instrumentation-aiohttp-server/src/opentelemetry/instrumentation/aiohttp_server/__init__.py

@@ -150,6 +150,23 @@ async def hello(request):
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
+Stable Semantic Conventions
+***************************
+
+This instrumentation supports the semantic convention migration plan. You can control
+which semantic conventions are emitted by setting the
+``OTEL_SEMCONV_STABILITY_OPT_IN`` environment variable.
+
+For HTTP instrumentations, set ``OTEL_SEMCONV_STABILITY_OPT_IN`` to:
+
+- ``http`` - emit the stable HTTP and networking conventions, and stop emitting
+  the old experimental HTTP and networking conventions.
+- ``http/dup`` - emit both the old experimental and stable HTTP and networking
+  conventions during a transition period.
+
+By default, when the environment variable is not set, the old experimental HTTP
+and networking conventions are emitted.
+
 API
 ---
 """

instrumentation/opentelemetry-instrumentation-asgi/src/opentelemetry/instrumentation/asgi/__init__.py

@@ -204,6 +204,23 @@ def client_response_hook(span: Span, scope: Scope, message: dict[str, Any]):
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
+Stable Semantic Conventions
+***************************
+
+This instrumentation supports the semantic convention migration plan. You can control
+which semantic conventions are emitted by setting the
+``OTEL_SEMCONV_STABILITY_OPT_IN`` environment variable.
+
+For HTTP instrumentations, set ``OTEL_SEMCONV_STABILITY_OPT_IN`` to:
+
+- ``http`` - emit the stable HTTP and networking conventions, and stop emitting
+  the old experimental HTTP and networking conventions.
+- ``http/dup`` - emit both the old experimental and stable HTTP and networking
+  conventions during a transition period.
+
+By default, when the environment variable is not set, the old experimental HTTP
+and networking conventions are emitted.
+
 API
 ---
 """

instrumentation/opentelemetry-instrumentation-falcon/src/opentelemetry/instrumentation/falcon/__init__.py

@@ -180,6 +180,23 @@ def response_hook(span, req, resp):
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
+Stable Semantic Conventions
+***************************
+
+This instrumentation supports the semantic convention migration plan. You can control
+which semantic conventions are emitted by setting the
+``OTEL_SEMCONV_STABILITY_OPT_IN`` environment variable.
+
+For HTTP instrumentations, set ``OTEL_SEMCONV_STABILITY_OPT_IN`` to:
+
+- ``http`` - emit the stable HTTP and networking conventions, and stop emitting
+  the old experimental HTTP and networking conventions.
+- ``http/dup`` - emit both the old experimental and stable HTTP and networking
+  conventions during a transition period.
+
+By default, when the environment variable is not set, the old experimental HTTP
+and networking conventions are emitted.
+
 API
 ---
 """

instrumentation/opentelemetry-instrumentation-fastapi/src/opentelemetry/instrumentation/fastapi/__init__.py

@@ -176,6 +176,23 @@ def client_response_hook(span: Span, scope: dict[str, Any], message: dict[str, A
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
+Stable Semantic Conventions
+***************************
+
+This instrumentation supports the semantic convention migration plan. You can control
+which semantic conventions are emitted by setting the
+``OTEL_SEMCONV_STABILITY_OPT_IN`` environment variable.
+
+For HTTP instrumentations, set ``OTEL_SEMCONV_STABILITY_OPT_IN`` to:
+
+- ``http`` - emit the stable HTTP and networking conventions, and stop emitting
+  the old experimental HTTP and networking conventions.
+- ``http/dup`` - emit both the old experimental and stable HTTP and networking
+  conventions during a transition period.
+
+By default, when the environment variable is not set, the old experimental HTTP
+and networking conventions are emitted.
+
 API
 ---
 """

instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py

@@ -189,6 +189,23 @@ def response_hook(span: Span, status: str, response_headers: List):
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
+Stable Semantic Conventions
+***************************
+
+This instrumentation supports the semantic convention migration plan. You can control
+which semantic conventions are emitted by setting the
+``OTEL_SEMCONV_STABILITY_OPT_IN`` environment variable.
+
+For HTTP instrumentations, set ``OTEL_SEMCONV_STABILITY_OPT_IN`` to:
+
+- ``http`` - emit the stable HTTP and networking conventions, and stop emitting
+  the old experimental HTTP and networking conventions.
+- ``http/dup`` - emit both the old experimental and stable HTTP and networking
+  conventions during a transition period.
+
+By default, when the environment variable is not set, the old experimental HTTP
+and networking conventions are emitted.
+
 SQLCommenter
 ************
 You can optionally enable sqlcommenter which enriches the query with contextual

instrumentation/opentelemetry-instrumentation-httpx/src/opentelemetry/instrumentation/httpx/__init__.py

@@ -308,6 +308,23 @@ async def async_response_hook(span, request, response):
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
+Stable Semantic Conventions
+***************************
+
+This instrumentation supports the semantic convention migration plan. You can control
+which semantic conventions are emitted by setting the
+``OTEL_SEMCONV_STABILITY_OPT_IN`` environment variable.
+
+For HTTP instrumentations, set ``OTEL_SEMCONV_STABILITY_OPT_IN`` to:
+
+- ``http`` - emit the stable HTTP and networking conventions, and stop emitting
+  the old experimental HTTP and networking conventions.
+- ``http/dup`` - emit both the old experimental and stable HTTP and networking
+  conventions during a transition period.
+
+By default, when the environment variable is not set, the old experimental HTTP
+and networking conventions are emitted.
+
 API
 ---
 """

instrumentation/opentelemetry-instrumentation-pyramid/src/opentelemetry/instrumentation/pyramid/__init__.py

@@ -179,6 +179,23 @@
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
+Stable Semantic Conventions
+***************************
+
+This instrumentation supports the semantic convention migration plan. You can control
+which semantic conventions are emitted by setting the
+``OTEL_SEMCONV_STABILITY_OPT_IN`` environment variable.
+
+For HTTP instrumentations, set ``OTEL_SEMCONV_STABILITY_OPT_IN`` to:
+
+- ``http`` - emit the stable HTTP and networking conventions, and stop emitting
+  the old experimental HTTP and networking conventions.
+- ``http/dup`` - emit both the old experimental and stable HTTP and networking
+  conventions during a transition period.
+
+By default, when the environment variable is not set, the old experimental HTTP
+and networking conventions are emitted.
+
 API
 ---
 """

instrumentation/opentelemetry-instrumentation-requests/src/opentelemetry/instrumentation/requests/__init__.py

@@ -177,6 +177,23 @@ def response_hook(span, request_obj, response):
 
 will exclude requests such as ``https://site/client/123/info`` and ``https://site/xyz/healthcheck``.
 
+Stable Semantic Conventions
+***************************
+
+This instrumentation supports the semantic convention migration plan. You can control
+which semantic conventions are emitted by setting the
+``OTEL_SEMCONV_STABILITY_OPT_IN`` environment variable.
+
+For HTTP instrumentations, set ``OTEL_SEMCONV_STABILITY_OPT_IN`` to:
+
+- ``http`` - emit the stable HTTP and networking conventions, and stop emitting
+  the old experimental HTTP and networking conventions.
+- ``http/dup`` - emit both the old experimental and stable HTTP and networking
+  conventions during a transition period.
+
+By default, when the environment variable is not set, the old experimental HTTP
+and networking conventions are emitted.
+
 API
 ---
 """