feedback

Change-Id: Ida0c2305d950d978c31eb04a80e21e947fabdfba
Co-developed-by: Cursor <[email protected]>

Author: Cirilla-zmh

util/opentelemetry-util-genai/src/opentelemetry/util/genai/environment_variables.py

@@ -16,6 +16,15 @@
     "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
 )
 
+OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT = "OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT"
+"""
+.. envvar:: OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT
+
+Controls whether to emit gen_ai.client.inference.operation.details events.
+Must be one of ``true`` or ``false`` (case-insensitive).
+Defaults to ``false``.
+"""
+
 OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK = (
     "OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK"
 )

util/opentelemetry-util-genai/src/opentelemetry/util/genai/span_utils.py

@@ -42,6 +42,7 @@
     gen_ai_json_dumps,
     get_content_capturing_mode,
     is_experimental_mode,
+    should_emit_event,
 )
 
 
@@ -140,14 +141,11 @@ def _maybe_emit_llm_event(
     This function creates a LogRecord event following the semantic convention
     for gen_ai.client.inference.operation.details as specified in the GenAI
     event semantic conventions.
-    """
-    if not is_experimental_mode() or get_content_capturing_mode() not in (
-        ContentCapturingMode.EVENT_ONLY,
-        ContentCapturingMode.SPAN_AND_EVENT,
-    ):
-        return
 
-    if logger is None:
+    For more details, see the semantic convention documentation:
+    https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-events.md#event-eventgen_aiclientinferenceoperationdetails
+    """
+    if not is_experimental_mode() or not should_emit_event() or logger is None:
         return
 
     # Build event attributes by reusing the attribute getter functions

util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py

@@ -40,6 +40,12 @@ class ContentCapturingMode(Enum):
 
 @dataclass()
 class ToolCall:
+    """Represents a tool call requested by the model
+
+    This model is specified as part of semconv in `GenAI messages Python models - ToolCallRequestPart
+    <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/non-normative/models.ipynb>`__.
+    """
+
     arguments: Any
     name: str
     id: str | None
@@ -48,19 +54,37 @@ class ToolCall:
 
 @dataclass()
 class ToolCallResponse:
+    """Represents a tool call result sent to the model or a built-in tool call outcome and details
+
+    This model is specified as part of semconv in `GenAI messages Python models - ToolCallResponsePart
+    <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/non-normative/models.ipynb>`__.
+    """
+
     response: Any
     id: str | None
     type: Literal["tool_call_response"] = "tool_call_response"
 
 
 @dataclass()
 class Text:
+    """Represents text content sent to or received from the model
+
+    This model is specified as part of semconv in `GenAI messages Python models - TextPart
+    <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/non-normative/models.ipynb>`__.
+    """
+
     content: str
     type: Literal["text"] = "text"
 
 
 @dataclass()
 class Reasoning:
+    """Represents reasoning/thinking content received from the model
+
+    This model is specified as part of semconv in `GenAI messages Python models - ReasoningPart
+    <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/non-normative/models.ipynb>`__.
+    """
+
     content: str
     type: Literal["reasoning"] = "reasoning"
 
@@ -70,6 +94,12 @@ class Reasoning:
 
 @dataclass()
 class Blob:
+    """Represents blob binary data sent inline to the model
+
+    This model is specified as part of semconv in `GenAI messages Python models - BlobPart
+    <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/non-normative/models.ipynb>`__.
+    """
+
     mime_type: str | None
     modality: Union[Modality, str]
     content: bytes
@@ -78,6 +108,12 @@ class Blob:
 
 @dataclass()
 class File:
+    """Represents an external referenced file sent to the model by file id
+
+    This model is specified as part of semconv in `GenAI messages Python models - FilePart
+    <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/non-normative/models.ipynb>`__.
+    """
+
     mime_type: str | None
     modality: Union[Modality, str]
     file_id: str
@@ -86,6 +122,12 @@ class File:
 
 @dataclass()
 class Uri:
+    """Represents an external referenced file sent to the model by URI
+
+    This model is specified as part of semconv in `GenAI messages Python models - UriPart
+    <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/non-normative/models.ipynb>`__.
+    """
+
     mime_type: str | None
     modality: Union[Modality, str]
     uri: str

util/opentelemetry-util-genai/src/opentelemetry/util/genai/utils.py

@@ -26,6 +26,7 @@
 )
 from opentelemetry.util.genai.environment_variables import (
     OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT,
+    OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT,
 )
 from opentelemetry.util.genai.types import ContentCapturingMode
 
@@ -64,6 +65,28 @@ def get_content_capturing_mode() -> ContentCapturingMode:
         return ContentCapturingMode.NO_CONTENT
 
 
+def should_emit_event() -> bool:
+    """Check if event emission is enabled.
+
+    Returns True if event emission is enabled, False otherwise.
+    Defaults to False if the environment variable is not set.
+    """
+    envvar = os.environ.get(OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT)
+    if not envvar:
+        return False
+    envvar_lower = envvar.lower()
+    if envvar_lower == "true":
+        return True
+    if envvar_lower == "false":
+        return False
+    logger.warning(
+        "%s is not a valid option for `%s` environment variable. Must be one of true or false (case-insensitive). Defaulting to `false`.",
+        envvar,
+        OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT,
+    )
+    return False
+
+
 class _GenAiJsonEncoder(json.JSONEncoder):
     def default(self, o: Any) -> Any:
         if isinstance(o, bytes):