feat(langchain): add OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI env var

Expose the OpenAI span-suppression behaviour as a configurable env var
instead of always injecting the suppress_language_model_instrumentation
context key.

Default is true (backward compatible). Zero-code deployments can set
OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI=false together with
OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=openai so that openai-v2 is
excluded at startup and no runtime suppression is needed. Manual users
who want both instrumentors to emit spans simultaneously can also use
false without disabling openai-v2.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: adityamehra

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

@@ -2,6 +2,17 @@
 
 All notable changes to this repository are documented in this file.
 
+## Unreleased
+
+### Added
+- **`OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI` env var** — Controls whether
+  the LangChain instrumentor injects the `suppress_language_model_instrumentation`
+  context key to prevent `opentelemetry-instrumentation-openai-v2` from creating
+  its own spans. Defaults to `true` (preserves existing behavior). Set to `false`
+  in zero-code deployments together with
+  `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=openai`, or to allow both instrumentors
+  to emit spans side by side in manual setups.
+
 ## Version 0.1.14
 
 ### Bump version for release

instrumentation-genai/opentelemetry-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/__init__.py

@@ -3,6 +3,7 @@
 import asyncio
 import inspect
 import logging
+import os
 from typing import Collection
 
 from opentelemetry import context as context_api
@@ -20,10 +21,24 @@
 )
 from wrapt import wrap_function_wrapper
 
+from .environment_variables import OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI
 from .semconv_ai import SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY
 
 logger = logging.getLogger(__name__)
 
+
+def _should_suppress_openai() -> bool:
+    """Return True when the suppression key should be set in the OTel context.
+
+    Reads OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI (default ``true``).
+    Set to ``false`` together with OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=openai
+    in zero-code deployments, or when you want both instrumentors to emit
+    spans side by side in manual setups.
+    """
+    raw = os.environ.get(OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI, "true")
+    return raw.strip().lower() not in ("false", "0", "no", "off")
+
+
 _instruments = ("langchain-core > 0.1.0",)
 
 # Embedding patches configuration
@@ -425,9 +440,12 @@ def __call__(
         # Sync (non-generator) path: attach, execute, detach.
         token = None
         try:
-            token = context_api.attach(
-                context_api.set_value(SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY, True)
-            )
+            if _should_suppress_openai():
+                token = context_api.attach(
+                    context_api.set_value(
+                        SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY, True
+                    )
+                )
             return wrapped(*args, **kwargs)
         finally:
             if token is not None:
@@ -438,9 +456,12 @@ async def _wrap_coroutine(coro):
         """Await a coroutine with LLM instrumentation suppressed."""
         token = None
         try:
-            token = context_api.attach(
-                context_api.set_value(SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY, True)
-            )
+            if _should_suppress_openai():
+                token = context_api.attach(
+                    context_api.set_value(
+                        SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY, True
+                    )
+                )
             return await coro
         finally:
             if token is not None:
@@ -451,9 +472,12 @@ async def _wrap_async_generator(agen):
         """Iterate an async generator with LLM instrumentation suppressed."""
         token = None
         try:
-            token = context_api.attach(
-                context_api.set_value(SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY, True)
-            )
+            if _should_suppress_openai():
+                token = context_api.attach(
+                    context_api.set_value(
+                        SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY, True
+                    )
+                )
             async for item in agen:
                 yield item
         finally:
@@ -465,9 +489,12 @@ def _wrap_sync_generator(gen):
         """Iterate a sync generator with LLM instrumentation suppressed."""
         token = None
         try:
-            token = context_api.attach(
-                context_api.set_value(SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY, True)
-            )
+            if _should_suppress_openai():
+                token = context_api.attach(
+                    context_api.set_value(
+                        SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY, True
+                    )
+                )
             yield from gen
         finally:
             if token is not None:

instrumentation-genai/opentelemetry-instrumentation-langchain/src/opentelemetry/instrumentation/langchain/environment_variables.py

@@ -0,0 +1,50 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI = (
+    "OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI"
+)
+"""
+.. envvar:: OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI
+
+Controls whether the LangChain instrumentor suppresses OpenAI spans when both
+``opentelemetry-instrumentation-langchain`` and
+``opentelemetry-instrumentation-openai-v2`` are active at the same time.
+
+When ``true`` (default), the LangChain instrumentor injects a suppression key
+into the OTel context before every OpenAI API call so that the openai-v2
+instrumentor skips creating its own spans.  This prevents duplicate LLM-level
+telemetry when both packages are manually instrumented together.
+
+When ``false``, the suppression key is **not** set.  Use this together with
+``OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=openai`` (zero-code / auto-instrumentation)
+so that the openai-v2 instrumentor is not loaded at all, or when you explicitly
+want both instrumentors to emit their own spans side by side.
+
+Default: ``true``
+
+Examples::
+
+    # Zero-code: disable the suppression key; openai-v2 is already excluded
+    # via OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=openai
+    export OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI=false
+
+    # Manual instrumentation: preserve the default suppression behavior
+    # (suppress is true, no setting needed)
+
+    # Manual instrumentation: allow both to emit spans simultaneously
+    export OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI=false
+"""
+
+__all__ = ["OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI"]

instrumentation-genai/opentelemetry-instrumentation-langchain/tests/test_suppress_openai_env_var.py

@@ -0,0 +1,120 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Unit tests for OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI env var.
+
+Verifies that _should_suppress_openai() correctly parses all truthy/falsey
+values and that the LangChain instrumentor skips setting the
+SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY when the env var is false.
+"""
+
+import pytest
+
+from opentelemetry.instrumentation.langchain import _should_suppress_openai
+from opentelemetry.instrumentation.langchain.environment_variables import (
+    OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI,
+)
+
+
+# ---------------------------------------------------------------------------
+# _should_suppress_openai() parsing
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "value",
+    ["true", "True", "TRUE", "1", "yes", "on", "  true  "],
+)
+def test_should_suppress_openai_truthy(monkeypatch, value):
+    """Truthy env var values return True (suppression is active)."""
+    monkeypatch.setenv(OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI, value)
+    assert _should_suppress_openai() is True
+
+
+@pytest.mark.parametrize(
+    "value",
+    ["false", "False", "FALSE", "0", "no", "off", "  false  "],
+)
+def test_should_suppress_openai_falsey(monkeypatch, value):
+    """Falsey env var values return False (suppression is disabled)."""
+    monkeypatch.setenv(OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI, value)
+    assert _should_suppress_openai() is False
+
+
+def test_should_suppress_openai_default(monkeypatch):
+    """When the env var is unset the default is True (backward compat)."""
+    monkeypatch.delenv(OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI, raising=False)
+    assert _should_suppress_openai() is True
+
+
+# ---------------------------------------------------------------------------
+# Integration: suppression key is NOT set when env var is false
+# ---------------------------------------------------------------------------
+
+
+def test_suppress_key_not_set_when_env_var_false(monkeypatch):
+    """When OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI=false the
+    suppression context key must not be set during an OpenAI wrapper call."""
+    monkeypatch.setenv(OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI, "false")
+
+    from opentelemetry import context as context_api
+    from opentelemetry.instrumentation.langchain import _OpenAITracingWrapper
+    from opentelemetry.util.genai.attributes import (
+        SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY,
+    )
+
+    captured_value = {}
+
+    def fake_wrapped(*args, **kwargs):
+        captured_value["suppress"] = context_api.get_value(
+            SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY
+        )
+        return "ok"
+
+    wrapper = _OpenAITracingWrapper(callback_manager=None)
+    result = wrapper(fake_wrapped, None, (), {})
+
+    assert result == "ok"
+    assert captured_value.get("suppress") is None, (
+        "Suppression key must not be set when env var is false"
+    )
+
+
+def test_suppress_key_set_when_env_var_true(monkeypatch):
+    """When OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI=true (default) the
+    suppression context key IS set during the wrapper call."""
+    monkeypatch.setenv(OTEL_INSTRUMENTATION_LANGCHAIN_SUPPRESS_OPENAI, "true")
+
+    from opentelemetry import context as context_api
+    from opentelemetry.instrumentation.langchain import _OpenAITracingWrapper
+    from opentelemetry.util.genai.attributes import (
+        SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY,
+    )
+
+    captured_value = {}
+
+    def fake_wrapped(*args, **kwargs):
+        captured_value["suppress"] = context_api.get_value(
+            SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY
+        )
+        return "ok"
+
+    wrapper = _OpenAITracingWrapper(callback_manager=None)
+    result = wrapper(fake_wrapped, None, (), {})
+
+    assert result == "ok"
+    assert captured_value.get("suppress") is True, (
+        "Suppression key must be set when env var is true"
+    )