Document OTEL_SEMCONV_STABILITY_OPT_IN environment variable

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
 ---
 """

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

@@ -150,6 +150,23 @@ def client_response_hook(span, future):
 Note:
     Environment variable names 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-urllib/src/opentelemetry/instrumentation/urllib/__init__.py

@@ -171,6 +171,23 @@ def response_hook(span: Span, request: Request, response: HTTPResponse):
 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-urllib3/src/opentelemetry/instrumentation/urllib3/__init__.py

@@ -179,6 +179,23 @@ def response_hook(
 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-wsgi/src/opentelemetry/instrumentation/wsgi/__init__.py

@@ -211,6 +211,23 @@ def response_hook(span: Span, environ: WSGIEnvironment, status: str, response_he
 To record all of the names set the environment variable  ``OTEL_PYTHON_INSTRUMENTATION_HTTP_CAPTURE_ALL_METHODS``
 to a value that evaluates to true, e.g. ``1``.
 
+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
 ---
 """