fix(metrics): remove gen_ai.agent.id from all GenAI metric dimensions (#323)

gen_ai.agent.id was set to the span ID (unique per invocation), causing
unbounded metric cardinality across all metric types. This attribute is
useful for trace lookup on spans but has no meaningful role in metric
aggregation where per-run IDs create metric series explosion.

Changes:
- Remove gen_ai.agent.id from MetricsEmitter for LLMInvocation,
  EmbeddingInvocation, ToolCall, MCPToolCall, RetrievalInvocation,
  and AgentInvocation (where it was hardcoded to span_id)
- gen_ai.agent.id remains on all span attributes (no span emitter change)
- gen_ai.agent.name is unaffected (bounded cardinality, kept on metrics)
- Update test assertions to verify gen_ai.agent.id is absent from
  metric data points
- Document span-only constraint in semconv-reference.md

Verified: 213 unit tests pass; end-to-end SRE Copilot run confirmed
telemetry forwarded to local OTel collector with no regressions.

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

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

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):