Updates according to latest spec

Author: Nagkumar Arkalgud

instrumentation-genai/opentelemetry-instrumentation-openai-agents/src/opentelemetry/instrumentation/openai_agents/__init__.py

@@ -13,8 +13,8 @@
 # limitations under the License.
 
 """
-OpenAI Agents instrumentation supporting `openai` in agent frameworks, it can be enabled by
-using ``OpenAIAgentsInstrumentor``.
+OpenAI Agents instrumentation supporting `openai` in agent frameworks.
+Enable with ``OpenAIAgentsInstrumentor``.
 
 .. _openai: https://pypi.org/project/openai/
 
@@ -24,7 +24,9 @@
 .. code:: python
 
     from openai import OpenAI
-    from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
+    from opentelemetry.instrumentation.openai_agents import (
+        OpenAIAgentsInstrumentor,
+    )
 
     OpenAIAgentsInstrumentor().instrument()
 
@@ -34,7 +36,8 @@
 API
 ---
 
-The OpenAI Agents instrumentation captures spans for OpenAI API calls made within agent frameworks.
+This instrumentation captures spans for OpenAI API calls made within
+agent frameworks.
 It provides detailed tracing information including:
 
 - Request and response content (if configured)
@@ -45,21 +48,29 @@
 Configuration
 -------------
 
-The following environment variables can be used to configure the instrumentation:
+Environment variables:
 
-- ``OTEL_INSTRUMENTATION_OPENAI_AGENTS_CAPTURE_CONTENT``: Set to ``true`` to capture the content of the requests and responses. Default is ``false``.
-- ``OTEL_INSTRUMENTATION_OPENAI_AGENTS_CAPTURE_METRICS``: Set to ``true`` to capture metrics. Default is ``true``.
+- ``OTEL_INSTRUMENTATION_OPENAI_AGENTS_CAPTURE_CONTENT``: ``true`` to
+    capture request/response content (default ``false``).
+- ``OTEL_INSTRUMENTATION_OPENAI_AGENTS_CAPTURE_METRICS``: ``true`` to
+    capture metrics (default ``true``).
 """
 
 import logging
-from os import environ
 from typing import Collection
 
 from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
 from opentelemetry.instrumentation.openai_agents.package import _instruments
-from opentelemetry.instrumentation.openai_agents.version import __version__
-from opentelemetry.instrumentation.openai_agents.utils import is_content_enabled
-from opentelemetry.instrumentation.openai_agents.genai_semantic_processor import GenAISemanticProcessor
+from opentelemetry.instrumentation.openai_agents.genai_semantic_processor import (
+    GenAISemanticProcessor,
+)
+from opentelemetry.instrumentation.openai_agents.constants import (
+    GenAIProvider,
+    GenAIOperationName,
+    GenAIToolType,
+    GenAIOutputType,
+    GenAIEvaluationAttributes,
+)
 from opentelemetry.semconv.schemas import Schemas
 from opentelemetry.trace import get_tracer
 from opentelemetry._events import get_event_logger
@@ -92,14 +103,28 @@ def _instrument(self, **kwargs):
             event_logger_provider=event_logger_provider,
         )
 
-        add_trace_processor(GenAISemanticProcessor(tracer=tracer, event_logger=event_logger))
-        
-
+        add_trace_processor(
+            GenAISemanticProcessor(
+                tracer=tracer,
+                event_logger=event_logger,
+            )
+        )
 
+        # Expose constants via module attributes for convenience
+        globals().update(
+            {
+                "GenAIProvider": GenAIProvider,
+                "GenAIOperationName": GenAIOperationName,
+                "GenAIToolType": GenAIToolType,
+                "GenAIOutputType": GenAIOutputType,
+                "GenAIEvaluationAttributes": GenAIEvaluationAttributes,
+            }
+        )
+        
     def _uninstrument(self, **kwargs):
         """Uninstruments the OpenAI library for agent frameworks."""
         pass
 
     def instrumentation_dependencies(self) -> Collection[str]:
-        """Return a list of python packages with versions that the will be instrumented."""
+        """Return list of python packages with versions instrumented."""
         return _instruments

instrumentation-genai/opentelemetry-instrumentation-openai-agents/src/opentelemetry/instrumentation/openai_agents/constants.py

@@ -0,0 +1,133 @@
+"""Centralized semantic convention constants for GenAI instrumentation.
+
+Consolidates provider names, operation names, tool types, output types,
+evaluation attributes, and helper maps so other modules can import from
+one place. Keeping strings in one module reduces drift as the spec evolves.
+"""
+from __future__ import annotations
+
+# Provider names (superset for forward compatibility)
+class GenAIProvider:
+    OPENAI = "openai"
+    GCP_GEN_AI = "gcp.gen_ai"
+    GCP_VERTEX_AI = "gcp.vertex_ai"
+    GCP_GEMINI = "gcp.gemini"
+    ANTHROPIC = "anthropic"
+    COHERE = "cohere"
+    AZURE_AI_INFERENCE = "azure.ai.inference"
+    AZURE_AI_OPENAI = "azure.ai.openai"
+    IBM_WATSONX_AI = "ibm.watsonx.ai"
+    AWS_BEDROCK = "aws.bedrock"
+    PERPLEXITY = "perplexity"
+    X_AI = "x_ai"
+    DEEPSEEK = "deepseek"
+    GROQ = "groq"
+    MISTRAL_AI = "mistral_ai"
+
+    ALL = {
+        OPENAI,
+        GCP_GEN_AI,
+        GCP_VERTEX_AI,
+        GCP_GEMINI,
+        ANTHROPIC,
+        COHERE,
+        AZURE_AI_INFERENCE,
+        AZURE_AI_OPENAI,
+        IBM_WATSONX_AI,
+        AWS_BEDROCK,
+        PERPLEXITY,
+        X_AI,
+        DEEPSEEK,
+        GROQ,
+        MISTRAL_AI,
+    }
+
+
+class GenAIOperationName:
+    CHAT = "chat"
+    GENERATE_CONTENT = "generate_content"
+    TEXT_COMPLETION = "text_completion"
+    EMBEDDINGS = "embeddings"
+    CREATE_AGENT = "create_agent"
+    INVOKE_AGENT = "invoke_agent"
+    EXECUTE_TOOL = "execute_tool"
+    TRANSCRIPTION = "transcription"
+    SPEECH = "speech_generation"
+    GUARDRAIL = "guardrail_check"
+    HANDOFF = "agent_handoff"
+    RESPONSE = "response"  # internal aggregator in current processor
+
+    # Mapping of span data class (lower) to default op (heuristic)
+    CLASS_FALLBACK = {
+        "generationspan": CHAT,
+        "responsespan": RESPONSE,
+        "functionspan": EXECUTE_TOOL,
+        "agentspan": INVOKE_AGENT,
+    }
+
+
+class GenAIOutputType:
+    TEXT = "text"
+    JSON = "json"
+    IMAGE = "image"
+    SPEECH = "speech"
+    # existing custom inference types retained for backward compatibility
+
+
+class GenAIToolType:
+    FUNCTION = "function"
+    EXTENSION = "extension"
+    DATASTORE = "datastore"
+
+    ALL = {FUNCTION, EXTENSION, DATASTORE}
+
+
+class GenAIEvaluationAttributes:
+    NAME = "gen_ai.evaluation.name"
+    SCORE_VALUE = "gen_ai.evaluation.score.value"
+    SCORE_LABEL = "gen_ai.evaluation.score.label"
+    EXPLANATION = "gen_ai.evaluation.explanation"
+
+
+# Complete list of GenAI semantic convention attribute keys
+GEN_AI_PROVIDER_NAME = "gen_ai.provider.name"
+GEN_AI_OPERATION_NAME = "gen_ai.operation.name"
+GEN_AI_REQUEST_MODEL = "gen_ai.request.model"
+GEN_AI_REQUEST_MAX_TOKENS = "gen_ai.request.max_tokens"
+GEN_AI_REQUEST_TEMPERATURE = "gen_ai.request.temperature"
+GEN_AI_REQUEST_TOP_P = "gen_ai.request.top_p"
+GEN_AI_REQUEST_TOP_K = "gen_ai.request.top_k"
+GEN_AI_REQUEST_FREQUENCY_PENALTY = "gen_ai.request.frequency_penalty"
+GEN_AI_REQUEST_PRESENCE_PENALTY = "gen_ai.request.presence_penalty"
+GEN_AI_REQUEST_CHOICE_COUNT = "gen_ai.request.choice.count"
+GEN_AI_REQUEST_STOP_SEQUENCES = "gen_ai.request.stop_sequences"
+GEN_AI_REQUEST_ENCODING_FORMATS = "gen_ai.request.encoding_formats"
+GEN_AI_REQUEST_SEED = "gen_ai.request.seed"
+GEN_AI_RESPONSE_ID = "gen_ai.response.id"
+GEN_AI_RESPONSE_MODEL = "gen_ai.response.model"
+GEN_AI_RESPONSE_FINISH_REASONS = "gen_ai.response.finish_reasons"
+GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens"
+GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
+GEN_AI_USAGE_TOTAL_TOKENS = "gen_ai.usage.total_tokens"
+GEN_AI_CONVERSATION_ID = "gen_ai.conversation.id"
+GEN_AI_AGENT_ID = "gen_ai.agent.id"
+GEN_AI_AGENT_NAME = "gen_ai.agent.name"
+GEN_AI_AGENT_DESCRIPTION = "gen_ai.agent.description"
+GEN_AI_TOOL_NAME = "gen_ai.tool.name"
+GEN_AI_TOOL_TYPE = "gen_ai.tool.type"
+GEN_AI_TOOL_CALL_ID = "gen_ai.tool.call.id"
+GEN_AI_TOOL_DESCRIPTION = "gen_ai.tool.description"
+GEN_AI_TOOL_CALL_ARGUMENTS = "gen_ai.tool.call.arguments"
+GEN_AI_TOOL_CALL_RESULT = "gen_ai.tool.call.result"
+GEN_AI_TOOL_DEFINITIONS = "gen_ai.tool.definitions"
+GEN_AI_ORCHESTRATOR_AGENT_DEFINITIONS = "gen_ai.orchestrator.agent.definitions"
+GEN_AI_OUTPUT_TYPE = "gen_ai.output.type"
+GEN_AI_SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions"
+GEN_AI_INPUT_MESSAGES = "gen_ai.input.messages"
+GEN_AI_OUTPUT_MESSAGES = "gen_ai.output.messages"
+GEN_AI_GUARDRAIL_NAME = "gen_ai.guardrail.name"
+GEN_AI_GUARDRAIL_TRIGGERED = "gen_ai.guardrail.triggered"
+GEN_AI_HANDOFF_FROM_AGENT = "gen_ai.handoff.from_agent"
+GEN_AI_HANDOFF_TO_AGENT = "gen_ai.handoff.to_agent"
+GEN_AI_EMBEDDINGS_DIMENSION_COUNT = "gen_ai.embeddings.dimension.count"
+GEN_AI_DATA_SOURCE_ID = "gen_ai.data_source.id"

instrumentation-genai/opentelemetry-instrumentation-openai-agents/src/opentelemetry/instrumentation/openai_agents/events.py

@@ -0,0 +1,140 @@
+"""Event emission helpers for GenAI instrumentation.
+
+Provides thin wrappers around the OpenTelemetry event logger for
+spec-defined GenAI events:
+
+- gen_ai.client.inference.operation.details
+- gen_ai.evaluation.result (helper only; actual evaluation may happen
+  externally – e.g. offline evaluator script)
+
+Environment toggles:
+- OTEL_GENAI_EMIT_OPERATION_DETAILS (default: true)
+- OTEL_GENAI_EMIT_EVALUATION_RESULTS (default: true)
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+import os
+from opentelemetry._events import Event
+
+OP_DETAILS_EVENT = "gen_ai.client.inference.operation.details"
+EVAL_RESULT_EVENT = "gen_ai.evaluation.result"
+
+_OP_DETAILS_ENABLED_ENV = "OTEL_GENAI_EMIT_OPERATION_DETAILS"
+_EVAL_RESULTS_ENABLED_ENV = "OTEL_GENAI_EMIT_EVALUATION_RESULTS"
+
+# Attribute allowlist subset to avoid dumping huge blobs blindly.
+# (Large content already controlled by capture-content env var.)
+_OPERATION_DETAILS_CORE_KEYS = {
+    "gen_ai.provider.name",
+    "gen_ai.operation.name",
+    "gen_ai.request.model",
+    "gen_ai.response.id",
+    "gen_ai.response.model",
+    "gen_ai.usage.input_tokens",
+    "gen_ai.usage.output_tokens",
+    "gen_ai.usage.total_tokens",
+    "gen_ai.output.type",
+    "gen_ai.system_instructions",
+    "gen_ai.input.messages",
+    "gen_ai.output.messages",
+}
+
+_MAX_VALUE_LEN = 4000  # defensive truncation
+
+
+def _enabled(env_name: str, default_true: bool = True) -> bool:
+    raw = os.getenv(env_name)
+    if raw is None:
+        return default_true
+    return raw.lower() not in {"0", "false", "no"}
+
+
+def emit_operation_details_event(
+    event_logger,
+    span_attributes: Dict[str, Any],
+    otel_span: Optional[Any] = None
+) -> None:
+    """Emit operation details event with span attributes.
+    
+    Args:
+        event_logger: The event logger instance
+        span_attributes: Dictionary of span attributes to include
+        otel_span: Optional OpenTelemetry span for context
+    """
+    if not event_logger:
+        return
+    if not _enabled(_OP_DETAILS_ENABLED_ENV, True):
+        return
+    
+    attrs: Dict[str, Any] = {}
+    for k in _OPERATION_DETAILS_CORE_KEYS:
+        if k in span_attributes:
+            v = span_attributes[k]
+            if isinstance(v, str) and len(v) > _MAX_VALUE_LEN:
+                v = v[: _MAX_VALUE_LEN - 3] + "..."
+            attrs[k] = v
+    
+    if not attrs:
+        return
+    
+    try:
+        event_logger.emit(
+            Event(
+                name=OP_DETAILS_EVENT,
+                attributes=attrs,
+            )
+        )
+    except Exception:  # pragma: no cover - defensive
+        pass
+
+
+def emit_evaluation_result_event(
+    event_logger,
+    *,
+    name: str,
+    score_value: Optional[float] = None,
+    score_label: Optional[str] = None,
+    explanation: Optional[str] = None,
+    response_id: Optional[str] = None,
+    error_type: Optional[str] = None,
+) -> None:
+    """Emit evaluation result event.
+    
+    Args:
+        event_logger: The event logger instance
+        name: Name of the evaluation metric
+        score_value: Numeric score value
+        score_label: Label for the score (e.g., "good", "bad")
+        explanation: Explanation of the evaluation
+        response_id: ID of the response being evaluated
+        error_type: Type of error if evaluation failed
+    """
+    if not event_logger:
+        return
+    if not _enabled(_EVAL_RESULTS_ENABLED_ENV, True):
+        return
+    
+    attrs: Dict[str, Any] = {"gen_ai.evaluation.name": name}
+    if score_value is not None:
+        attrs["gen_ai.evaluation.score.value"] = float(score_value)
+    if score_label is not None:
+        attrs["gen_ai.evaluation.score.label"] = score_label
+    if explanation:
+        attrs["gen_ai.evaluation.explanation"] = (
+            explanation[:4000] if len(explanation) > 4000 else explanation
+        )
+    if response_id:
+        attrs["gen_ai.response.id"] = response_id
+    if error_type:
+        attrs["error.type"] = error_type
+    
+    try:
+        event_logger.emit(
+            Event(
+                name=EVAL_RESULT_EVENT,
+                attributes=attrs,
+            )
+        )
+    except Exception:  # pragma: no cover - defensive
+        pass