Merge branch 'main' into fix-aiohttp-readmes

Author: xrmx

CHANGELOG.md

@@ -15,13 +15,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `opentelemetry-instrumentation-aiohttp-client`: add support for url exclusions via `OTEL_PYTHON_EXCLUDED_URLS` / `OTEL_PYTHON_AIOHTTP_CLIENT_EXCLUDED_URLS`
   ([#3850](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3850))
+- `opentelemetry-instrumentation-httpx`: add support for url exclusions via `OTEL_PYTHON_EXCLUDED_URLS` / `OTEL_PYTHON_HTTPX_EXCLUDED_URLS`
+  ([#3837](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3837))
+- `opentelemetry-instrumentation-flask`: improve readthedocs for sqlcommenter configuration.
+  ([#3883](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3883))
+- `opentelemetry-instrumentation-sqlalchemy`: improve readthedocs for sqlcommenter configuration.
+  ([#3886](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3886))
+- `opentelemetry-instrumentation-mysql`, `opentelemetry-instrumentation-mysqlclient`, `opentelemetry-instrumentation-pymysql`: improve readthedocs for sqlcommenter configuration.
+  ([#3885](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3885))
+- `opentelemetry-instrumentation-django`: improve readthedocs for sqlcommenter configuration.
+  ([#3884](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3884))
 
 ### Fixed
 
 - `opentelemetry-instrumentation-botocore`: Handle dict input in _decode_tool_use for Bedrock streaming
   ([#3875](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3875))
 - `opentelemetry-instrumentation-aiohttp-client`, `opentelemetry-instrumentation-aiohttp-server`: Fix readme links and text
   ([#3902](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3902))
+- `opentelemetry-instrumentation-aws-lambda`: Fix ImportError with slash-delimited handler paths
+  ([#3894](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3894))
+- `opentelemetry-exporter-richconsole`: Prevent deadlock when parent span is not part of the batch
+  ([#3900](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3900))
 
 ## Version 1.38.0/0.59b0 (2025-10-16)
 

exporter/opentelemetry-exporter-richconsole/src/opentelemetry/exporter/richconsole/__init__.py

@@ -173,14 +173,17 @@ def spans_to_tree(spans: typing.Sequence[ReadableSpan]) -> Dict[str, Tree]:
         trees = {}
         parents = {}
         spans = list(spans)
+        span_ids = {s.context.span_id for s in spans}
         while spans:
             for span in spans:
-                if not span.parent:
+                if not span.parent or span.parent.span_id not in span_ids:
                     trace_id = opentelemetry.trace.format_trace_id(
                         span.context.trace_id
                     )
-                    trees[trace_id] = Tree(label=f"Trace {trace_id}")
-                    child = trees[trace_id].add(
+                    tree = trees.setdefault(
+                        trace_id, Tree(label=f"Trace {trace_id}")
+                    )
+                    child = tree.add(
                         label=Text.from_markup(
                             f"[blue][{_ns_to_time(span.start_time)}][/blue] [bold]{span.name}[/bold], span {opentelemetry.trace.format_span_id(span.context.span_id)}"
                         )

exporter/opentelemetry-exporter-richconsole/test-requirements.txt

@@ -9,6 +9,7 @@ pluggy==1.5.0
 py-cpuinfo==9.0.0
 Pygments==2.17.2
 pytest==7.4.4
+pytest-timeout==2.3.1
 rich==13.7.1
 tomli==2.0.1
 typing_extensions==4.12.2

exporter/opentelemetry-exporter-richconsole/tests/test_rich_exporter.py

@@ -96,3 +96,15 @@ def test_multiple_traces(tracer_provider):
         parent_2.name in child.label
         for child in trees[traceid_1].children[0].children
     )
+
+
+@pytest.mark.timeout(30)
+def test_no_deadlock(tracer_provider):
+    # non-regression test for https://github.com/open-telemetry/opentelemetry-python-contrib/issues/3254
+
+    tracer = tracer_provider.get_tracer(__name__)
+    with tracer.start_as_current_span("parent"):
+        with tracer.start_as_current_span("child") as child:
+            pass
+
+    RichConsoleSpanExporter.spans_to_tree((child,))

instrumentation-genai/opentelemetry-instrumentation-google-genai/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- Minor change to check LRU cache in Completion Hook before acquiring semaphore/thread ([#3907](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3907)).
+
 ## Version 0.4b0 (2025-10-16)
 
 - Implement the new semantic convention changes made in https://github.com/open-telemetry/semantic-conventions/pull/2179.

instrumentation-genai/opentelemetry-instrumentation-langchain/examples/manual/README.rst

@@ -1,4 +1,4 @@
-OpenTelemetry Langcahin Instrumentation Example
+OpenTelemetry Langchain Instrumentation Example
 ===============================================
 
 This is an example of how to instrument Langchain when configuring OpenTelemetry SDK and instrumentations manually.
@@ -8,14 +8,14 @@ Traces include details such as the span name and other attributes.
 
 Note: `.env <.env>`_ file configures additional environment variables:
 - :code:`OTEL_LOGS_EXPORTER=otlp` to specify exporter type.
-- :code:`OPENAI_API_KEY` open AI key for accessing the OpenAI API.
+- :code:`OPENAI_API_KEY` key for accessing the OpenAI API.
 - :code:`OTEL_EXPORTER_OTLP_ENDPOINT` to specify the endpoint for exporting traces (default is http://localhost:4317).
 
 Setup
 -----
 
 Minimally, update the `.env <.env>`_ file with your :code:`OPENAI_API_KEY`.
-An OTLP compatible endpoint should be listening for traces http://localhost:4317.
+An OTLP compatible endpoint should be listening for traces at http://localhost:4317.
 If not, update :code:`OTEL_EXPORTER_OTLP_ENDPOINT` as well.
 
 Next, set up a virtual environment like this:

instrumentation/opentelemetry-instrumentation-aws-lambda/src/opentelemetry/instrumentation/aws_lambda/__init__.py

@@ -460,6 +460,8 @@ def _instrument(self, **kwargs):
             )
             return
         # pylint: disable=attribute-defined-outside-init
+        # Convert slash-delimited paths to dot-delimited for valid Python imports
+        lambda_handler = lambda_handler.replace("/", ".")
         (
             self._wrapped_module_name,
             self._wrapped_function_name,

instrumentation/opentelemetry-instrumentation-aws-lambda/tests/test_aws_lambda_instrumentation_manual.py

@@ -727,6 +727,53 @@ def test_sqs_event_sets_attributes(self):
             MOCK_LAMBDA_CONTEXT_ATTRIBUTES,
         )
 
+    def test_slash_delimited_handler_path(self):
+        """Test that slash-delimited handler paths work correctly.
+
+        AWS Lambda accepts both slash-delimited (python/functions/api.handler)
+        and dot-delimited (python.functions.api.handler) handler paths.
+        This test ensures the instrumentation handles both formats.
+        """
+        # Test slash-delimited format
+        slash_env_patch = mock.patch.dict(
+            "os.environ",
+            {_HANDLER: "tests/mocks/lambda_function.handler"},
+        )
+        slash_env_patch.start()
+        AwsLambdaInstrumentor().instrument()
+
+        mock_execute_lambda()
+
+        spans = self.memory_exporter.get_finished_spans()
+        self.assertEqual(len(spans), 1)
+        self.assertSpanHasAttributes(
+            spans[0],
+            MOCK_LAMBDA_CONTEXT_ATTRIBUTES,
+        )
+
+        slash_env_patch.stop()
+        AwsLambdaInstrumentor().uninstrument()
+        self.memory_exporter.clear()
+
+        # Test dot-delimited format (should still work)
+        dot_env_patch = mock.patch.dict(
+            "os.environ",
+            {_HANDLER: "tests.mocks.lambda_function.handler"},
+        )
+        dot_env_patch.start()
+        AwsLambdaInstrumentor().instrument()
+
+        mock_execute_lambda()
+
+        spans = self.memory_exporter.get_finished_spans()
+        self.assertEqual(len(spans), 1)
+        self.assertSpanHasAttributes(
+            spans[0],
+            MOCK_LAMBDA_CONTEXT_ATTRIBUTES,
+        )
+
+        dot_env_patch.stop()
+
     def test_lambda_handles_handler_exception_with_api_gateway_proxy_event(
         self,
     ):

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

@@ -170,64 +170,61 @@ def response_hook(span, request, response):
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
-SQLCOMMENTER
-*****************************************
-You can optionally configure Django instrumentation to enable sqlcommenter which enriches
-the query with contextual information.
+SQLCommenter
+************
+You can optionally enable sqlcommenter which enriches the query with contextual
+information. Queries made after setting up trace integration with sqlcommenter
+enabled will have configurable key-value pairs appended to them, e.g.
+``Users().objects.all()`` will result in
+``"select * from auth_users; /*traceparent=00-01234567-abcd-01*/"``. This
+supports context propagation between database client and server when database log
+records are enabled. For more information, see:
+
+* `Semantic Conventions - Database Spans <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md#sql-commenter>`_
+* `sqlcommenter <https://google.github.io/sqlcommenter/>`_
 
 .. code:: python
 
     from opentelemetry.instrumentation.django import DjangoInstrumentor
 
     DjangoInstrumentor().instrument(is_sql_commentor_enabled=True)
 
-
-For example,
-::
-
-   Invoking Users().objects.all() will lead to sql query "select * from auth_users" but when SQLCommenter is enabled
-   the query will get appended with some configurable tags like "select * from auth_users /*metrics=value*/;"
-
-
-SQLCommenter Configurations
-***************************
-We can configure the tags to be appended to the sqlquery log by adding below variables to the settings.py
-
-SQLCOMMENTER_WITH_FRAMEWORK = True(Default) or False
-
-For example,
-::
-Enabling this flag will add django framework and it's version which is /*framework='django%3A2.2.3*/
-
-SQLCOMMENTER_WITH_CONTROLLER = True(Default) or False
-
-For example,
-::
-Enabling this flag will add controller name that handles the request /*controller='index'*/
-
-SQLCOMMENTER_WITH_ROUTE = True(Default) or False
-
-For example,
-::
-Enabling this flag will add url path that handles the request /*route='polls/'*/
-
-SQLCOMMENTER_WITH_APP_NAME = True(Default) or False
-
-For example,
-::
-Enabling this flag will add app name that handles the request /*app_name='polls'*/
-
-SQLCOMMENTER_WITH_OPENTELEMETRY = True(Default) or False
-
-For example,
-::
-Enabling this flag will add opentelemetry traceparent /*traceparent='00-fd720cffceba94bbf75940ff3caaf3cc-4fd1a2bdacf56388-01'*/
-
-SQLCOMMENTER_WITH_DB_DRIVER = True(Default) or False
-
-For example,
-::
-Enabling this flag will add name of the db driver /*db_driver='django.db.backends.postgresql'*/
+Warning:
+    Duplicate sqlcomments may be appended to the sqlquery log if DjangoInstrumentor
+    sqlcommenter is enabled in addition to sqlcommenter for an active instrumentation
+    of a database driver or object-relational mapper (ORM) in the same database client
+    stack. For example, if psycopg2 driver is used and Psycopg2Instrumentor has
+    sqlcommenter enabled, then both DjangoInstrumentor and Psycopg2Instrumentor will
+    append comments to the query statement.
+
+SQLCommenter with commenter_options
+***********************************
+The key-value pairs appended to the query can be configured using
+variables in Django ``settings.py``. When sqlcommenter is enabled, all
+available KVs/tags are calculated by default, i.e. ``True`` for each. The
+``settings.py`` values support *opting out* of specific KVs.
+
+Available settings.py commenter options
+#######################################
+
+We can configure the tags to be appended to the sqlquery log by adding below variables to
+``settings.py``, e.g. ``SQLCOMMENTER_WITH_FRAMEWORK = False``
+
++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``settings.py`` variable            | Description                                               | Example                                                                   |
++=====================================+===========================================================+===========================================================================+
+| ``SQLCOMMENTER_WITH_FRAMEWORK``     | Django framework name with version (URL encoded).         | ``framework='django%%%%3A4.2.0'``                                         |
++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``SQLCOMMENTER_WITH_CONTROLLER``    | Django controller/view name that handles the request.     | ``controller='index'``                                                    |
++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``SQLCOMMENTER_WITH_ROUTE``         | URL path pattern that handles the request.                | ``route='polls/'``                                                        |
++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``SQLCOMMENTER_WITH_APP_NAME``      | Django app name that handles the request.                 | ``app_name='polls'``                                                      |
++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``SQLCOMMENTER_WITH_OPENTELEMETRY`` | OpenTelemetry context as traceparent at time of query.    | ``traceparent='00-fd720cffceba94bbf75940ff3caaf3cc-4fd1a2bdacf56388-01'`` |
++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``SQLCOMMENTER_WITH_DB_DRIVER``     | Database driver name used by Django.                      | ``db_driver='django.db.backends.postgresql'``                             |
++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
 
 API
 ---

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

@@ -189,54 +189,66 @@ 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.
 
-SQLCOMMENTER
-*****************************************
-You can optionally configure Flask instrumentation to enable sqlcommenter which enriches
-the query with contextual information.
+SQLCommenter
+************
+You can optionally enable sqlcommenter which enriches the query with contextual
+information. Queries made after setting up trace integration with sqlcommenter
+enabled will have configurable key-value pairs appended to them, e.g.
+``"select * from auth_users; /*framework=flask%%3A2.9.3*/"``. This
+supports context propagation between database client and server when database log
+records are enabled. For more information, see:
+
+* `Semantic Conventions - Database Spans <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md#sql-commenter>`_
+* `sqlcommenter <https://google.github.io/sqlcommenter/>`_
 
 .. code:: python
 
     from opentelemetry.instrumentation.flask import FlaskInstrumentor
 
-    FlaskInstrumentor().instrument(enable_commenter=True, commenter_options={})
-
-For example, FlaskInstrumentor when used with SQLAlchemyInstrumentor or Psycopg2Instrumentor,
-invoking ``cursor.execute("select * from auth_users")`` will lead to sql query
-``select * from auth_users`` but when SQLCommenter is enabled the query will get appended with
-some configurable tags like:
-
-.. code::
-
-    select * from auth_users /*metrics=value*/;"
+    FlaskInstrumentor().instrument(enable_commenter=True)
 
-Inorder for the commenter to append flask related tags to sql queries, the commenter needs
-to enabled on the respective SQLAlchemyInstrumentor or Psycopg2Instrumentor framework too.
-
-SQLCommenter Configurations
-***************************
-We can configure the tags to be appended to the sqlquery log by adding configuration
-inside ``commenter_options={}`` dict.
-
-For example, enabling this flag will add flask and it's version which
-is ``/*flask%%3A2.9.3*/`` to the SQL query as a comment (default is True):
+Note:
+    FlaskInstrumentor sqlcommenter requires that sqlcommenter is also
+    enabled for an active instrumentation of a database driver or object-relational
+    mapper (ORM) in the same database client stack. The latter, such as
+    Psycopg2Instrumentor of SQLAlchemyInstrumentor, will create a base sqlcomment
+    that is enhanced by FlaskInstrumentor with additional values from context
+    before appending to the query statement.
+
+SQLCommenter with commenter_options
+***********************************
+The key-value pairs appended to the query can be configured using
+``commenter_options``. When sqlcommenter is enabled, all available KVs/tags
+are calculated by default. ``commenter_options`` supports *opting out*
+of specific KVs.
 
 .. code:: python
 
-    framework = True
-
-For example, enabling this flag will add route uri ``/*route='/home'*/``
-to the SQL query as a comment (default is True):
-
-.. code:: python
+    from opentelemetry.instrumentation.flask import FlaskInstrumentor
 
-    route = True
+    # Opts into sqlcomment for Flask trace integration.
+    # Opts out of tags for controller.
+    FlaskInstrumentor().instrument(
+        enable_commenter=True,
+        commenter_options={
+            "controller": False,
+        }
+    )
 
-For example, enabling this flag will add controller name ``/*controller='home_view'*/``
-to the SQL query as a comment (default is True):
+Available commenter_options
+###########################
 
-.. code:: python
+The following sqlcomment key-values can be opted out of through ``commenter_options``:
 
-    controller = True
++-------------------+----------------------------------------------------+----------------------------------------+
+| Commenter Option  | Description                                        | Example                                |
++===================+====================================================+========================================+
+| ``framework``     | Flask framework name with version (URL encoded).   | ``framework='flask%%%%3A2.9.3'``       |
++-------------------+----------------------------------------------------+----------------------------------------+
+| ``route``         | Flask route URI pattern.                           | ``route='/home'``                      |
++-------------------+----------------------------------------------------+----------------------------------------+
+| ``controller``    | Flask controller/endpoint name.                    | ``controller='home_view'``             |
++-------------------+----------------------------------------------------+----------------------------------------+
 
 API
 ---