Merge remote-tracking branch 'origin/main' into fix/stream-wrapper-getattr-headers

Author: adityamehra

docs/semconv-reference.md

@@ -282,7 +282,7 @@ Note: Including high-cardinality values into metrics association-properties may
 | Attribute | Type | Description | OTel Semconv |
 |---|---|---|---|
 | `gen_ai.agent.name` | string | Human-readable agent name | [Standard](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-agent-spans.md) |
-| `gen_ai.agent.id` | string | Unique agent identifier | [Standard](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-agent-spans.md) |
+| `gen_ai.agent.id` | string | Unique agent identifier. **Span-only** — excluded from metric dimensions due to unbounded per-invocation cardinality (value equals the span ID). | [Standard](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-agent-spans.md) |
 | `gen_ai.agent.description` | string | Agent description | [Standard](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-agent-spans.md) |
 | `gen_ai.agent.version` | string | Agent version | [Standard](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-agent-spans.md) |
 | `gen_ai.agent.tools` | string[] | Available tool names | **SDOT extension** |
@@ -555,7 +555,7 @@ These attributes follow the current [OTel Gen AI semantic conventions](https://g
 | Category | Attributes |
 |---|---|
 | **Core** | `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.response.id`, `gen_ai.output.type` |
-| **Agent** | `gen_ai.agent.name`, `gen_ai.agent.id`, `gen_ai.agent.description`, `gen_ai.agent.version` |
+| **Agent** | `gen_ai.agent.name`, `gen_ai.agent.description`, `gen_ai.agent.version` (`gen_ai.agent.id` is **span-only** — see note above) |
 | **Workflow** | `gen_ai.workflow.name` |
 | **Conversation** | `gen_ai.conversation.id`, `gen_ai.data_source.id` |
 | **Tokens** | `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.usage.cache_creation.input_tokens`, `gen_ai.usage.cache_read.input_tokens` |

instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Fixed
+- Corrected package name in READMEs from `splunk-otel-instrumentation-openai-agents-v2` to `splunk-otel-instrumentation-openai-agents` to match `pyproject.toml`.
+- Updated README env vars to align with upstream `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` values (`span_only`, `event_only`, `span_and_event`), removed deprecated `CAPTURE_MESSAGE_CONTENT_MODE` flag.
+
 ### Changed
 
 - **Always populate messages on Python objects** — `_build_content_payload()` now always captures messages on `LLMInvocation` regardless of `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`. The emitter layer controls what reaches telemetry, enabling evaluators to access full content even in `NO_CONTENT` mode.

instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/README.md

@@ -1,6 +1,6 @@
 # OpenTelemetry OpenAI Agents Instrumentation (Alpha)
 
-[![PyPI](https://badge.fury.io/py/splunk-otel-instrumentation-openai-agents-v2.svg)](https://pypi.org/project/splunk-otel-instrumentation-openai-agents-v2/)
+[![PyPI](https://badge.fury.io/py/splunk-otel-instrumentation-openai-agents.svg)](https://pypi.org/project/splunk-otel-instrumentation-openai-agents/)
 
 This package provides OpenTelemetry instrumentation for
 [OpenAI Agents SDK](https://github.com/openai/openai-agents-python),
@@ -13,7 +13,7 @@ Status: Alpha (APIs and produced telemetry are subject to change).
 ## Installation
 
 ```bash
-pip install splunk-otel-instrumentation-openai-agents-v2
+pip install splunk-otel-instrumentation-openai-agents
 ```
 
 ## Quick Start
@@ -76,19 +76,35 @@ rich attributes about the operation.
 
 ## Configuration
 
-### Environment Variables
+### Enabling message content
+
+Message content such as prompts, completions, tool arguments, and return values
+are not captured by default. To enable content capturing, set the environment variable
+`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` to one of the following values:
+
+- `true` — Legacy. Treated as `span_and_event` for backward compatibility.
+- `span_only` — Capture content on span attributes only.
+- `event_only` — Capture content on event attributes only.
+- `span_and_event` — Capture content on both span and event attributes.
 
 ```bash
-# Capture message content (disabled by default)
-export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
+export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=span_and_event
+```
 
-# Content capture mode
-export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT_MODE=SPAN_AND_EVENT
+### Other environment variables
+
+```bash
+# Capture tool/function definitions on LLM spans (disabled by default)
+export OTEL_INSTRUMENTATION_GENAI_CAPTURE_TOOL_DEFINITIONS=true
 
 # Disable metrics
 export OTEL_INSTRUMENTATION_OPENAI_AGENTS_CAPTURE_METRICS=false
 ```
 
+> **Backward compatibility**: The deprecated
+> `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT_MODE` variable is still
+> honored when the primary variable is set to a truthy value (`true`/`1`/`yes`/`on`).
+
 ### Instrumentation Options
 
 ```python

instrumentation-genai/opentelemetry-instrumentation-openai-agents-v2/examples/travel-planner/README.md

@@ -37,7 +37,7 @@ Install the Splunk Distribution of OpenTelemetry packages:
 
 ```bash
 # Core instrumentation packages
-pip install splunk-otel-instrumentation-openai-agents-v2
+pip install splunk-otel-instrumentation-openai-agents
 pip install splunk-otel-util-genai
 
 # Splunk-specific emitters (required for Splunk Observability Cloud)

instrumentation-genai/opentelemetry-instrumentation-openai-v2/CHANGELOG.md

@@ -28,6 +28,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add `gen_ai.request.stream` attribute for streaming requests
 - Add `gen_ai.response.time_to_first_chunk` attribute and metric for streaming requests
 
+### Fixed
+
+- Fix PyPI badge, install command, and references in README.rst to use correct
+  `splunk-otel-instrumentation-openai` package name instead of upstream
+- Fix project URLs in pyproject.toml to point to SDOT repo (`signalfx/splunk-otel-python-contrib`)
+
 ### Changed
 
 - **Always populate messages and tool arguments on Python objects** — `input_messages`, `output_messages`, and tool call `arguments` are now always set on `LLMInvocation`/`ToolCall` regardless of `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`. The emitter layer controls what reaches telemetry, enabling evaluators to access full content even in `NO_CONTENT` mode.
@@ -47,7 +53,7 @@ Initial release of `splunk-otel-instrumentation-openai` package.
 - Update tool call handling
   ([#135](https://github.com/signalfx/splunk-otel-python-contrib/pull/135))
 - Add suppression key handling
-  ([#155](https://github.com/signalfx/splunk-otel-python-contrib/pull/135))
+  ([#155](https://github.com/signalfx/splunk-otel-python-contrib/pull/155))
 - Move events/logs and metrics to handler-based emitters
   ([#158](https://github.com/signalfx/splunk-otel-python-contrib/pull/158))
 - Fix service tier attribute names: use `GEN_AI_OPENAI_REQUEST_SERVICE_TIER` for request

instrumentation-genai/opentelemetry-instrumentation-openai-v2/README.rst

@@ -3,8 +3,8 @@ OpenTelemetry OpenAI Instrumentation
 
 |pypi|
 
-.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-openai-v2.svg
-   :target: https://pypi.org/project/opentelemetry-instrumentation-openai-v2/
+.. |pypi| image:: https://badge.fury.io/py/splunk-otel-instrumentation-openai.svg
+   :target: https://pypi.org/project/splunk-otel-instrumentation-openai/
 
 This library allows tracing LLM requests and logging of messages made by the
 `OpenAI Python API library <https://pypi.org/project/openai/>`_. It also captures
@@ -40,7 +40,7 @@ If your application is already instrumented with OpenTelemetry, add this
 package to your requirements.
 ::
 
-    pip install opentelemetry-instrumentation-openai-v2
+    pip install splunk-otel-instrumentation-openai
 
 If you don't have an OpenAI application, yet, try our `examples <examples>`_
 which only need a valid OpenAI API key.
@@ -89,6 +89,24 @@ Message content such as the contents of the prompt, completion, function argumen
 are not captured by default. To capture message content as log events, set the environment variable
 `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` to `true`.
 
+See the `upstream OpenTelemetry documentation <https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation-genai/opentelemetry-instrumentation-openai-v2#enabling-message-content>`_ for more details.
+
+Suppressing nested instrumentation
+***********************************
+
+When using multiple instrumentations together (e.g., LangChain + OpenAI), the higher-level
+instrumentation automatically sets ``SUPPRESS_LANGUAGE_MODEL_INSTRUMENTATION_KEY`` in the
+OpenTelemetry context to prevent duplicate spans for the same underlying LLM call.
+
+This is handled transparently — **no user configuration is needed**. For example, when
+LangChain instrumentation is active alongside OpenAI instrumentation, you will see
+LangChain spans without redundant nested OpenAI spans.
+
+.. note::
+
+   This is not an environment variable and cannot be configured for zero-code instrumentation.
+   It is a context key managed programmatically by instrumentation libraries.
+
 Uninstrument
 ************
 
@@ -106,7 +124,7 @@ To uninstrument clients, call the uninstrument method:
 
 References
 ----------
-* `OpenTelemetry OpenAI Instrumentation <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation-genai/openai.html>`_
+* `Splunk OpenTelemetry OpenAI Instrumentation <https://github.com/signalfx/splunk-otel-python-contrib/tree/main/instrumentation-genai/opentelemetry-instrumentation-openai-v2>`_
 * `OpenTelemetry Project <https://opentelemetry.io/>`_
 * `OpenTelemetry Python Examples <https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples>`_
 

instrumentation-genai/opentelemetry-instrumentation-openai-v2/pyproject.toml

@@ -35,8 +35,8 @@ instruments = [
 openai = "opentelemetry.instrumentation.openai_v2:OpenAIInstrumentor"
 
 [project.urls]
-Homepage = "https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation-genai/opentelemetry-instrumentation-openai-v2"
-Repository = "https://github.com/open-telemetry/opentelemetry-python-contrib"
+Homepage = "https://github.com/signalfx/splunk-otel-python-contrib/tree/main/instrumentation-genai/opentelemetry-instrumentation-openai-v2"
+Repository = "https://github.com/signalfx/splunk-otel-python-contrib"
 
 [tool.hatch.version]
 path = "src/opentelemetry/instrumentation/openai_v2/version.py"

util/opentelemetry-util-genai/CHANGELOG.md

@@ -10,6 +10,7 @@ All notable changes to this repository are documented in this file.
 
 ### Changed
 
+- **`gen_ai.agent.id` removed from all GenAI metric dimensions** — The attribute was set to the span ID (unique per invocation), causing unbounded metric cardinality. It remains available on spans where per-invocation identity is expected and useful. `gen_ai.agent.name` is unaffected.
 - **`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` now accepts mode values directly** — Accepts `NO_CONTENT`, `SPAN_ONLY`, `EVENT_ONLY`, `SPAN_AND_EVENT` in addition to legacy `true`/`false`. Aligns with upstream OpenTelemetry GenAI conventions.
 - **Removed experimental mode gating** — Content capture no longer requires an experimental stability flag.
 

util/opentelemetry-util-genai/src/opentelemetry/util/genai/emitters/metrics.py

@@ -105,8 +105,6 @@ def on_end(self, obj: Any) -> None:
                 metric_attrs[GenAI.GEN_AI_AGENT_NAME] = (
                     llm_invocation.agent_name
                 )
-            if llm_invocation.agent_id:
-                metric_attrs[GenAI.GEN_AI_AGENT_ID] = llm_invocation.agent_id
 
             # Add session context if configured
             metric_attrs.update(get_context_metric_attributes(llm_invocation))
@@ -170,10 +168,6 @@ def on_end(self, obj: Any) -> None:
                 metric_attrs[GenAI.GEN_AI_AGENT_NAME] = (
                     embedding_invocation.agent_name
                 )
-            if embedding_invocation.agent_id:
-                metric_attrs[GenAI.GEN_AI_AGENT_ID] = (
-                    embedding_invocation.agent_id
-                )
 
             # Add session context if configured
             metric_attrs.update(
@@ -224,8 +218,6 @@ def on_error(self, error: Error, obj: Any) -> None:
                 metric_attrs[GenAI.GEN_AI_AGENT_NAME] = (
                     llm_invocation.agent_name
                 )
-            if llm_invocation.agent_id:
-                metric_attrs[GenAI.GEN_AI_AGENT_ID] = llm_invocation.agent_id
             if getattr(error, "type", None) is not None:
                 metric_attrs[ErrorAttributes.ERROR_TYPE] = (
                     error.type.__qualname__
@@ -252,8 +244,6 @@ def on_error(self, error: Error, obj: Any) -> None:
                 metric_attrs[GenAI.GEN_AI_TOOL_NAME] = obj.name
                 if obj.agent_name:
                     metric_attrs[GenAI.GEN_AI_AGENT_NAME] = obj.agent_name
-                if obj.agent_id:
-                    metric_attrs[GenAI.GEN_AI_AGENT_ID] = obj.agent_id
                 if getattr(error, "type", None) is not None:
                     metric_attrs[ErrorAttributes.ERROR_TYPE] = (
                         error.type.__qualname__
@@ -289,8 +279,6 @@ def on_error(self, error: Error, obj: Any) -> None:
                 metric_attrs[GenAI.GEN_AI_AGENT_NAME] = (
                     tool_invocation.agent_name
                 )
-            if tool_invocation.agent_id:
-                metric_attrs[GenAI.GEN_AI_AGENT_ID] = tool_invocation.agent_id
             if getattr(error, "type", None) is not None:
                 metric_attrs[ErrorAttributes.ERROR_TYPE] = (
                     error.type.__qualname__
@@ -319,10 +307,6 @@ def on_error(self, error: Error, obj: Any) -> None:
                 metric_attrs[GenAI.GEN_AI_AGENT_NAME] = (
                     embedding_invocation.agent_name
                 )
-            if embedding_invocation.agent_id:
-                metric_attrs[GenAI.GEN_AI_AGENT_ID] = (
-                    embedding_invocation.agent_id
-                )
             if getattr(error, "type", None) is not None:
                 metric_attrs[ErrorAttributes.ERROR_TYPE] = (
                     error.type.__qualname__
@@ -395,11 +379,6 @@ def _record_agent_metrics(
         metric_attrs = {
             GenAI.GEN_AI_OPERATION_NAME: agent.operation,
             GenAI.GEN_AI_AGENT_NAME: agent.name,
-            GenAI.GEN_AI_AGENT_ID: (
-                f"{agent.span_id:016x}"
-                if agent.span_id is not None
-                else str(id(agent))
-            ),
         }
         if agent.agent_type:
             metric_attrs["gen_ai.agent.type"] = agent.agent_type
@@ -437,8 +416,6 @@ def _record_retrieval_metrics(
         # Add agent context if available
         if retrieval.agent_name:
             metric_attrs[GenAI.GEN_AI_AGENT_NAME] = retrieval.agent_name
-        if retrieval.agent_id:
-            metric_attrs[GenAI.GEN_AI_AGENT_ID] = retrieval.agent_id
         # Add error type if present
         if error is not None and getattr(error, "type", None) is not None:
             metric_attrs[ErrorAttributes.ERROR_TYPE] = error.type.__qualname__
@@ -467,8 +444,6 @@ def _record_execute_tool_metrics(self, tool: ToolCall) -> None:
         metric_attrs[GenAI.GEN_AI_TOOL_NAME] = tool.name
         if tool.agent_name:
             metric_attrs[GenAI.GEN_AI_AGENT_NAME] = tool.agent_name
-        if tool.agent_id:
-            metric_attrs[GenAI.GEN_AI_AGENT_ID] = tool.agent_id
         metric_attrs.update(get_context_metric_attributes(tool))
         _record_duration(
             self._duration_histogram,

util/opentelemetry-util-genai/tests/test_metrics.py

@@ -260,8 +260,7 @@ def test_llm_metrics_include_agent_identity_when_present(self):
             agent_id="agent-123",
         )
         metrics_list = self._collect_metrics()
-        # Collect token usage and duration datapoints and assert agent attrs present
-        # We flatten all datapoints for easier searching
+        # agent.name (bounded cardinality) is kept; agent.id (per-invocation) is excluded
         found_token_agent = False
         found_duration_agent = False
         for metric in metrics_list:
@@ -270,28 +269,29 @@ def test_llm_metrics_include_agent_identity_when_present(self):
                 "gen_ai.client.operation.duration",
             ):
                 continue
-            # metric.data.data_points for Histogram-like metrics
             data = getattr(metric, "data", None)
             if not data:
                 continue
             data_points = getattr(data, "data_points", []) or []
             for dp in data_points:
                 attrs = getattr(dp, "attributes", {}) or {}
-                if (
-                    attrs.get("gen_ai.agent.name") == "router_agent"
-                    and attrs.get("gen_ai.agent.id") == "agent-123"
-                ):
+                if attrs.get("gen_ai.agent.name") == "router_agent":
+                    self.assertNotIn(
+                        "gen_ai.agent.id",
+                        attrs,
+                        "gen_ai.agent.id must not appear on metric data points",
+                    )
                     if metric.name == "gen_ai.client.token.usage":
                         found_token_agent = True
                     if metric.name == "gen_ai.client.operation.duration":
                         found_duration_agent = True
         self.assertTrue(
             found_token_agent,
-            "Expected token usage metric datapoint to include agent.name and agent.id",
+            "Expected token usage metric datapoint to include agent.name",
         )
         self.assertTrue(
             found_duration_agent,
-            "Expected operation duration metric datapoint to include agent.name and agent.id",
+            "Expected operation duration metric datapoint to include agent.name",
         )
 
     def test_llm_metrics_include_server_attributes(self):
@@ -391,15 +391,17 @@ def test_llm_metrics_inherit_agent_identity_from_context(self):
                 continue
             for dp in getattr(data, "data_points", []) or []:
                 attrs = getattr(dp, "attributes", {}) or {}
-                if (
-                    attrs.get("gen_ai.agent.name") == "context_agent"
-                    and attrs.get("gen_ai.agent.id") == "agent-123"
-                ):
+                if attrs.get("gen_ai.agent.name") == "context_agent":
+                    self.assertNotIn(
+                        "gen_ai.agent.id",
+                        attrs,
+                        "gen_ai.agent.id must not appear on metric data points",
+                    )
                     inherited = True
                     break
         self.assertTrue(
             inherited,
-            "Expected metrics to inherit agent identity from active agent context",
+            "Expected metrics to inherit agent.name from active agent context",
         )
 
     def test_llm_duration_metric_includes_error_type_on_failure(self):