Skip to content

Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.

fix: OpenTelemetry Semantic convention compliance in CrewAI, AGNO and Google ADK (#1082)

Ishan Jain6e69fda18c21
diff --git a/sdk/python/pyproject.toml b/sdk/python/pyproject.toml
index 737383a4..57b4a11b 100644
--- a/sdk/python/pyproject.toml
+++ b/sdk/python/pyproject.toml
@@ -1,6 +1,6 @@
[tool.poetry]
name = "openlit"
-version = "1.39.1"
+version = "1.39.0"
description = "OpenTelemetry-native Auto instrumentation library for monitoring LLM Applications and GPUs, facilitating the integration of observability into your GenAI-driven projects"
authors = ["OpenLIT"]
license = "Apache-2.0"
diff --git a/sdk/python/src/openlit/__helpers.py b/sdk/python/src/openlit/__helpers.py
index 235731cd..eede6987 100644
--- a/sdk/python/src/openlit/__helpers.py
+++ b/sdk/python/src/openlit/__helpers.py
@@ -4,6 +4,7 @@ This module has functions to calculate model costs based on tokens and to fetch
"""
import asyncio
+import inspect
import os
import json
import logging
@@ -38,6 +39,12 @@ _framework_llm_span_active: ContextVar[bool] = ContextVar(
"openlit_framework_llm_span_active", default=False
)
+# Prevents duplicate spans when both `litellm` and `litellm.main` are
+# wrapped. The outer wrapper sets this; the inner one checks and skips.
+_litellm_span_active: ContextVar[bool] = ContextVar(
+ "openlit_litellm_span_active", default=False
+)
+
# Set by the LangGraph wrapper before calling wrapped() so the LangChain
# callback handler knows to skip its own top-level graph invocation span
# (which would duplicate the LangGraph wrapper span).
@@ -61,6 +68,21 @@ def is_framework_llm_active() -> bool:
return _framework_llm_span_active.get()
+def set_litellm_span_active():
+ """Set by LiteLLM wrapper; returns a token to reset later."""
+ return _litellm_span_active.set(True)
+
+
+def reset_litellm_span_active(token):
+ """Reset the LiteLLM span flag using the token from set_litellm_span_active."""
+ _litellm_span_active.reset(token)
+
+
+def is_litellm_span_active() -> bool:
+ """Check if a LiteLLM instrumentor is already handling this call."""
+ return _litellm_span_active.get()
+
+
def set_langgraph_wrapper_active():
"""Set by LangGraph wrapper; returns a token to reset later."""
return _langgraph_wrapper_active.set(True)
@@ -201,7 +223,16 @@ def response_as_dict(response):
if hasattr(response, "model_dump"):
return response.model_dump()
elif hasattr(response, "parse"):
- return response_as_dict(response.parse())
+ if inspect.iscoroutinefunction(response.parse):
+ logger.warning("response.parse() is a coroutine function; skipping")
+ return {}
+ parsed = response.parse()
+ if asyncio.iscoroutine(parsed):
+ logger.warning(
+ "response.parse() returned a coroutine; cannot await in sync context"
+ )
+ return {}
+ return response_as_dict(parsed)
else:
return response
@@ -389,7 +420,7 @@ def create_metrics_attributes(
SemanticConvention.GEN_AI_REQUEST_MODEL: request_model,
SemanticConvention.SERVER_ADDRESS: server_address,
SemanticConvention.SERVER_PORT: server_port,
- SemanticConvention.GEN_AI_RESPONSE_MODEL: response_model,
+ SemanticConvention.GEN_AI_RESPONSE_MODEL: response_model or "",
}
# Propagate agent name from context if an agent framework set it.
diff --git a/sdk/python/src/openlit/_instrumentors.py b/sdk/python/src/openlit/_instrumentors.py
index 7998612a..da07111f 100644
--- a/sdk/python/src/openlit/_instrumentors.py
+++ b/sdk/python/src/openlit/_instrumentors.py
@@ -54,6 +54,7 @@ MODULE_NAME_MAP = {
"sarvam": "sarvamai",
"browser-use": "browser_use",
"mcp": "mcp",
+ "google-adk": "google.adk",
# Database instrumentations
"psycopg": "psycopg",
"psycopg-pool": "psycopg_pool",
@@ -124,6 +125,7 @@ INSTRUMENTOR_MAP = {
"sarvam": "openlit.instrumentation.sarvam.SarvamInstrumentor",
"browser-use": "openlit.instrumentation.browser_use.BrowserUseInstrumentor",
"mcp": "openlit.instrumentation.mcp.MCPInstrumentor",
+ "google-adk": "openlit.instrumentation.google_adk.GoogleADKInstrumentor",
# Database instrumentations
"psycopg": "openlit.instrumentation.psycopg.PsycopgInstrumentor",
"psycopg-pool": "openlit.instrumentation.psycopg.PsycopgInstrumentor",
diff --git a/sdk/python/src/openlit/instrumentation/agno/__init__.py b/sdk/python/src/openlit/instrumentation/agno/__init__.py
index b5ecbdd7..8aa93ffa 100644
--- a/sdk/python/src/openlit/instrumentation/agno/__init__.py
+++ b/sdk/python/src/openlit/instrumentation/agno/__init__.py
@@ -1,78 +1,56 @@
-"""Initializer of Auto Instrumentation of Agno Framework Functions"""
+"""
+OpenLIT Agno Instrumentation — OTel GenAI semantic convention compliant.
+
+Targets agno >= 0.6.0. Uses unified general_wrap / async_general_wrap
+wrappers with OPERATION_MAP-driven span names, kinds, and attributes.
+"""
from typing import Collection
import importlib.metadata
from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
from wrapt import wrap_function_wrapper
+
+from openlit.instrumentation.agno.agno import general_wrap
+from openlit.instrumentation.agno.async_agno import (
+ async_general_wrap,
+ async_workflow_wrap,
+)
from openlit.instrumentation.agno.utils import (
resolve_agno_knowledge_target,
resolve_agno_memory_target,
)
-from openlit.instrumentation.agno.agno import (
- agent_run_wrap,
- agent_continue_run_wrap,
- agent_run_tool_wrap,
- agent_add_tool_wrap,
- session_memory_wrap,
- memory_add_wrap,
- memory_search_wrap,
- function_execute_wrap,
- reasoning_wrap,
- vectordb_search_wrap,
- vectordb_upsert_wrap,
- knowledge_search_wrap,
- knowledge_add_wrap,
- workflow_run_wrap,
- team_run_wrap,
- model_run_function_call_wrap,
- function_entrypoint_wrap,
- memory_operation_wrap,
- parallel_execution_wrap,
- reasoning_tool_wrap,
-)
-from openlit.instrumentation.agno.async_agno import (
- async_agent_run_wrap,
- async_agent_run_stream_wrap,
- async_agent_continue_run_wrap,
- async_function_execute_wrap,
- async_reasoning_wrap,
- async_team_run_stream_wrap,
- async_workflow_run_wrap,
- async_team_run_wrap,
- async_model_run_function_call_wrap,
- async_function_entrypoint_wrap,
-)
_instruments = ("agno >= 0.6.0",)
+# === ALWAYS-ON OPERATIONS ===
+# Each tuple: (module, method, operation_key, sync_type)
WORKFLOW_OPERATIONS = [
- # Core Agent Execution Methods
- "Agent.run",
- "Agent.continue_run",
- # Team Operations
- "Agent.create",
+ # Agent construction — create_agent spans
+ ("agno.agent.agent", "Agent.__init__", "agent_init", "sync"),
+ # Agent execution — invoke_agent
+ ("agno.agent.agent", "Agent.run", "agent_run", "sync"),
+ ("agno.agent.agent", "Agent.arun", "agent_arun", "async"),
+ ("agno.agent.agent", "Agent.continue_run", "agent_continue_run", "sync"),
+ ("agno.agent.agent", "Agent.acontinue_run", "agent_acontinue_run", "async"),
]
-COMPONENT_OPERATIONS = [
- # Tool Management
- "Agent.add_tool",
- "Agent.set_tools",
- # Memory Operations
- "Agent.get_session_summary",
- "Agent.get_user_memories",
+# === DETAILED-TRACING OPERATIONS ===
+# Wrapped only when detailed_tracing=True
+DETAILED_OPERATIONS = [
+ # Tool execution — execute_tool (FunctionCall.execute/aexecute)
+ ("agno.tools.function", "FunctionCall.execute", "tool_execute", "sync"),
+ ("agno.tools.function", "FunctionCall.aexecute", "tool_aexecute", "async"),
+ # Team operations — invoke_workflow
+ ("agno.team.team", "Team.run", "team_run", "sync"),
+ ("agno.team.team", "Team.arun", "team_arun", "async"),
+ # VectorDB operations — retrieval / upsert
+ ("agno.vectordb.base", "VectorDb.search", "vectordb_search", "sync"),
+ ("agno.vectordb.base", "VectorDb.upsert", "vectordb_upsert", "sync"),
]
class AgnoInstrumentor(BaseInstrumentor):
- """
- An instrumentor for Agno Framework's agent library.
- """
-
- def __init__(self):
- """Initialize the AgnoInstrumentor."""
- super().__init__()
- self._original_thread_pool_submit = None
- self._original_runtime_detach = None
+ """OTel GenAI semantic convention compliant instrumentor for Agno."""
def instrumentation_dependencies(self) -> Collection[str]:
return _instruments
@@ -87,18 +65,25 @@ class AgnoInstrumentor(BaseInstrumentor):
disable_metrics = kwargs.get("disable_metrics")
detailed_tracing = kwargs.get("detailed_tracing", False)
- # Get version
try:
version = importlib.metadata.version("agno")
except importlib.metadata.PackageNotFoundError:
version = "unknown"
- # Patch OpenTelemetry's context detach to suppress benign errors in async/threaded scenarios
- self._patch_otel_context_detach()
+ wrap_args = (
+ version,
+ environment,
+ application_name,
+ tracer,
+ pricing_info,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ )
# Detect agno version for method name compatibility.
- # agno < 2.5.3 used private methods (_run, _arun, _arun_stream, _run_tool).
- # agno >= 2.5.3 replaced them with public methods (run, arun) and removed _run_tool.
+ # agno < 2.5.3 used private methods (_run, _arun, _arun_stream).
+ # agno >= 2.5.3 replaced them with public methods (run, arun).
try:
from agno.agent.agent import Agent as _AgnoAgent
except ImportError:
@@ -106,613 +91,181 @@ class AgnoInstrumentor(BaseInstrumentor):
_has_private_run = _AgnoAgent is not None and hasattr(_AgnoAgent, "_run")
- # Workflow Operations (Always Instrumented)
- _run_method = "_run" if _has_private_run else "run"
- wrap_function_wrapper(
- "agno.agent.agent",
- f"Agent.{_run_method}",
- agent_run_wrap(
- f"agent.{_run_method}",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- wrap_function_wrapper(
- "agno.agent.agent",
- "Agent.continue_run",
- agent_continue_run_wrap(
- "agent.continue_run",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
+ # Build the operations list with version-aware method names
+ ops = []
- # CRITICAL: Agent._run_tool is the bridge between agent and tool execution.
- # Removed in agno >= 2.5.3 — only wrap if it exists.
- if _AgnoAgent is not None and hasattr(_AgnoAgent, "_run_tool"):
- wrap_function_wrapper(
- "agno.agent.agent",
- "Agent._run_tool",
- agent_run_tool_wrap(
- "agent._run_tool",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
+ # Agent.__init__ — always wrap for create_agent spans
+ ops.append(("agno.agent.agent", "Agent.__init__", "agent_init", "sync"))
- # Async Operations
- _arun_method = "_arun" if _has_private_run else "arun"
- wrap_function_wrapper(
- "agno.agent.agent",
- f"Agent.{_arun_method}",
- async_agent_run_wrap(
- f"agent.{_arun_method}",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
+ # Agent run methods
+ run_method = "_run" if _has_private_run else "run"
+ arun_method = "_arun" if _has_private_run else "arun"
+ ops.append(("agno.agent.agent", f"Agent.{run_method}", "agent_run", "sync"))
+ ops.append(("agno.agent.agent", f"Agent.{arun_method}", "agent_arun", "async"))
+ ops.append(
+ ("agno.agent.agent", "Agent.continue_run", "agent_continue_run", "sync")
+ )
+ ops.append(
+ ("agno.agent.agent", "Agent.acontinue_run", "agent_acontinue_run", "async")
)
- # Agent._arun_stream removed in agno >= 2.5.3 (streaming merged into arun).
+ # Wrap Agent._arun_stream if it exists (agno < 2.5.3)
if _AgnoAgent is not None and hasattr(_AgnoAgent, "_arun_stream"):
- wrap_function_wrapper(
- "agno.agent.agent",
- "Agent._arun_stream",
- async_agent_run_stream_wrap(
- "agent._arun_stream",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
+ ops.append(
+ ("agno.agent.agent", "Agent._arun_stream", "agent_arun", "async")
)
- wrap_function_wrapper(
- "agno.agent.agent",
- "Agent.acontinue_run",
- async_agent_continue_run_wrap(
- "agent.acontinue_run",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- # Component Operations (Detailed Tracing Only) - Updated to match actual agno structure
+ # -- always-on operations --
+ for module, method, op_key, sync_type in ops:
+ try:
+ if sync_type == "async":
+ wrapper = async_general_wrap(op_key, *wrap_args)
+ else:
+ wrapper = general_wrap(op_key, *wrap_args)
+ wrap_function_wrapper(module, method, wrapper)
+ except Exception:
+ pass
+
+ # -- detailed-tracing operations --
if detailed_tracing:
- # CRITICAL: Bridge span context between agent and tool execution
- wrap_function_wrapper(
- "agno.models.base",
- "Model.run_function_call",
- model_run_function_call_wrap(
- "model.run_function_call",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- # CRITICAL: Bridge span context for async function calls
- wrap_function_wrapper(
- "agno.models.base",
- "Model.arun_function_call",
- async_model_run_function_call_wrap(
- "model.arun_function_call",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- # NOTE: Removed instrumentation for Model.run_function_calls and Model.arun_function_calls
- # These methods are iterators/async iterators that call individual function calls
- # Individual function calls are already instrumented through Model.run_function_call and Model.arun_function_call
- # Instrumenting the batch methods causes span hierarchy issues and is redundant
-
- # CRITICAL: Memory operations that bypass model bridge
-
- # Dynamically determine the correct memory module/class based on the installed
- # agno version. 2.x versions expose MemoryManager in ``agno.memory.manager``
- # while older 1.x versions expose Memory in ``agno.memory.v2.memory``.
-
- memory_module, memory_class = resolve_agno_memory_target()
-
- if memory_module is not None:
- # Wrap memory add/search exactly once using the dedicated wrappers to avoid
- # duplicate spans and performance overhead.
- wrap_function_wrapper(
- memory_module,
- f"{memory_class}.add_user_memory",
- memory_add_wrap(
- "memory.add_user_memory",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- wrap_function_wrapper(
- memory_module,
- f"{memory_class}.search_user_memories",
- memory_search_wrap(
- "memory.search_user_memories",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- # VectorDB Operations (base class)
- wrap_function_wrapper(
- "agno.vectordb.base",
- "VectorDb.search",
- vectordb_search_wrap(
- "vectordb.search",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
+ # Tool execution via FunctionCall
+ for module, method, op_key, sync_type in [
+ ("agno.tools.function", "FunctionCall.execute", "tool_execute", "sync"),
+ (
+ "agno.tools.function",
+ "FunctionCall.aexecute",
+ "tool_aexecute",
+ "async",
),
- )
-
- wrap_function_wrapper(
- "agno.vectordb.base",
- "VectorDb.upsert",
- vectordb_upsert_wrap(
- "vectordb.upsert",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- # Dynamically determine the correct knowledge module/class based on the installed
- # agno version. 2.x versions expose `Knowledge` in `agno.knowledge.knowledge`
- # while older 1.x versions expose `AgentKnowledge` in `agno.knowledge.agent`.
- knowledge_module, knowledge_class = resolve_agno_knowledge_target()
+ ]:
+ try:
+ if sync_type == "async":
+ wrapper = async_general_wrap(op_key, *wrap_args)
+ else:
+ wrapper = general_wrap(op_key, *wrap_args)
+ wrap_function_wrapper(module, method, wrapper)
+ except Exception:
+ pass
- if knowledge_module is not None:
- # Knowledge Operations
- wrap_function_wrapper(
- knowledge_module,
- f"{knowledge_class}.search",
- knowledge_search_wrap(
- "knowledge.search",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
+ # Team operations
+ try:
+ from agno.team.team import Team # pylint: disable=import-error
+ except ImportError:
+ Team = None
- # agno 2.x versions do not have load method
- if hasattr(knowledge_class, "load"):
- wrap_function_wrapper(
- knowledge_module,
- f"{knowledge_class}.load",
- knowledge_add_wrap(
- "knowledge.load",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
+ if Team is not None:
+ # Team._arun_stream (agno < 2.5.3 private methods)
+ if hasattr(Team, "_arun_stream"):
+ try:
+ wrap_function_wrapper(
+ "agno.team.team",
+ "Team._arun_stream",
+ async_general_wrap("team_arun", *wrap_args),
+ )
+ wrap_function_wrapper(
+ "agno.team.team",
+ "Team._arun",
+ async_general_wrap("team_arun", *wrap_args),
+ )
+ except Exception:
+ pass
+ else:
+ try:
+ wrap_function_wrapper(
+ "agno.team.team",
+ "Team.arun",
+ async_general_wrap("team_arun", *wrap_args),
+ )
+ except Exception:
+ pass
- # agno 2.x versions do not have add_document_to_knowledge_base method
- if hasattr(knowledge_class, "add_document_to_knowledge_base"):
+ try:
wrap_function_wrapper(
- knowledge_module,
- f"{knowledge_class}.add_document_to_knowledge_base",
- knowledge_add_wrap(
- "knowledge.add_document_to_knowledge_base",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
+ "agno.team.team",
+ "Team.run",
+ general_wrap("team_run", *wrap_args),
)
+ except Exception:
+ pass
+ # Workflow operations
try:
- from agno.workflow.workflow import Workflow
+ from agno.workflow.workflow import Workflow # pylint: disable=import-error
except ImportError:
Workflow = None
- # agno 2.x versions do not have Workflow.run_workflow and Workflow.arun_workflow methods
- if Workflow is not None and hasattr(Workflow, "run_workflow"):
- wrap_function_wrapper(
- "agno.workflow.workflow",
- "Workflow.run_workflow",
- workflow_run_wrap(
- "workflow.run_workflow",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- wrap_function_wrapper(
- "agno.workflow.workflow",
- "Workflow.arun_workflow",
- async_workflow_run_wrap(
- "workflow.arun_workflow",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- # Async Workflow Operations (actual methods that exist)
- wrap_function_wrapper(
- "agno.workflow.workflow",
- "Workflow.arun",
- async_workflow_run_wrap(
- "workflow.arun",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- # Team Operations
-
- try:
- from agno.team.team import Team # pylint: disable=import-error
- except ImportError:
- Team = None
- # agno 2.x versions do use Team._arun_stream and Team._arun methods
- if Team is not None and hasattr(Team, "_arun_stream"):
- wrap_function_wrapper(
- "agno.team.team",
- "Team._arun_stream",
- async_team_run_stream_wrap(
- "team._arun_stream",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- wrap_function_wrapper(
- "agno.team.team",
- "Team._arun",
- async_team_run_wrap(
- "team._arun",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- else:
- # agno 2.x versions do not have Team._arun_stream
- # Team Async Operations (actual methods that exist)
- wrap_function_wrapper(
- "agno.team.team",
- "Team.arun",
- async_team_run_wrap(
- "team.arun",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- wrap_function_wrapper(
- "agno.team.team",
- "Team.run",
- team_run_wrap(
- "team.run",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- # Note: VectorDb class does not have async_search or async_upsert methods
-
- # Note: AgentKnowledge class does not have async_search method
-
- # Note: AgentKnowledge class does not have async_load or async_add_document_to_knowledge_base methods
+ if Workflow is not None:
+ if hasattr(Workflow, "run_workflow"):
+ try:
+ wrap_function_wrapper(
+ "agno.workflow.workflow",
+ "Workflow.run_workflow",
+ general_wrap("workflow_run", *wrap_args),
+ )
+ except Exception:
+ pass
+ if hasattr(Workflow, "arun_workflow"):
+ try:
+ wrap_function_wrapper(
+ "agno.workflow.workflow",
+ "Workflow.arun_workflow",
+ async_workflow_wrap("workflow_arun", *wrap_args),
+ )
+ except Exception:
+ pass
- # NOTE: Removed duplicate tool execution instrumentation
- # The bridge spans from Model.run_function_call provide sufficient tracing
- # without creating redundant spans for FunctionCall.execute/aexecute
+ try:
+ wrap_function_wrapper(
+ "agno.workflow.workflow",
+ "Workflow.arun",
+ async_workflow_wrap("workflow_arun", *wrap_args),
+ )
+ except Exception:
+ pass
- # Reasoning Operations
+ # VectorDB operations
try:
- from agno.agent.agent import Agent
- except ImportError:
- Agent = None
-
- # agno 2.x versions do not have Agent.reason and Agent.areason methods
- if Agent is not None and hasattr(Agent, "reason"):
wrap_function_wrapper(
- "agno.agent.agent",
- "Agent.reason",
- reasoning_wrap(
- "agent.reason",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
+ "agno.vectordb.base",
+ "VectorDb.search",
+ general_wrap("vectordb_search", *wrap_args),
)
-
wrap_function_wrapper(
- "agno.agent.agent",
- "Agent.areason",
- async_reasoning_wrap(
- "agent.areason",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
+ "agno.vectordb.base",
+ "VectorDb.upsert",
+ general_wrap("vectordb_upsert", *wrap_args),
)
+ except Exception:
+ pass
- # Original Component Operations
- if detailed_tracing:
- wrap_function_wrapper(
- "agno.agent.agent",
- "Agent.add_tool",
- agent_add_tool_wrap(
- "agent.add_tool",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- # Note: Agent class does not have async_add_tool method
-
- wrap_function_wrapper(
- "agno.agent.agent",
- "Agent.get_session_summary",
- session_memory_wrap(
- "agent.get_session_summary",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- wrap_function_wrapper(
- "agno.agent.agent",
- "Agent.get_user_memories",
- session_memory_wrap(
- "agent.get_user_memories",
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
-
- # Note: Agent class does not have async_get_session_summary or async_get_user_memories methods
-
- # CRITICAL: Parallel execution operations for context preservation
- # Note: Parallel class doesn't have a run method, context is preserved via Model.run_function_calls
-
- # NOTE: Team._make_memories_and_summaries method was removed in recent Agno versions
- # Only Team._make_memories exists now. If parallel execution instrumentation is needed,
- # it should be added for Team._make_memories instead.
-
- # NOTE: Removed duplicate reasoning tool instrumentation
- # The bridge spans from Model.run_function_call provide sufficient tracing
- # without creating redundant spans for ReasoningTools.think/analyze
-
- def _patch_otel_context_detach(self):
- """
- Patch OpenTelemetry's context detach to suppress benign cross-context errors.
-
- Agno uses ThreadPoolExecutor internally for tool execution, which can cause
- context tokens to be detached in a different context than where they were created.
- This is benign but OTel logs it as an error. We suppress the logging for these cases.
- """
- import logging
- from opentelemetry.context import _RUNTIME_CONTEXT
-
- # Suppress the specific logger that logs "Failed to detach context"
- otel_context_logger = logging.getLogger("opentelemetry.context")
- otel_context_logger.setLevel(logging.CRITICAL)
-
- # Also patch the runtime context's detach to not raise for cross-context errors
- original_detach = _RUNTIME_CONTEXT.detach
-
- def patched_detach(token):
- """Detach context token, suppressing cross-context ValueError"""
- try:
- original_detach(token)
- except ValueError as e:
- # Silently ignore "was created in a different Context" errors
- # These occur when Agno's ThreadPoolExecutor runs tools in different threads
- if "was created in a different Context" not in str(e):
- raise
-
- _RUNTIME_CONTEXT.detach = patched_detach
- self._original_runtime_detach = original_detach
-
- def _patch_thread_pool_executor(self):
- """
- CRITICAL: Patch ThreadPoolExecutor.submit globally to preserve OpenTelemetry context.
- This fixes the broken span hierarchy caused by agno's extensive use of threading.
- """
- from concurrent.futures import ThreadPoolExecutor
- from opentelemetry import context as context_api
-
- # Store original submit method
- original_submit = ThreadPoolExecutor.submit
-
- def context_preserving_submit(self, func, *args, **kwargs):
- """Submit function while preserving OpenTelemetry context"""
- # Capture current context
- current_context = context_api.get_current()
-
- def context_wrapper(*wrapper_args, **wrapper_kwargs):
- # OpenTelemetry context management for threaded execution
- # Note: In async/threaded scenarios, the context token may become invalid
- # if the execution context changes. We handle this gracefully.
- token = None
+ # Memory operations
+ memory_module, memory_class = resolve_agno_memory_target()
+ if memory_module is not None:
try:
- token = context_api.attach(current_context)
+ wrap_function_wrapper(
+ memory_module,
+ f"{memory_class}.add_user_memory",
+ general_wrap("memory_add", *wrap_args),
+ )
+ wrap_function_wrapper(
+ memory_module,
+ f"{memory_class}.search_user_memories",
+ general_wrap("memory_search", *wrap_args),
+ )
except Exception:
- # If attach fails, continue without context propagation
pass
+ # Knowledge operations
+ knowledge_module, knowledge_class = resolve_agno_knowledge_target()
+ if knowledge_module is not None:
try:
- return func(*wrapper_args, **wrapper_kwargs)
- finally:
- if token is not None:
- try:
- context_api.detach(token)
- except Exception:
- # Silently ignore detach errors - can happen when context changes
- # between attach and detach in async/threaded scenarios
- pass
-
- return original_submit(self, context_wrapper, *args, **kwargs)
-
- # Apply the patch
- ThreadPoolExecutor.submit = context_preserving_submit
-
- # Store original for potential uninstrumentation
- self._original_thread_pool_submit = original_submit
+ wrap_function_wrapper(
+ knowledge_module,
+ f"{knowledge_class}.search",
+ general_wrap("knowledge_search", *wrap_args),
+ )
+ except Exception:
+ pass
def _uninstrument(self, **kwargs):
- # Restore original ThreadPoolExecutor.submit if it was patched
- if hasattr(self, "_original_thread_pool_submit"):
- from concurrent.futures import ThreadPoolExecutor
-
- ThreadPoolExecutor.submit = self._original_thread_pool_submit
+ pass
diff --git a/sdk/python/src/openlit/instrumentation/agno/agno.py b/sdk/python/src/openlit/instrumentation/agno/agno.py
index 12d8e288..42a36847 100644
--- a/sdk/python/src/openlit/instrumentation/agno/agno.py
+++ b/sdk/python/src/openlit/instrumentation/agno/agno.py
@@ -1,410 +1,29 @@
"""
-Module for monitoring Agno agent framework operations.
+Agno sync wrapper — OTel GenAI semantic convention compliant.
+
+Uses dynamic SpanKind from SPAN_KIND_MAP and deduplication contextvars
+to prevent double-spanning (Team.run -> Agent.run internally).
"""
-import logging
import time
-from opentelemetry.trace import Status, StatusCode, SpanKind
from opentelemetry import context as context_api
-from openlit.__helpers import (
- handle_exception,
-)
+from opentelemetry.trace import Link
+from openlit.__helpers import handle_exception
from openlit.instrumentation.agno.utils import (
- process_agent_request,
- process_tool_request,
- process_memory_request,
- process_reasoning_request,
- process_vectordb_request,
- process_knowledge_request,
- process_workflow_request,
- process_team_request,
+ process_agno_response,
+ emit_create_agent_spans,
+ OPERATION_MAP,
+ get_span_kind,
+ generate_span_name,
+ _agno_team_active,
+ _agno_workflow_active,
+ _current_agent_model_info,
+ _compute_agent_model_info,
+ _agno_parent_agent,
)
-from openlit.semcov import SemanticConvention
-
-# Initialize logger for Agno monitoring
-logger = logging.getLogger(__name__)
-
-
-def agent_run_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Agent.run method with comprehensive instrumentation using process functions only.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- # Extract agent name for span naming with fallback to agent_id
- agent_name = (
- getattr(instance, "name", None)
- or getattr(instance, "agent_id", None)
- or "default_agent"
- )
- span_name = f"agent {agent_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
- response = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_agent_request(
- span,
- instance,
- args,
- kwargs,
- response,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
- )
-
- # Mark span as successful
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- # Handle instrumentation exceptions - log but don't raise
- handle_exception(span, e)
- logger.error("Error in agent.run trace creation: %s", e)
-
- return response
-
- return wrapper
-
-
-def agent_run_tool_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Agent._run_tool method - the critical bridge between agent and tool execution.
- This method runs within the agent context and coordinates tool execution.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- # Extract tool information for span naming
- tool = args[1] if len(args) > 1 else None # tool: ToolExecution
- tool_name = "unknown_tool"
- if tool and hasattr(tool, "name"):
- tool_name = tool.name
- elif tool and hasattr(tool, "function") and hasattr(tool.function, "name"):
- tool_name = tool.function.name
-
- span_name = f"agent run tool {tool_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- tool_name,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in agent._run_tool trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def agent_continue_run_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Agent.continue_run method.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- agent_name = getattr(instance, "name", "unknown")
- span_name = f"continue {agent_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_agent_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in agent.continue_run trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def agent_add_tool_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Agent.add_tool method for detailed tracing.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- agent_name = getattr(instance, "name", "unknown")
- span_name = f"agent {agent_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
- )
- span.set_status(Status(StatusCode.OK))
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in agent.add_tool trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def session_memory_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Agent memory operations (get_session_summary, get_user_memories).
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- # Extract method name from endpoint
- method_name = gen_ai_endpoint.split(".")[-1]
- span_name = f"memory {method_name.replace('get_', '').replace('_', ' ')}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute memory operation with timing
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- # Extract method name for operation type
- operation_type = method_name.replace("get_", "").replace("_", " ")
- process_memory_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- operation_type,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in memory operation trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def model_run_function_call_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Model.run_function_call method to bridge agent and tool span context.
- This is the critical method that connects agent execution to tool execution.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- # Extract function call information for span naming
- function_call = args[0] if args else kwargs.get("function_call", None)
- function_name = None
-
- if function_call:
- # Extract function name from the FunctionCall object
- if hasattr(function_call, "function") and hasattr(
- function_call.function, "name"
- ):
- function_name = function_call.function.name
- elif hasattr(function_call, "name"):
- function_name = function_call.name
-
- # Skip creating span if we can't identify the function
- if not function_name or function_name == "unknown_function":
- return wrapped(*args, **kwargs)
-
- span_name = f"tool {function_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
- function_call,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- function_name,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in model.run_function_call trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# Tools Component Wrappers
-def function_call_wrap(
+def general_wrap(
gen_ai_endpoint,
version,
environment,
@@ -415,944 +34,104 @@ def function_call_wrap(
metrics,
disable_metrics,
):
- """
- Wrap Agno Function call method for tool execution tracing.
- """
+ """Create a sync wrapper for an Agno operation."""
def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
return wrapped(*args, **kwargs)
- # Extract function information
- function_name = getattr(
- instance, "name", getattr(instance, "__name__", "unknown_function")
- )
- span_name = f"tool {function_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute function with timing
- start_time = time.time()
+ # agent_init: emit create_agent span, then return
+ if gen_ai_endpoint == "agent_init":
result = wrapped(*args, **kwargs)
-
try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
+ ctx = emit_create_agent_spans(
+ tracer,
instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in tool execution trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def toolkit_run_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Toolkit run method for toolkit execution tracing.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- # Extract toolkit information
- toolkit_name = getattr(
- instance,
- "name",
- getattr(instance, "__class__", {}).get("__name__", "unknown_toolkit"),
- )
- span_name = f"toolkit {toolkit_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute toolkit with timing
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
environment,
application_name,
- metrics,
capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
)
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in toolkit execution trace creation: %s", e)
-
+ if ctx:
+ instance._openlit_creation_context = ctx
+ except Exception:
+ pass
return result
- return wrapper
+ operation_type = OPERATION_MAP.get(gen_ai_endpoint, "invoke_agent")
+ span_kind = get_span_kind(operation_type)
+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)
+ # Deduplication: set flag so nested calls know a span already exists
+ dedup_token = None
+ if gen_ai_endpoint == "team_run":
+ dedup_token = _agno_team_active.set(True)
+ elif gen_ai_endpoint == "workflow_run":
+ dedup_token = _agno_workflow_active.set(True)
-def function_entrypoint_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Function.entrypoint method to catch direct tool executions that bypass Model.run_function_call.
- This ensures ALL tool executions maintain span context.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- # Extract function information for span naming
- function_name = getattr(instance, "name", None) or getattr(
- instance, "__name__", "unknown_function"
- )
- span_name = f"tool {function_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- function_name,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in function.entrypoint trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# Tool Execution Component Wrappers
-def function_execute_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno FunctionCall.execute method for tool execution tracing using process functions only.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- # Extract function information
- function_name = getattr(instance.function, "name", "unknown_function")
- span_name = f"tool {function_name}"
-
- # CRITICAL: Capture current OpenTelemetry context to ensure proper nesting
- current_context = context_api.get_current()
-
- with tracer.start_as_current_span(
- span_name, kind=SpanKind.INTERNAL, context=current_context
- ) as span:
- # Execute tool with timing
- start_time = time.time()
- # CRITICAL: Set the span context as current for nested calls
- token = context_api.attach(
- context_api.set_value("current_span", span, current_context)
- )
- try:
- result = wrapped(*args, **kwargs)
- finally:
- context_api.detach(token)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- function_name,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in tool execution trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def parallel_execution_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap parallel execution methods to preserve OpenTelemetry context through ThreadPoolExecutor.
- This is critical for maintaining span hierarchy in parallel workflows and team operations.
- """
- from concurrent.futures import ThreadPoolExecutor
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- # Capture current OpenTelemetry context
- current_context = context_api.get_current()
-
- # Patch ThreadPoolExecutor.submit to preserve context
- original_submit = ThreadPoolExecutor.submit
-
- def context_preserving_submit(
- executor_self, func, *submit_args, **submit_kwargs
- ):
- """Submit function to executor while preserving OpenTelemetry context"""
-
- def context_wrapper(*wrapper_args, **wrapper_kwargs):
- # Restore the OpenTelemetry context in the thread
- token = context_api.attach(current_context)
- try:
- return func(*wrapper_args, **wrapper_kwargs)
- finally:
- context_api.detach(token)
-
- return original_submit(
- executor_self, context_wrapper, *submit_args, **submit_kwargs
- )
-
- # Temporarily patch the submit method
- ThreadPoolExecutor.submit = context_preserving_submit
+ # Propagate agent model info and instance to child execute_tool spans
+ model_info_token = None
+ parent_agent_token = None
+ if gen_ai_endpoint.startswith("agent_"):
+ model_info_token = _current_agent_model_info.set(
+ _compute_agent_model_info(instance)
+ )
+ parent_agent_token = _agno_parent_agent.set(instance)
+
+ # Span links: connect back to create_agent spans
+ links = []
+ if gen_ai_endpoint == "team_run":
+ members = (
+ getattr(instance, "members", None)
+ or getattr(instance, "agents", None)
+ or []
+ )
+ for member in members:
+ creation_ctx = getattr(member, "_openlit_creation_context", None)
+ if creation_ctx:
+ links.append(Link(creation_ctx))
+ elif gen_ai_endpoint.startswith("agent_") and gen_ai_endpoint != "agent_init":
+ creation_ctx = getattr(instance, "_openlit_creation_context", None)
+ if creation_ctx:
+ links.append(Link(creation_ctx))
try:
- result = wrapped(*args, **kwargs)
+ with tracer.start_as_current_span(
+ span_name, kind=span_kind, links=links
+ ) as span:
+ start_time = time.time()
+ try:
+ response = wrapped(*args, **kwargs)
+
+ process_agno_response(
+ response,
+ gen_ai_endpoint,
+ span,
+ instance,
+ args,
+ kwargs,
+ start_time,
+ environment,
+ application_name,
+ metrics,
+ capture_message_content,
+ disable_metrics,
+ version,
+ )
+
+ return response
+
+ except Exception as e:
+ handle_exception(span, e)
+ raise
finally:
- # Restore original submit method
- ThreadPoolExecutor.submit = original_submit
-
- return result
-
- return wrapper
-
-
-def reasoning_tool_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap reasoning tools (think, analyze) to maintain proper span hierarchy.
- These tools were previously creating disconnected spans.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- # Extract tool name from endpoint
- tool_name = gen_ai_endpoint.split(".")[-1]
- span_name = f"reasoning {tool_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_reasoning_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- tool_name,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in reasoning tool trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# Reasoning Component Wrappers
-def reasoning_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Agent.reason method for reasoning operation tracing.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- agent_name = getattr(instance, "name", "unknown_agent")
- span_name = f"reasoning {agent_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute reasoning with timing
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- # Use reasoning operation for reasoning requests
- process_reasoning_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- "reasoning",
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in reasoning trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def memory_operation_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Memory operations that bypass Model.run_function_call to maintain span context.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- # Extract operation name from endpoint
- operation_name = gen_ai_endpoint.split(".")[-1]
- span_name = f"memory {operation_name.replace('_', ' ')}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_memory_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- operation_name.replace("_", " "),
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in memory operation trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# Memory Component Wrappers
-def memory_add_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Memory add method for memory storage tracing using process functions only.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- span_name = "memory add"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute memory operation with timing
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_memory_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- "add",
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in memory add trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def memory_search_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Memory search method for memory retrieval tracing using process functions only.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- span_name = "memory search"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute memory search with timing
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_memory_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- "search",
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in memory search trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# VectorDB Component Wrappers
-def vectordb_search_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno VectorDb search method for vector search tracing using process functions only.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- span_name = "vectordb search"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- # Execute vectordb search with timing
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_vectordb_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- "search",
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in vectordb search trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def vectordb_upsert_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno VectorDb upsert method for vector upsert tracing using process functions only.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- span_name = "vectordb upsert"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- # Execute vectordb upsert with timing
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_vectordb_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- "upsert",
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in vectordb upsert trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# Knowledge Component Wrappers
-def knowledge_search_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno AgentKnowledge search method for knowledge search tracing using process functions only.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- span_name = "knowledge search"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute knowledge search with timing
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_knowledge_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- "search",
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in knowledge search trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def knowledge_add_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno AgentKnowledge add method for knowledge addition tracing using process functions only.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- span_name = "knowledge add"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute knowledge addition with timing
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_knowledge_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- "add",
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in knowledge add trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# Workflow Component Wrappers
-def workflow_run_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Workflow run method for workflow execution tracing using process functions only.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- workflow_name = getattr(instance, "name", "unknown_workflow")
- span_name = f"workflow {workflow_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- # Execute workflow with timing
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_workflow_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in workflow run trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# Team Component Wrappers
-def team_run_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Team run method for team execution tracing.
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- # CRITICAL: Suppression check to prevent recursive instrumentation
- if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
- return wrapped(*args, **kwargs)
-
- team_name = getattr(instance, "name", "unknown_team")
- span_name = f"team {team_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- # Execute team with timing
- start_time = time.time()
- result = wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_team_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in team run trace creation: %s", e)
-
- return result
+ if gen_ai_endpoint == "team_run" and dedup_token is not None:
+ _agno_team_active.reset(dedup_token)
+ elif gen_ai_endpoint == "workflow_run" and dedup_token is not None:
+ _agno_workflow_active.reset(dedup_token)
+ if model_info_token is not None:
+ _current_agent_model_info.reset(model_info_token)
+ if parent_agent_token is not None:
+ _agno_parent_agent.reset(parent_agent_token)
return wrapper
diff --git a/sdk/python/src/openlit/instrumentation/agno/async_agno.py b/sdk/python/src/openlit/instrumentation/agno/async_agno.py
index 794c1831..9bbd4c79 100644
--- a/sdk/python/src/openlit/instrumentation/agno/async_agno.py
+++ b/sdk/python/src/openlit/instrumentation/agno/async_agno.py
@@ -1,30 +1,32 @@
"""
-Module for monitoring Agno agent framework async operations.
+Agno async wrapper — OTel GenAI semantic convention compliant.
+
+Mirrors the sync wrapper with async/await support and checks
+deduplication flags set by the sync wrapper to prevent double-spanning.
+Handles streaming via async generator wrappers.
"""
import logging
import time
-from opentelemetry.trace import Status, StatusCode, SpanKind
-from openlit.__helpers import (
- handle_exception,
-)
+from opentelemetry import context as context_api
+from opentelemetry.trace import Link
+from openlit.__helpers import handle_exception
from openlit.instrumentation.agno.utils import (
- process_agent_request,
- process_tool_request,
- process_memory_request,
- process_reasoning_request,
- process_vectordb_request,
- process_knowledge_request,
- process_workflow_request,
- process_team_request,
+ process_agno_response,
+ OPERATION_MAP,
+ get_span_kind,
+ generate_span_name,
+ _agno_team_active,
+ _agno_workflow_active,
+ _current_agent_model_info,
+ _compute_agent_model_info,
+ _agno_parent_agent,
)
-from openlit.semcov import SemanticConvention
-# Initialize logger for Agno async monitoring
logger = logging.getLogger(__name__)
-def async_agent_run_wrap(
+def async_general_wrap(
gen_ai_endpoint,
version,
environment,
@@ -35,101 +37,166 @@ def async_agent_run_wrap(
metrics,
disable_metrics,
):
- """
- Wrap Agno Agent.arun method with comprehensive async instrumentation using process functions only.
- """
+ """Create an async wrapper for an Agno operation."""
def wrapper(wrapped, instance, args, kwargs):
- # Extract agent name for span naming with fallback to agent_id
- agent_name = (
- getattr(instance, "name", None)
- or getattr(instance, "agent_id", None)
- or "default_agent"
- )
- span_name = f"agent {agent_name}"
-
- # agno >= 2.5.3: Agent.arun(stream=True) returns an async generator directly,
- # not a coroutine. We use a plain def wrapper (not async def) so we can return
- # either an async gen or a coroutine transparently — an async def wrapper always
- # wraps its return value inside a new coroutine, breaking the async gen path.
- if kwargs.get("stream", False):
+ if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
+ return wrapped(*args, **kwargs)
+
+ # Deduplication: if the sync variant already created a span, pass through
+ if gen_ai_endpoint == "team_arun" and _agno_team_active.get():
+ return wrapped(*args, **kwargs)
+ if gen_ai_endpoint == "workflow_arun" and _agno_workflow_active.get():
+ return wrapped(*args, **kwargs)
+
+ # Streaming agent/team runs: return async generator wrapper
+ if gen_ai_endpoint in ("agent_arun", "agent_acontinue_run") and kwargs.get(
+ "stream", False
+ ):
return _arun_stream_wrapper(
wrapped,
instance,
args,
kwargs,
- span_name,
+ gen_ai_endpoint,
tracer,
- pricing_info,
+ version,
environment,
application_name,
- metrics,
+ pricing_info,
capture_message_content,
+ metrics,
disable_metrics,
+ )
+
+ if gen_ai_endpoint == "team_arun" and kwargs.get("stream", False):
+ return _team_arun_stream_wrapper(
+ wrapped,
+ instance,
+ args,
+ kwargs,
+ gen_ai_endpoint,
+ tracer,
version,
+ environment,
+ application_name,
+ pricing_info,
+ capture_message_content,
+ metrics,
+ disable_metrics,
)
- # Non-streaming: return the coroutine from the inner async function directly.
- return _arun_wrapper(
+ # Non-streaming: return coroutine
+ return _async_invoke(
wrapped,
instance,
args,
kwargs,
- span_name,
+ gen_ai_endpoint,
tracer,
- pricing_info,
+ version,
environment,
application_name,
- metrics,
+ pricing_info,
capture_message_content,
+ metrics,
disable_metrics,
- version,
)
return wrapper
-async def _arun_wrapper(
+async def _async_invoke(
wrapped,
instance,
args,
kwargs,
- span_name,
+ gen_ai_endpoint,
tracer,
- pricing_info,
+ version,
environment,
application_name,
- metrics,
+ pricing_info,
capture_message_content,
+ metrics,
disable_metrics,
- version,
):
- """Coroutine helper for the non-streaming Agent.arun path."""
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
- response = await wrapped(*args, **kwargs)
- try:
- process_agent_request(
- span,
- instance,
- args,
- kwargs,
- response,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
- )
- span.set_status(Status(StatusCode.OK))
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async agent.arun trace creation: %s", e)
- return response
+ """Coroutine helper for non-streaming async operations."""
+ operation_type = OPERATION_MAP.get(gen_ai_endpoint, "invoke_agent")
+ span_kind = get_span_kind(operation_type)
+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)
+
+ # Propagate agent model info and instance to child execute_tool spans
+ model_info_token = None
+ parent_agent_token = None
+ if gen_ai_endpoint.startswith("agent_"):
+ model_info_token = _current_agent_model_info.set(
+ _compute_agent_model_info(instance)
+ )
+ parent_agent_token = _agno_parent_agent.set(instance)
+
+ # Dedup tokens
+ dedup_token = None
+ if gen_ai_endpoint == "team_arun":
+ dedup_token = _agno_team_active.set(True)
+ elif gen_ai_endpoint == "workflow_arun":
+ dedup_token = _agno_workflow_active.set(True)
+
+ # Span links: connect back to create_agent spans
+ links = []
+ if gen_ai_endpoint == "team_arun":
+ members = (
+ getattr(instance, "members", None)
+ or getattr(instance, "agents", None)
+ or []
+ )
+ for member in members:
+ creation_ctx = getattr(member, "_openlit_creation_context", None)
+ if creation_ctx:
+ links.append(Link(creation_ctx))
+ elif gen_ai_endpoint.startswith("agent_"):
+ creation_ctx = getattr(instance, "_openlit_creation_context", None)
+ if creation_ctx:
+ links.append(Link(creation_ctx))
+
+ try:
+ with tracer.start_as_current_span(
+ span_name, kind=span_kind, links=links
+ ) as span:
+ start_time = time.time()
+ try:
+ response = await wrapped(*args, **kwargs)
+
+ process_agno_response(
+ response,
+ gen_ai_endpoint,
+ span,
+ instance,
+ args,
+ kwargs,
+ start_time,
+ environment,
+ application_name,
+ metrics,
+ capture_message_content,
+ disable_metrics,
+ version,
+ )
+
+ return response
+
+ except Exception as e:
+ handle_exception(span, e)
+ raise
+ finally:
+ if gen_ai_endpoint == "team_arun" and dedup_token is not None:
+ _agno_team_active.reset(dedup_token)
+ elif gen_ai_endpoint == "workflow_arun" and dedup_token is not None:
+ _agno_workflow_active.reset(dedup_token)
+ if model_info_token is not None:
+ _current_agent_model_info.reset(model_info_token)
+ if parent_agent_token is not None:
+ _agno_parent_agent.reset(parent_agent_token)
async def _arun_stream_wrapper(
@@ -137,21 +204,40 @@ async def _arun_stream_wrapper(
instance,
args,
kwargs,
- span_name,
+ gen_ai_endpoint,
tracer,
- pricing_info,
+ version,
environment,
application_name,
- metrics,
+ pricing_info,
capture_message_content,
+ metrics,
disable_metrics,
- version,
):
+ """Async generator wrapper for Agent.arun(stream=True).
+
+ Injects yield_run_output=True to capture the final RunOutput for
+ telemetry extraction, then keeps the span open for the full duration.
"""
- Async generator wrapper for Agent.arun(stream=True).
- Keeps the span open for the full duration of iteration.
- """
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
+ operation_type = OPERATION_MAP.get(gen_ai_endpoint, "invoke_agent")
+ span_kind = get_span_kind(operation_type)
+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)
+
+ model_info_token = None
+ parent_agent_token = None
+ if gen_ai_endpoint.startswith("agent_"):
+ model_info_token = _current_agent_model_info.set(
+ _compute_agent_model_info(instance)
+ )
+ parent_agent_token = _agno_parent_agent.set(instance)
+
+ links = []
+ if gen_ai_endpoint.startswith("agent_"):
+ creation_ctx = getattr(instance, "_openlit_creation_context", None)
+ if creation_ctx:
+ links.append(Link(creation_ctx))
+
+ with tracer.start_as_current_span(span_name, kind=span_kind, links=links) as span:
start_time = time.time()
final_response = None
try:
@@ -159,11 +245,13 @@ async def _arun_stream_wrapper(
from agno.run.agent import RunOutput # noqa: WPS433
except Exception:
RunOutput = None
+
yield_run_output = kwargs.get("yield_run_output", None) or kwargs.get(
"yield_run_response", None
)
new_kwargs = dict(kwargs)
new_kwargs["yield_run_output"] = True
+
async for response in wrapped(*args, **new_kwargs):
if RunOutput and isinstance(response, RunOutput):
final_response = response
@@ -171,92 +259,123 @@ async def _arun_stream_wrapper(
yield response
else:
yield response
+
if not RunOutput:
final_response = getattr(instance, "run_response", None)
except GeneratorExit:
pass
except Exception as e:
handle_exception(span, e)
- logger.error("Error in async agent.arun stream: %s", e)
+ logger.error("Error in async agent stream: %s", e)
raise
finally:
try:
- process_agent_request(
+ process_agno_response(
+ final_response,
+ gen_ai_endpoint,
span,
instance,
args,
kwargs,
- final_response,
start_time,
- pricing_info,
environment,
application_name,
metrics,
capture_message_content,
disable_metrics,
version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
)
- span.set_status(Status(StatusCode.OK))
except Exception as e:
handle_exception(span, e)
- logger.error("Error in async agent.arun stream telemetry: %s", e)
+ logger.error("Error in async agent stream telemetry: %s", e)
+ if model_info_token is not None:
+ _current_agent_model_info.reset(model_info_token)
+ if parent_agent_token is not None:
+ _agno_parent_agent.reset(parent_agent_token)
-def async_agent_continue_run_wrap(
+async def _team_arun_stream_wrapper(
+ wrapped,
+ instance,
+ args,
+ kwargs,
gen_ai_endpoint,
+ tracer,
version,
environment,
application_name,
- tracer,
pricing_info,
capture_message_content,
metrics,
disable_metrics,
):
- """
- Wrap Agno Agent.acontinue_run method using process functions only.
- """
+ """Async generator wrapper for Team._arun_stream / Team.arun(stream=True)."""
+ operation_type = OPERATION_MAP.get(gen_ai_endpoint, "invoke_workflow")
+ span_kind = get_span_kind(operation_type)
+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)
+
+ # Span links
+ links = []
+ members = (
+ getattr(instance, "members", None) or getattr(instance, "agents", None) or []
+ )
+ for member in members:
+ creation_ctx = getattr(member, "_openlit_creation_context", None)
+ if creation_ctx:
+ links.append(Link(creation_ctx))
+
+ with tracer.start_as_current_span(span_name, kind=span_kind, links=links) as span:
+ start_time = time.time()
+ final_response = None
+ try:
+ try:
+ from agno.run.team import TeamRunOutput # noqa: WPS433
+ except Exception:
+ TeamRunOutput = None
- async def wrapper(wrapped, instance, args, kwargs):
- agent_name = getattr(instance, "name", "unknown")
- span_name = f"continue {agent_name}"
+ yield_run_response = kwargs.get("yield_run_response", None)
+ new_kwargs = dict(kwargs)
+ new_kwargs["yield_run_response"] = True
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
+ async for response in wrapped(*args, **new_kwargs):
+ if TeamRunOutput and isinstance(response, TeamRunOutput):
+ final_response = response
+ if yield_run_response:
+ yield response
+ else:
+ yield response
+ if not TeamRunOutput:
+ final_response = getattr(instance, "run_response", None)
+ except GeneratorExit:
+ pass
+ except Exception as e:
+ handle_exception(span, e)
+ logger.error("Error in team stream run: %s", e)
+ raise
+ finally:
try:
- # Process request using utils function with ALL attributes from semcov
- process_agent_request(
+ process_agno_response(
+ final_response,
+ gen_ai_endpoint,
span,
instance,
args,
kwargs,
- result,
start_time,
- pricing_info,
environment,
application_name,
metrics,
capture_message_content,
disable_metrics,
version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
)
-
- span.set_status(Status(StatusCode.OK))
-
except Exception as e:
handle_exception(span, e)
- logger.error("Error in async agent.acontinue_run trace creation: %s", e)
-
- return result
-
- return wrapper
+ logger.error("Error creating team stream trace: %s", e)
-def async_model_run_function_call_wrap(
+def async_workflow_wrap(
gen_ai_endpoint,
version,
environment,
@@ -267,1176 +386,84 @@ def async_model_run_function_call_wrap(
metrics,
disable_metrics,
):
- """
- Wrap Agno Model.arun_function_call async method to bridge agent and tool span context.
- This is the critical method that connects agent execution to tool execution.
- """
+ """Wrapper for Workflow.arun which may return an async iterator."""
async def wrapper(wrapped, instance, args, kwargs):
- # Extract function call information for span naming
- function_call = args[0] if args else kwargs.get("function_call", None)
- function_name = None
-
- if function_call:
- # Extract function name from the FunctionCall object
- if hasattr(function_call, "function") and hasattr(
- function_call.function, "name"
- ):
- function_name = function_call.function.name
- elif hasattr(function_call, "name"):
- function_name = function_call.name
+ if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
+ result = wrapped(*args, **kwargs)
+ if hasattr(result, "__aiter__"):
+ async for item in result:
+ yield item
+ return
+ yield await result
+ return
- # Skip creating span if we can't identify the function
- if not function_name or function_name == "unknown_function":
- return await wrapped(*args, **kwargs)
+ if _agno_workflow_active.get():
+ result = wrapped(*args, **kwargs)
+ if hasattr(result, "__aiter__"):
+ async for item in result:
+ yield item
+ return
+ yield await result
+ return
- span_name = f"tool {function_name}"
+ operation_type = OPERATION_MAP.get(gen_ai_endpoint, "invoke_workflow")
+ span_kind = get_span_kind(operation_type)
+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
+ with tracer.start_as_current_span(span_name, kind=span_kind) as span:
start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
- function_call,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- function_name,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error(
- "Error in async model.arun_function_call trace creation: %s", e
- )
-
- return result
-
- return wrapper
-
-
-def async_agent_run_stream_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Agent._arun_stream async generator method.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- # Extract agent name for span naming with fallback to agent_id
- agent_name = (
- getattr(instance, "name", None)
- or getattr(instance, "agent_id", None)
- or "default_agent"
- )
- span_name = f"agent {agent_name}"
+ result = wrapped(*args, **kwargs)
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
- final_response = None
- try:
- # agno 2.x: when `yield_run_response=True`, the final `RunOutput` is yielded
- # rather than stored on `instance.run_response`
- # agno 2.3+: `yield_run_response` has been deprecated for `yield_run_output`
- try:
- from agno.run.agent import RunOutput # noqa: WPS433 # pylint: disable=import-error
- except Exception: # noqa: WPS429
- RunOutput = None # type: ignore # pylint: disable=invalid-name
- # `yield_run_response` is backwards compatibility for agno < 2.3
- yield_run_output = kwargs.get("yield_run_output", None) or kwargs.get(
- "yield_run_response", None
- )
- new_kwargs = dict(kwargs)
- new_kwargs["yield_run_output"] = True
- async for response in wrapped(*args, **new_kwargs):
- if RunOutput and isinstance(response, RunOutput):
- final_response = response
- if yield_run_output:
- yield response
- else:
- yield response
- if not RunOutput:
- # Get the final response after iteration completes
- final_response = getattr(instance, "run_response", None)
- except GeneratorExit:
- # Generator was closed early by consumer - this is normal
- # Don't log as error, just mark span complete with what we have
- pass
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async agent._arun_stream: %s", e)
- raise
- finally:
- # Always process telemetry in finally block to ensure it runs
+ if hasattr(result, "__aiter__"):
+ final_response = None
try:
- # Process request using utils function with ALL attributes from semcov
- process_agent_request(
- span,
- instance,
- args,
- kwargs,
- final_response,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
- )
-
- # Mark span as successful
- span.set_status(Status(StatusCode.OK))
-
+ async for event in result:
+ final_response = event
+ yield event
except Exception as e:
- # Handle instrumentation exceptions - log but don't raise
handle_exception(span, e)
- logger.error(
- "Error in async agent._arun_stream trace creation: %s", e
- )
-
- return wrapper
-
-
-def async_model_run_function_calls_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Model.arun_function_calls async method to bridge agent and tool span context.
- This method returns an AsyncIterator and requires special handling to maintain span hierarchy.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- # Extract function calls information for span naming
- function_calls = args[0] if args else []
- function_names = []
- if function_calls:
- for fc in function_calls:
- if hasattr(fc, "function"):
- if hasattr(fc.function, "name"):
- function_names.append(fc.function.name)
- elif hasattr(fc.function, "__name__"):
- function_names.append(fc.function.__name__)
-
- span_name = f"model run functions {', '.join(function_names[:3])}" # Limit to first 3 names
- if len(function_names) > 3:
- span_name += f" (+{len(function_names) - 3} more)"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
-
- try:
- # Stream items directly - OpenTelemetry's context manager handles context automatically
- async for item in wrapped(*args, **kwargs):
- yield item
-
- except GeneratorExit:
- # Generator was closed early by consumer - this is normal
- pass
- except Exception as e:
- handle_exception(span, e)
- logger.error(
- "Error in async model.arun_function_calls execution: %s", e
- )
- raise
- finally:
- # Process the span after completion
+ raise
+ finally:
+ try:
+ process_agno_response(
+ final_response,
+ gen_ai_endpoint,
+ span,
+ instance,
+ args,
+ kwargs,
+ start_time,
+ environment,
+ application_name,
+ metrics,
+ capture_message_content,
+ disable_metrics,
+ version,
+ )
+ except Exception as e:
+ handle_exception(span, e)
+ else:
try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
+ response = await result
+ process_agno_response(
+ response,
+ gen_ai_endpoint,
span,
- function_calls,
+ instance,
args,
kwargs,
- "AsyncIterator completed", # Result is the completion status
start_time,
- pricing_info,
environment,
application_name,
metrics,
capture_message_content,
disable_metrics,
version,
- "batch_function_calls",
)
-
- span.set_status(Status(StatusCode.OK))
-
+ yield response
except Exception as e:
handle_exception(span, e)
- logger.error(
- "Error in async model.arun_function_calls trace creation: %s", e
- )
-
- return wrapper
-
-
-def async_function_entrypoint_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Function.entrypoint async method to catch direct async tool executions.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- # Extract function information for span naming
- function_name = getattr(instance, "name", None) or getattr(
- instance, "__name__", "unknown_function"
- )
- span_name = f"tool {function_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- function_name,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async function.entrypoint trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# Async Tools Component Wrappers
-def async_function_call_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Function async call method for tool execution tracing using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- # Extract function information
- function_name = getattr(
- instance, "name", getattr(instance, "__name__", "unknown_function")
- )
- span_name = f"tool {function_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute async function with timing
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async tool execution trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# Async Memory Component Wrappers
-def async_memory_add_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Memory async add method for memory storage tracing using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- span_name = "memory add"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_memory_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_MEMORY,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async memory add trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def async_memory_search_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Memory async search method for memory retrieval tracing using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- span_name = "memory search"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_memory_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_MEMORY,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async memory search trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# Async VectorDB Component Wrappers
-def async_vectordb_search_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno VectorDb async search method for vector search tracing using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- span_name = "vectordb search"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_vectordb_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_VECTORDB,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async vectordb search trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# Async Knowledge Component Wrappers
-def async_knowledge_search_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno AgentKnowledge async search method for knowledge search tracing using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- span_name = "knowledge search"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_knowledge_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_KNOWLEDGE,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async knowledge search trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-# Async Workflow Component Wrappers
-def async_workflow_run_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Workflow async run method for workflow execution tracing.
-
- In Agno 2.2+, workflow.arun() returns an async iterator instead of a coroutine.
- This wrapper handles both patterns for backward compatibility.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- workflow_name = getattr(instance, "name", "unknown_workflow")
- span_name = f"workflow {workflow_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
-
- # Call the wrapped function to get the result
- result = wrapped(*args, **kwargs)
-
- # Check if result is an async iterator (Agno 2.2+)
- if hasattr(result, "__aiter__"):
- # Handle async iterator - stream events and collect final response
- try:
- final_response = None
- async for event in result:
- final_response = event
- yield event
-
- # Process the final response for telemetry
- try:
- process_workflow_request(
- span,
- instance,
- args,
- kwargs,
- final_response,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- )
- span.set_status(Status(StatusCode.OK))
- except Exception as e:
- handle_exception(span, e)
- logger.error(
- "Error in async workflow run trace creation: %s", e
- )
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async workflow run iteration: %s", e)
- raise
- else:
- # Legacy coroutine pattern (pre-Agno 2.2)
- # Await the result and yield it as a single item
- try:
- response = await result
-
- # Process request using utils function with ALL attributes from semcov
- process_workflow_request(
- span,
- instance,
- args,
- kwargs,
- response,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- )
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async workflow run trace creation: %s", e)
- raise
-
- # Yield the single response to maintain generator contract
- yield response
-
- return wrapper
-
-
-# Async Team Component Wrappers
-def async_team_run_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Team async run method for team execution tracing using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- team_name = getattr(instance, "name", "unknown_team")
- span_name = f"team {team_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_team_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async team run trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def async_team_run_stream_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Team async stream run; request final RunOutput via yield_run_response=True.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- team_name = getattr(instance, "name", "unknown_team")
- span_name = f"team {team_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
- final_response = None
-
- try:
- # agno 2.x: when `yield_run_response=True`, the final `TeamRunOutput` is yielded
- # rather than stored on `instance.run_response`
- try:
- from agno.run.team import TeamRunOutput # noqa: WPS433 # pylint: disable=import-error
- except Exception: # noqa: WPS429
- TeamRunOutput = None # type: ignore # pylint: disable=invalid-name
-
- yield_run_response = kwargs.get("yield_run_response", None)
- new_kwargs = dict(kwargs)
- new_kwargs["yield_run_response"] = True
- async for response in wrapped(*args, **new_kwargs):
- if TeamRunOutput and isinstance(response, TeamRunOutput):
- final_response = response
- if yield_run_response:
- yield response
- else:
- yield response
- if not TeamRunOutput:
- # Get the final response after iteration completes
- final_response = getattr(instance, "run_response", None)
- except GeneratorExit:
- # Generator was closed early by consumer - this is normal
- # Don't log as error, just mark span complete with what we have
- pass
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in team stream run: %s", e)
- raise
- finally:
- # Always process telemetry in finally block to ensure it runs
- try:
- process_team_request(
- span,
- instance,
- args,
- kwargs,
- final_response,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- )
- span.set_status(Status(StatusCode.OK))
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error creating team stream trace: %s", e)
-
- return wrapper
-
-
-def async_agent_add_tool_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Agent.add_tool method for detailed async tracing using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- agent_name = getattr(instance, "name", "unknown")
- span_name = f"agent {agent_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async agent.add_tool trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def async_session_memory_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Agent async memory operations (get_session_summary, get_user_memories) using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- # Extract method name from endpoint
- method_name = gen_ai_endpoint.split(".")[-1]
- span_name = f"memory {method_name.replace('get_', '').replace('_', ' ')}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute async memory operation with timing
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- # Extract method name for operation type
- operation_type = method_name.replace("get_", "").replace("_", " ")
- process_memory_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- operation_type,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async memory operation trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def async_function_execute_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno FunctionCall.aexecute method for async tool execution tracing using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- # Extract function information
- function_name = getattr(instance.function, "name", "unknown_function")
- span_name = f"tool {function_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async tool execution trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def async_toolkit_run_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Toolkit async run method for toolkit execution tracing using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- # Extract toolkit information
- toolkit_name = getattr(
- instance,
- "name",
- getattr(instance, "__class__", {}).get("__name__", "unknown_toolkit"),
- )
- span_name = f"toolkit {toolkit_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute async toolkit with timing
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_tool_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async toolkit execution trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def async_reasoning_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno Agent.areason method for async reasoning operation tracing using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- agent_name = getattr(instance, "name", "unknown_agent")
- span_name = f"reasoning {agent_name}"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute async reasoning with timing
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_reasoning_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- "reasoning",
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async reasoning trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def async_vectordb_upsert_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno VectorDb async upsert method for vector upsert tracing using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- span_name = "vectordb upsert"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- # Execute async vectordb upsert with timing
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_vectordb_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- "upsert",
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async vectordb upsert trace creation: %s", e)
-
- return result
-
- return wrapper
-
-
-def async_knowledge_add_wrap(
- gen_ai_endpoint,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
-):
- """
- Wrap Agno AgentKnowledge async add method for knowledge addition tracing using process functions only.
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- span_name = "knowledge add"
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.INTERNAL) as span:
- # Execute async knowledge addition with timing
- start_time = time.time()
- result = await wrapped(*args, **kwargs)
-
- try:
- # Process request using utils function with ALL attributes from semcov
- process_knowledge_request(
- span,
- instance,
- args,
- kwargs,
- result,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- "add",
- )
-
- span.set_status(Status(StatusCode.OK))
-
- except Exception as e:
- handle_exception(span, e)
- logger.error("Error in async knowledge add trace creation: %s", e)
-
- return result
+ raise
return wrapper
diff --git a/sdk/python/src/openlit/instrumentation/agno/utils.py b/sdk/python/src/openlit/instrumentation/agno/utils.py
index 4a44388b..3c9d8635 100644
--- a/sdk/python/src/openlit/instrumentation/agno/utils.py
+++ b/sdk/python/src/openlit/instrumentation/agno/utils.py
@@ -1,679 +1,732 @@
"""
-Utility functions for Agno instrumentation following OpenLIT patterns.
+Agno utilities for OTel GenAI semantic convention compliant telemetry.
+
+Follows the same patterns as the CrewAI / OpenAI Agents instrumentations.
+All operation names, span kinds, and attributes comply with the OTel GenAI
+semantic conventions (gen-ai-spans.md, gen-ai-agent-spans.md).
"""
import importlib
+import inspect
+import json
import logging
import time
+import contextvars
+
+from opentelemetry.trace import SpanKind, Status, StatusCode
+
from openlit.__helpers import (
- common_span_attributes,
+ common_framework_span_attributes,
+ get_server_address_for_provider,
truncate_content,
)
from openlit.semcov import SemanticConvention
-# Initialize logger
logger = logging.getLogger(__name__)
+# ---------------------------------------------------------------------------
+# Contextvars for span deduplication
+# ---------------------------------------------------------------------------
+_agno_team_active = contextvars.ContextVar("openlit_agno_team_active", default=False)
+_agno_workflow_active = contextvars.ContextVar(
+ "openlit_agno_workflow_active", default=False
+)
-# Simple utility functions following OpenLIT patterns
-
-
-class _ScopeWrapper:
- """
- A scope wrapper class for common_span_attributes compatibility.
-
- This class wraps the necessary parameters required by the common_span_attributes
- function to maintain consistency with OpenLIT instrumentation patterns.
- """
-
- def __init__(self, span, instance, kwargs, args, start_time):
- """Initialize the scope wrapper with required parameters."""
- self._span = span
- self._instance = instance
- self._kwargs = kwargs
- self._args = args
- self._start_time = start_time
- self._end_time = time.time()
-
- def get_span(self):
- """Get the associated span."""
- return self._span
-
- def get_instance(self):
- """Get the instrumented instance."""
- return self._instance
-
+# Propagates the executing agent's model info to child execute_tool spans
+_current_agent_model_info = contextvars.ContextVar(
+ "openlit_agno_agent_model_info", default=None
+)
-def process_agent_request(
- span,
- instance,
- args,
- kwargs,
- response,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- operation_type=SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
-):
+# Stores the parent agent instance so child tool spans can lazily
+# read session_id (set by Agno mid-run, not available before wrapped())
+_agno_parent_agent = contextvars.ContextVar("openlit_agno_parent_agent", default=None)
+
+# ---------------------------------------------------------------------------
+# OTel GenAI Operation Mapping
+# ---------------------------------------------------------------------------
+OPERATION_MAP = {
+ "agent_init": SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,
+ "agent_run": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ "agent_arun": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ "agent_continue_run": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ "agent_acontinue_run": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ "team_run": SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,
+ "team_arun": SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,
+ "workflow_run": SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,
+ "workflow_arun": SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,
+ "tool_execute": SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
+ "tool_aexecute": SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
+ "vectordb_search": "retrieval",
+ "vectordb_upsert": "upsert",
+ "knowledge_search": "retrieval",
+ "knowledge_add": "knowledge_add",
+ "memory_add": SemanticConvention.GEN_AI_OPERATION_TYPE_MEMORY,
+ "memory_search": SemanticConvention.GEN_AI_OPERATION_TYPE_MEMORY,
+}
+
+# ---------------------------------------------------------------------------
+# SpanKind per operation type (OTel GenAI spec)
+# ---------------------------------------------------------------------------
+SPAN_KIND_MAP = {
+ SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK: SpanKind.INTERNAL,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT: SpanKind.INTERNAL,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS: SpanKind.INTERNAL,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT: SpanKind.CLIENT,
+ "retrieval": SpanKind.CLIENT,
+ "upsert": SpanKind.CLIENT,
+ "knowledge_add": SpanKind.CLIENT,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_MEMORY: SpanKind.INTERNAL,
+}
+
+
+def get_span_kind(operation_type):
+ """Return the correct SpanKind for *operation_type* per OTel GenAI spec."""
+ return SPAN_KIND_MAP.get(operation_type, SpanKind.INTERNAL)
+
+
+# ---------------------------------------------------------------------------
+# Model name / server resolution
+# ---------------------------------------------------------------------------
+_MODEL_PREFIX_TO_PROVIDER = {
+ "gpt-": "openai",
+ "o1": "openai",
+ "o3": "openai",
+ "o4": "openai",
+ "davinci": "openai",
+ "claude": "anthropic",
+ "gemini": "google",
+ "mistral": "mistral_ai",
+ "command": "cohere",
+ "deepseek": "deepseek",
+ "llama": "groq",
+ "mixtral": "groq",
+}
+
+
+def _infer_provider_from_model(model_name):
+ """Map a model name string to a provider key."""
+ if not model_name:
+ return None
+ lower = model_name.lower()
+ for prefix, provider in _MODEL_PREFIX_TO_PROVIDER.items():
+ if lower.startswith(prefix):
+ return provider
+ return None
+
+
+def _extract_model_name(instance):
+ """Walk the instance hierarchy to find the LLM model name."""
+ if not instance:
+ return "unknown"
+
+ model = getattr(instance, "model", None)
+ if model:
+ model_id = getattr(model, "id", None)
+ if model_id:
+ return str(model_id)
+ model_name = getattr(model, "name", None)
+ if model_name:
+ return str(model_name)
+
+ # For teams, walk members/agents to find first model
+ for attr in ("members", "agents"):
+ agents = getattr(instance, attr, None)
+ if agents:
+ for ag in agents:
+ ag_model = getattr(ag, "model", None)
+ if ag_model:
+ mid = getattr(ag_model, "id", None) or getattr(
+ ag_model, "name", None
+ )
+ if mid:
+ return str(mid)
+
+ # Tool instances: inherit from parent agent via contextvar
+ model_info = _current_agent_model_info.get()
+ if model_info:
+ return model_info[0]
+
+ return "unknown"
+
+
+def set_server_address_and_port(instance):
+ """Extract server address / port from an Agno instance's model config.
+
+ Falls back to PROVIDER_DEFAULT_ENDPOINTS when no explicit api_base is set.
"""
- Process agent request and generate ALL telemetry attributes from semcov (CrewAI pattern)
- """
-
- # Calculate execution time
- execution_time = time.time() - start_time
-
- # Extract agent information
- agent_name = (
- getattr(instance, "name", None)
- or getattr(instance, "agent_id", None)
- or "default_agent"
- )
- request_model = None
-
- # Get model information
- if hasattr(instance, "model"):
- model = instance.model
- if hasattr(model, "id"):
- request_model = str(model.id)
- elif hasattr(model, "name"):
- request_model = str(model.name)
-
- # Create scope object for common_span_attributes compatibility
- scope = _ScopeWrapper(span, instance, kwargs, args, start_time)
-
- # Use common span attributes helper from __helpers
- common_span_attributes(
- scope,
- operation_type,
- SemanticConvention.GEN_AI_SYSTEM_AGNO,
- "localhost", # server_address
- 80, # server_port
- request_model,
- request_model, # response_model same as request
- environment,
- application_name,
- kwargs.get("stream", False), # is_stream
- 0, # tbt
- 0, # ttft
- version,
+ server_address = ""
+ server_port = 0
+ try:
+ model = getattr(instance, "model", None)
+
+ # Walk to find a model in teams/agents
+ if not model:
+ for attr in ("members", "agents"):
+ agents = getattr(instance, attr, None)
+ if agents:
+ for ag in agents:
+ model = getattr(ag, "model", None)
+ if model:
+ break
+ if model:
+ break
+
+ if model:
+ api_base = getattr(model, "api_base", None) or getattr(
+ model, "base_url", None
+ )
+ if api_base:
+ from urllib.parse import urlparse
+
+ parsed = urlparse(str(api_base))
+ server_address = parsed.hostname or ""
+ server_port = parsed.port or 443
+
+ if not server_address:
+ model_name = _extract_model_name(instance)
+ provider = _infer_provider_from_model(model_name)
+ if provider:
+ server_address, server_port = get_server_address_for_provider(provider)
+
+ # Tool instances: inherit from parent agent via contextvar
+ if not server_address:
+ model_info = _current_agent_model_info.get()
+ if model_info:
+ server_address = model_info[1]
+ server_port = model_info[2]
+ except Exception:
+ pass
+ return server_address, server_port
+
+
+def _compute_agent_model_info(instance):
+ """Return (model_name, server_address, server_port) for an agent."""
+ model_name = _extract_model_name(instance)
+ server_address, server_port = set_server_address_and_port(instance)
+ return (model_name, server_address, server_port)
+
+
+# ---------------------------------------------------------------------------
+# Span name generation
+# ---------------------------------------------------------------------------
+def generate_span_name(endpoint, instance, args=None, kwargs=None):
+ """Return an OTel-compliant span name: ``{operation} {entity_name}``."""
+ operation = OPERATION_MAP.get(
+ endpoint, SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT
)
- # Set agno-specific attributes using semantic conventions
- span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, agent_name)
+ if endpoint == "agent_init":
+ name = getattr(instance, "name", None) or "agent"
+ return f"{operation} {name}"
- # Set lifecycle phase based on operation
- if operation_type == SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT:
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_LIFECYCLE_PHASE,
- SemanticConvention.GEN_AI_AGENT_LIFECYCLE_PHASE_EXECUTE,
- )
- elif operation_type == SemanticConvention.GEN_AI_OPERATION_TYPE_MEMORY:
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_LIFECYCLE_PHASE,
- SemanticConvention.GEN_AI_AGENT_LIFECYCLE_PHASE_EXECUTE,
+ if endpoint.startswith("agent_"):
+ name = (
+ getattr(instance, "name", None)
+ or getattr(instance, "agent_id", None)
+ or "agent"
)
- elif operation_type == SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS:
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_LIFECYCLE_PHASE,
- SemanticConvention.GEN_AI_AGENT_LIFECYCLE_PHASE_TOOL_EXECUTION,
+ return f"{operation} {name}"
+
+ if endpoint.startswith("team_"):
+ name = getattr(instance, "name", None) or "team"
+ return f"{operation} {name}"
+
+ if endpoint.startswith("workflow_"):
+ name = getattr(instance, "name", None) or "workflow"
+ return f"{operation} {name}"
+
+ if endpoint.startswith("tool_"):
+ func = getattr(instance, "function", None)
+ name = getattr(func, "name", None) if func else None
+ if not name:
+ name = getattr(instance, "name", None) or "tool"
+ return f"{operation} {name}"
+
+ if endpoint.startswith("vectordb_"):
+ name = getattr(instance, "name", None) or type(instance).__name__
+ return f"{operation} {name}"
+
+ if endpoint.startswith("knowledge_"):
+ name = getattr(instance, "name", None) or type(instance).__name__
+ return f"{operation} {name}"
+
+ if endpoint.startswith("memory_"):
+ op_suffix = endpoint.replace("memory_", "")
+ return f"{operation} {op_suffix}"
+
+ return f"{operation} {endpoint}"
+
+
+# ---------------------------------------------------------------------------
+# Token usage extraction
+# ---------------------------------------------------------------------------
+def _extract_token_usage(response):
+ """Extract token metrics from RunOutput.metrics or TeamRunOutput.metrics."""
+ input_tokens = 0
+ output_tokens = 0
+ try:
+ metrics = getattr(response, "metrics", None)
+ if metrics:
+ input_tokens = getattr(metrics, "input_tokens", 0) or 0
+ output_tokens = getattr(metrics, "output_tokens", 0) or 0
+ except Exception:
+ pass
+ return input_tokens, output_tokens
+
+
+# ---------------------------------------------------------------------------
+# Entity-specific attribute setters
+# ---------------------------------------------------------------------------
+def _set_agent_attributes(span, instance, endpoint, capture_message_content):
+ """Set agent-specific attributes per OTel GenAI semantic conventions."""
+ if not endpoint.startswith("agent_"):
+ return
+ try:
+ agent_name = (
+ getattr(instance, "name", None)
+ or getattr(instance, "agent_id", None)
+ or "agent"
)
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(agent_name))
- # Add detailed agent information if available
- if hasattr(instance, "instructions") and instance.instructions:
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_INSTRUCTIONS,
- truncate_content(instance.instructions),
- )
+ agent_id = getattr(instance, "agent_id", None) or getattr(instance, "id", None)
+ if agent_id:
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_ID, str(agent_id))
- if hasattr(instance, "agent_id") and instance.agent_id:
- span.set_attribute(SemanticConvention.GEN_AI_AGENT_ID, instance.agent_id)
+ description = getattr(instance, "description", None)
+ if description:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION,
+ truncate_content(str(description)),
+ )
- if hasattr(instance, "description") and instance.description:
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_DESCRIPTION,
- truncate_content(instance.description),
- )
+ instructions = getattr(instance, "instructions", None)
+ if instructions and capture_message_content:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS,
+ truncate_content(str(instructions)),
+ )
- if hasattr(instance, "introduction") and instance.introduction:
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_INTRODUCTION,
- truncate_content(instance.introduction),
- )
+ _set_tool_definitions(span, getattr(instance, "tools", None) or [])
- # Add request-specific attributes from args and kwargs
- if args and args[0]:
- if capture_message_content:
+ # Session / conversation ID
+ session_id = getattr(instance, "session_id", None)
+ if session_id:
span.set_attribute(
- SemanticConvention.GEN_AI_INPUT_MESSAGES, truncate_content(args[0])
+ SemanticConvention.GEN_AI_CONVERSATION_ID, str(session_id)
)
- # agno 2.x versions agent.run use input instead of args[0]
- if kwargs and kwargs.get("input", None) and capture_message_content:
- span.set_attribute(
- SemanticConvention.GEN_AI_INPUT_MESSAGES, truncate_content(kwargs["input"])
- )
- # agno 2.x versions team.run use input_message instead of args[0]
- if kwargs and kwargs.get("input_message", None) and capture_message_content:
- span.set_attribute(
- SemanticConvention.GEN_AI_INPUT_MESSAGES,
- truncate_content(kwargs["input_message"]),
- )
+ user_id = getattr(instance, "user_id", None)
+ if user_id:
+ span.set_attribute(SemanticConvention.GEN_AI_REQUEST_USER, str(user_id))
+ except Exception:
+ pass
- # User and session information
- if "user_id" in kwargs and kwargs["user_id"]:
- span.set_attribute(SemanticConvention.GEN_AI_REQUEST_USER, kwargs["user_id"])
- elif hasattr(instance, "user_id") and instance.user_id:
- span.set_attribute(SemanticConvention.GEN_AI_REQUEST_USER, instance.user_id)
-
- if "session_id" in kwargs and kwargs["session_id"]:
- span.set_attribute(SemanticConvention.GEN_AI_SESSION_ID, kwargs["session_id"])
-
- # agno 2.x versions use session instead of session_id
- if (
- "session" in kwargs
- and kwargs["session"]
- and hasattr(kwargs["session"], "session_id")
- ):
- span.set_attribute(
- SemanticConvention.GEN_AI_SESSION_ID, kwargs["session"].session_id
- )
- # Stream and reasoning attributes
- if "stream" in kwargs:
- span.set_attribute(
- SemanticConvention.GEN_AI_REQUEST_IS_STREAM, bool(kwargs["stream"])
- )
+def _set_team_attributes(span, instance, endpoint):
+ """Set team-specific attributes (teams are workflows in OTel)."""
+ if not endpoint.startswith("team_"):
+ return
+ try:
+ team_name = getattr(instance, "name", None) or "team"
+ span.set_attribute(SemanticConvention.GEN_AI_WORKFLOW_NAME, str(team_name))
- if "show_full_reasoning" in kwargs:
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_SHOW_REASONING,
- bool(kwargs["show_full_reasoning"]),
- )
+ session_id = getattr(instance, "session_id", None)
+ if session_id:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_CONVERSATION_ID, str(session_id)
+ )
- if "stream_intermediate_steps" in kwargs:
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_STREAM_INTERMEDIATE_STEPS,
- bool(kwargs["stream_intermediate_steps"]),
+ members = getattr(instance, "members", None) or getattr(
+ instance, "agents", None
)
+ if members:
+ agent_names = []
+ for m in members[:10]:
+ name = getattr(m, "name", None) or "unknown"
+ agent_names.append(str(name))
+ if agent_names:
+ span.set_attribute("gen_ai.agno.team.agents", json.dumps(agent_names))
+ except Exception:
+ pass
+
+
+def _set_workflow_attributes(span, instance, endpoint):
+ """Set workflow-specific attributes."""
+ if not endpoint.startswith("workflow_"):
+ return
+ try:
+ wf_name = getattr(instance, "name", None) or "workflow"
+ span.set_attribute(SemanticConvention.GEN_AI_WORKFLOW_NAME, str(wf_name))
+
+ session_id = getattr(instance, "session_id", None)
+ if session_id:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_CONVERSATION_ID, str(session_id)
+ )
- # Set execution time using semantic convention
- span.set_attribute(SemanticConvention.GEN_AI_AGENT_EXECUTION_TIME, execution_time)
-
- # Process response with comprehensive output capture
- if response:
- if capture_message_content:
- if hasattr(response, "content") and response.content:
- content = truncate_content(response.content)
- span.set_attribute(SemanticConvention.GEN_AI_OUTPUT_MESSAGES, content)
- elif hasattr(response, "message") and response.message:
- content = truncate_content(response.message)
- span.set_attribute(SemanticConvention.GEN_AI_OUTPUT_MESSAGES, content)
-
- # Capture additional response metadata
- if hasattr(response, "metrics"):
+ description = getattr(instance, "description", None)
+ if description:
span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_RESPONSE_TIME, execution_time
+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION,
+ truncate_content(str(description)),
)
+ except Exception:
+ pass
-def process_tool_request(
- span,
- instance,
- args,
- kwargs,
- response,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- tool_name,
+def _set_tool_attributes(
+ span, instance, endpoint, capture_message_content, args, kwargs, response
):
- """
- Process tool execution request and generate ALL telemetry attributes from semcov
- """
-
- execution_time = time.time() - start_time
-
- # Create scope object for common_span_attributes compatibility
- scope = _ScopeWrapper(span, instance, kwargs, args, start_time)
-
- # Get model info from instance if available
- request_model = getattr(instance, "model", None)
- if request_model and hasattr(request_model, "id"):
- model_name = request_model.id
- else:
- model_name = "unknown"
-
- # Use common span attributes for tool operations
- common_span_attributes(
- scope,
- SemanticConvention.GEN_AI_OPERATION_TYPE_EXECUTE_AGENT_TASK,
- SemanticConvention.GEN_AI_SYSTEM_AGNO,
- "localhost", # server_address
- 80, # server_port
- model_name, # request_model
- model_name, # response_model
- environment,
- application_name,
- False, # is_stream
- 0, # tbt
- 0, # ttft
- version,
- )
-
- # Set tool-specific attributes using semcov
- span.set_attribute(SemanticConvention.GEN_AI_TOOL_NAME, tool_name)
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_LIFECYCLE_PHASE,
- SemanticConvention.GEN_AI_AGENT_LIFECYCLE_PHASE_TOOL_EXECUTION,
- )
-
- # Set tool-specific attributes that aren't in the process function
- if (
- hasattr(instance, "function")
- and hasattr(instance.function, "description")
- and instance.function.description
- ):
- span.set_attribute(
- SemanticConvention.GEN_AI_TOOL_DESCRIPTION,
- truncate_content(instance.function.description),
- )
-
- if hasattr(instance, "arguments") and instance.arguments:
- span.set_attribute(
- SemanticConvention.GEN_AI_TOOL_PARAMETERS,
- truncate_content(instance.arguments),
- )
+ """Set tool attributes per OTel GenAI semantic conventions.
- # Set execution metrics
- span.set_attribute(
- SemanticConvention.GEN_AI_TOOL_EXECUTION_DURATION, execution_time
- )
+ Returns True if the tool execution had an error, False otherwise.
+ """
+ if not endpoint.startswith("tool_"):
+ return False
+ tool_errored = False
+ try:
+ func = getattr(instance, "function", None)
+ tool_name = getattr(func, "name", None) if func else None
+ if not tool_name:
+ tool_name = getattr(instance, "name", None) or "tool"
+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_NAME, str(tool_name))
+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_TYPE, "function")
+
+ call_id = getattr(instance, "call_id", None)
+ if call_id:
+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_CALL_ID, str(call_id))
+
+ tool_desc = getattr(func, "description", None) if func else None
+ if tool_desc:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_DESCRIPTION,
+ truncate_content(str(tool_desc)),
+ )
- # Process result
- if response and hasattr(response, "status"):
- span.set_attribute(
- SemanticConvention.GEN_AI_TOOL_EXECUTION_SUCCESS,
- response.status == "success",
- )
if capture_message_content:
- if hasattr(response, "result") and response.result:
+ arguments = getattr(instance, "arguments", None)
+ if arguments:
+ try:
+ arg_str = (
+ json.dumps(arguments)
+ if not isinstance(arguments, str)
+ else arguments
+ )
+ except (TypeError, ValueError):
+ arg_str = str(arguments)
span.set_attribute(
- SemanticConvention.GEN_AI_TOOL_CALL_RESULT,
- truncate_content(response.result),
+ SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS,
+ truncate_content(arg_str),
)
- if hasattr(response, "error") and response.error:
- span.set_attribute(
- SemanticConvention.GEN_AI_TOOL_ERROR, truncate_content(response.error)
- )
-
-
-def process_memory_request(
- span,
- instance,
- args,
- kwargs,
- response,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- memory_operation,
-):
- """
- Process memory operation request and generate ALL telemetry attributes from semcov
- """
-
- execution_time = time.time() - start_time
-
- # Create scope object for common_span_attributes compatibility
- scope = _ScopeWrapper(span, instance, kwargs, args, start_time)
-
- # Use common span attributes for memory operations
- common_span_attributes(
- scope,
- SemanticConvention.GEN_AI_OPERATION_TYPE_MEMORY,
- SemanticConvention.GEN_AI_SYSTEM_AGNO,
- "localhost", # server_address
- 80, # server_port
- None, # request_model
- None, # response_model
- environment,
- application_name,
- False, # is_stream
- 0, # tbt
- 0, # ttft
- version,
- )
-
- # Set memory-specific attributes using semcov
- span.set_attribute(SemanticConvention.GEN_AI_MEMORY_OPERATION, memory_operation)
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_LIFECYCLE_PHASE,
- SemanticConvention.GEN_AI_AGENT_LIFECYCLE_PHASE_EXECUTE,
- )
-
- # Set memory-specific attributes that aren't in the process function
- if hasattr(instance, "db") and instance.db:
- span.set_attribute("gen_ai.memory.db_type", type(instance.db).__name__)
- if hasattr(instance, "table_name"):
- span.set_attribute("gen_ai.memory.table_name", str(instance.table_name))
-
- # Add input data
- if args and capture_message_content:
- span.set_attribute(
- "gen_ai.memory.input", truncate_content(args[0]) if args[0] else ""
- )
-
- # Add metadata from kwargs
- if "user_id" in kwargs:
- span.set_attribute("gen_ai.memory.user_id", kwargs["user_id"])
- if "agent_id" in kwargs:
- span.set_attribute("gen_ai.memory.agent_id", kwargs["agent_id"])
- if "metadata" in kwargs:
- span.set_attribute(
- "gen_ai.memory.metadata", truncate_content(kwargs["metadata"])
- )
+ if response is not None:
+ if hasattr(response, "status"):
+ if (
+ response.status != "success"
+ and hasattr(response, "error")
+ and response.error
+ ):
+ span.set_attribute(
+ SemanticConvention.ERROR_TYPE,
+ truncate_content(str(response.error)),
+ )
+ tool_errored = True
+ if (
+ capture_message_content
+ and hasattr(response, "result")
+ and response.result
+ ):
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_RESULT,
+ truncate_content(str(response.result)),
+ )
+ except Exception:
+ pass
+ return tool_errored
- # Set execution metrics
- span.set_attribute("gen_ai.memory.operation.duration", execution_time)
- # Process result
- if response:
- if hasattr(response, "id"):
- span.set_attribute("gen_ai.memory.result_id", str(response.id))
- span.set_attribute("gen_ai.memory.operation.success", True)
- else:
- span.set_attribute("gen_ai.memory.operation.success", False)
+def _set_retrieval_attributes(span, instance, endpoint, args, kwargs):
+ """Set attributes for vectordb/knowledge retrieval spans."""
+ if not (endpoint.startswith("vectordb_") or endpoint.startswith("knowledge_")):
+ return
+ try:
+ db_name = getattr(instance, "name", None) or type(instance).__name__
+ span.set_attribute("gen_ai.data_source.id", str(db_name))
+ except Exception:
+ pass
-def process_reasoning_request(
- span,
- instance,
- args,
- kwargs,
- response,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- operation_type,
+def _set_memory_attributes(
+ span, instance, endpoint, args, kwargs, capture_message_content
):
- """
- Process reasoning operation request and generate ALL telemetry attributes from semcov
- """
-
- execution_time = time.time() - start_time
- agent_name = getattr(instance, "name", None) or "unknown_agent"
+ """Set attributes for memory operation spans."""
+ if not endpoint.startswith("memory_"):
+ return
+ try:
+ op_type = endpoint.replace("memory_", "")
+ span.set_attribute("gen_ai.agno.memory.operation", op_type)
- # Create scope object for common_span_attributes compatibility
- scope = _ScopeWrapper(span, instance, kwargs, args, start_time)
+ if hasattr(instance, "db") and instance.db:
+ span.set_attribute("gen_ai.agno.memory.db_type", type(instance.db).__name__)
- # Get model info from agent instance if available
- request_model = getattr(instance, "model", None)
- if request_model and hasattr(request_model, "id"):
- model_name = request_model.id
- else:
- model_name = "unknown"
-
- # Use common span attributes for reasoning operations (use agent task operation type)
- common_span_attributes(
- scope,
- SemanticConvention.GEN_AI_OPERATION_TYPE_EXECUTE_AGENT_TASK,
- SemanticConvention.GEN_AI_SYSTEM_AGNO,
- "localhost", # server_address
- 80, # server_port
- model_name, # request_model
- model_name, # response_model
- environment,
- application_name,
- False, # is_stream
- 0, # tbt
- 0, # ttft
- version,
- )
-
- # Set reasoning-specific attributes using semcov
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_LIFECYCLE_PHASE,
- SemanticConvention.GEN_AI_AGENT_LIFECYCLE_PHASE_EXECUTE,
- )
- span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, agent_name)
-
- # Add reasoning-specific attributes
- if hasattr(instance, "reasoning_min_steps"):
- span.set_attribute(
- SemanticConvention.GEN_AI_REASONING_MIN_STEPS, instance.reasoning_min_steps
- )
-
- if hasattr(instance, "reasoning_max_steps"):
- span.set_attribute(
- SemanticConvention.GEN_AI_REASONING_MAX_STEPS, instance.reasoning_max_steps
- )
+ if args and capture_message_content:
+ span.set_attribute(
+ "gen_ai.agno.memory.input",
+ truncate_content(str(args[0])) if args[0] else "",
+ )
- if hasattr(instance, "reasoning_model") and instance.reasoning_model:
- reasoning_model_name = getattr(
- instance.reasoning_model, "name", str(instance.reasoning_model)
- )
- span.set_attribute(
- SemanticConvention.GEN_AI_REASONING_MODEL, reasoning_model_name
- )
+ if "user_id" in kwargs:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_REQUEST_USER, str(kwargs["user_id"])
+ )
+ except Exception:
+ pass
- # Set execution time
- span.set_attribute(
- SemanticConvention.GEN_AI_REASONING_EXECUTION_DURATION, execution_time
- )
+def _get_function_description(fn):
+ """Extract the best available description for an Agno Function object.
-def process_vectordb_request(
- span,
- instance,
- args,
- kwargs,
- response,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- operation_type="vectordb_search",
-):
+ Function.description is set lazily by process_entrypoint() (called during
+ the first LLM interaction), so at create_agent time it is typically None.
+ Fall back to inspect.getdoc on the actual entrypoint callable.
"""
- Process vectordb operation request and generate ALL telemetry attributes from semcov
+ desc = getattr(fn, "description", None)
+ if desc:
+ return desc
+ entrypoint = getattr(fn, "entrypoint", None)
+ if callable(entrypoint):
+ desc = inspect.getdoc(entrypoint)
+ if desc:
+ return desc
+ return None
+
+
+def _set_tool_definitions(span, tools):
+ """Set gen_ai.tool.definitions from a list of Agno tool instances.
+
+ For Agno toolkit objects (e.g. DuckDuckGoTools) that have a `functions`
+ dict, we iterate the registered function names to avoid a mismatch
+ between the toolkit class name and the actual function-level names
+ used at execution time.
"""
-
- execution_time = time.time() - start_time
-
- # Create scope object for common_span_attributes compatibility
- scope = _ScopeWrapper(span, instance, kwargs, args, start_time)
-
- # Use common span attributes for vectordb operations
- common_span_attributes(
- scope,
- f"gen_ai.operation.{operation_type}",
- SemanticConvention.GEN_AI_SYSTEM_AGNO,
- "localhost", # server_address
- 80, # server_port
- None, # request_model
- None, # response_model
- environment,
- application_name,
- False, # is_stream
- 0, # tbt
- 0, # ttft
- version,
- )
-
- # Set vectordb-specific attributes using semcov
- if hasattr(instance, "name"):
- span.set_attribute(SemanticConvention.GEN_AI_VECTORDB_NAME, str(instance.name))
-
- if hasattr(instance, "dimensions"):
+ if not tools:
+ return
+ tool_defs = []
+ for tool in tools[:10]:
+ functions = getattr(tool, "functions", None)
+ if isinstance(functions, dict) and functions:
+ for fn_name, fn in functions.items():
+ entry = {"type": "function", "name": str(fn_name)}
+ desc = _get_function_description(fn)
+ if desc:
+ entry["description"] = truncate_content(str(desc))
+ tool_defs.append(entry)
+ else:
+ entry = {"type": "function"}
+ name = getattr(tool, "name", None) or getattr(tool, "__name__", None)
+ if name:
+ entry["name"] = str(name)
+ desc = _get_function_description(tool)
+ if not desc:
+ desc = getattr(tool, "__doc__", None)
+ if desc:
+ entry["description"] = truncate_content(str(desc))
+ if len(entry) > 1:
+ tool_defs.append(entry)
+ if tool_defs:
span.set_attribute(
- SemanticConvention.GEN_AI_VECTORDB_DIMENSIONS, instance.dimensions
+ SemanticConvention.GEN_AI_TOOL_DEFINITIONS, json.dumps(tool_defs)
)
- # Search-specific attributes
- if operation_type == "vectordb_search" and args:
- query = args[0] if args else None
- if query:
- if isinstance(query, str):
- span.set_attribute(
- SemanticConvention.GEN_AI_VECTORDB_SEARCH_QUERY,
- truncate_content(query),
- )
- elif hasattr(query, "__len__"):
- span.set_attribute(
- SemanticConvention.GEN_AI_VECTORDB_SEARCH_VECTOR_SIZE, len(query)
- )
-
- limit = kwargs.get("limit", args[1] if len(args) > 1 else None)
- if limit:
- span.set_attribute(SemanticConvention.GEN_AI_VECTORDB_SEARCH_LIMIT, limit)
- # Upsert-specific attributes
- if operation_type == "vectordb_upsert" and args:
- documents = args[0] if args else None
- if documents and hasattr(documents, "__len__"):
+# ---------------------------------------------------------------------------
+# Content capture (structured JSON format)
+# ---------------------------------------------------------------------------
+def _capture_content_as_attributes(span, instance, response, endpoint, args, kwargs):
+ """Record input/output as span attributes in structured JSON format."""
+ try:
+ # Input messages
+ input_content = None
+ if endpoint.startswith("agent_") or endpoint.startswith("team_"):
+ if args and args[0]:
+ input_content = str(args[0])
+ elif kwargs.get("input"):
+ input_content = str(kwargs["input"])
+ elif kwargs.get("input_message"):
+ input_content = str(kwargs["input_message"])
+ elif kwargs.get("message"):
+ input_content = str(kwargs["message"])
+
+ if input_content:
span.set_attribute(
- SemanticConvention.GEN_AI_VECTORDB_UPSERT_DOCUMENT_COUNT, len(documents)
+ SemanticConvention.GEN_AI_INPUT_MESSAGES,
+ json.dumps(
+ [{"role": "user", "content": truncate_content(input_content)}]
+ ),
)
- # Set execution metrics
- span.set_attribute(
- SemanticConvention.GEN_AI_VECTORDB_OPERATION_DURATION, execution_time
- )
+ # Output messages
+ if response is not None:
+ output_content = None
+ if hasattr(response, "content") and response.content:
+ output_content = str(response.content)
+ elif hasattr(response, "message") and response.message:
+ output_content = str(response.message)
+ elif hasattr(response, "result") and response.result:
+ output_content = str(response.result)
+ elif isinstance(response, str):
+ output_content = response
- # Process result
- if response:
- span.set_attribute(SemanticConvention.GEN_AI_VECTORDB_OPERATION_SUCCESS, True)
- if operation_type == "vectordb_search" and hasattr(response, "__len__"):
- span.set_attribute(
- SemanticConvention.GEN_AI_VECTORDB_SEARCH_RESULTS_COUNT, len(response)
- )
- if response and hasattr(response[0], "score"):
- scores = [r.score for r in response[:5]] # Top 5 scores
+ if output_content:
span.set_attribute(
- SemanticConvention.GEN_AI_VECTORDB_SEARCH_TOP_SCORES, scores
+ SemanticConvention.GEN_AI_OUTPUT_MESSAGES,
+ json.dumps(
+ [
+ {
+ "role": "assistant",
+ "content": truncate_content(output_content),
+ }
+ ]
+ ),
)
- else:
- span.set_attribute(SemanticConvention.GEN_AI_VECTORDB_OPERATION_SUCCESS, False)
+ except Exception:
+ pass
-def process_knowledge_request(
- span,
- instance,
- args,
- kwargs,
- response,
- start_time,
- pricing_info,
+# ---------------------------------------------------------------------------
+# Metrics recording
+# ---------------------------------------------------------------------------
+def _record_agno_metrics(
+ metrics,
+ operation_type,
+ duration,
environment,
application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
- operation_type="knowledge_search",
+ request_model,
+ server_address,
+ server_port,
):
- """
- Process knowledge operation request and generate ALL telemetry attributes from semcov
- """
-
- execution_time = time.time() - start_time
-
- # Create scope object for common_span_attributes compatibility
- scope = _ScopeWrapper(span, instance, kwargs, args, start_time)
+ """Record OTel-compliant metrics with correct attribute keys."""
+ try:
+ attributes = {
+ SemanticConvention.GEN_AI_OPERATION: operation_type,
+ SemanticConvention.GEN_AI_PROVIDER_NAME: SemanticConvention.GEN_AI_SYSTEM_AGNO,
+ "service.name": application_name,
+ "deployment.environment": environment,
+ }
+ if request_model and request_model != "unknown":
+ attributes[SemanticConvention.GEN_AI_REQUEST_MODEL] = request_model
+ if server_address:
+ attributes[SemanticConvention.SERVER_ADDRESS] = server_address
+ if server_port:
+ attributes[SemanticConvention.SERVER_PORT] = server_port
+
+ if "genai_client_operation_duration" in metrics:
+ metrics["genai_client_operation_duration"].record(duration, attributes)
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# create_agent span emitter
+# ---------------------------------------------------------------------------
+def emit_create_agent_spans(
+ tracer, instance, version, environment, application_name, capture_message_content
+):
+ """Emit a ``create_agent`` span for an Agent.__init__ call.
- # Use common span attributes for knowledge operations
- common_span_attributes(
- scope,
- f"gen_ai.operation.{operation_type}",
- SemanticConvention.GEN_AI_SYSTEM_AGNO,
- "localhost", # server_address
- 80, # server_port
- None, # request_model
- None, # response_model
- environment,
- application_name,
- False, # is_stream
- 0, # tbt
- 0, # ttft
- version,
- )
+ Returns the SpanContext so the caller can store it on
+ ``instance._openlit_creation_context`` for later span linking.
+ """
+ try:
+ from opentelemetry.sdk.resources import TELEMETRY_SDK_NAME, SERVICE_NAME
+ from opentelemetry.semconv.resource import ResourceAttributes
- # Search-specific attributes
- if operation_type == "knowledge_search":
- query = args[0] if args else None
- if query and capture_message_content:
+ DEPLOYMENT_ENVIRONMENT = getattr(
+ ResourceAttributes, "DEPLOYMENT_ENVIRONMENT", "deployment.environment"
+ )
+ except ImportError:
+ TELEMETRY_SDK_NAME = "telemetry.sdk.name"
+ SERVICE_NAME = "service.name"
+ DEPLOYMENT_ENVIRONMENT = "deployment.environment"
+
+ try:
+ start_time = time.time()
+ name = getattr(instance, "name", None) or "agent"
+ span_name = f"{SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT} {name}"
+
+ with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
+ span.set_attribute(TELEMETRY_SDK_NAME, "openlit")
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OPERATION,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,
+ )
span.set_attribute(
- SemanticConvention.GEN_AI_KNOWLEDGE_SEARCH_QUERY,
- truncate_content(query),
+ SemanticConvention.GEN_AI_PROVIDER_NAME,
+ SemanticConvention.GEN_AI_SYSTEM_AGNO,
)
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(name))
- limit = kwargs.get("limit", args[1] if len(args) > 1 else 5)
- span.set_attribute(SemanticConvention.GEN_AI_KNOWLEDGE_SEARCH_LIMIT, limit)
+ model_name = _extract_model_name(instance)
+ if model_name and model_name != "unknown":
+ span.set_attribute(SemanticConvention.GEN_AI_REQUEST_MODEL, model_name)
+
+ agent_id = getattr(instance, "agent_id", None) or getattr(
+ instance, "id", None
+ )
+ if not agent_id and name:
+ agent_id = name.lower().replace(" ", "_")
+ if agent_id:
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_ID, str(agent_id))
- # Add-specific attributes
- if operation_type == "knowledge_add" and args:
- documents = args[0] if args else None
- if documents:
- if hasattr(documents, "__len__"):
+ description = getattr(instance, "description", None)
+ if description:
span.set_attribute(
- SemanticConvention.GEN_AI_KNOWLEDGE_ADD_DOCUMENT_COUNT,
- len(documents),
+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION,
+ truncate_content(str(description)),
)
- else:
+
+ instructions = getattr(instance, "instructions", None)
+ if instructions and capture_message_content:
span.set_attribute(
- SemanticConvention.GEN_AI_KNOWLEDGE_ADD_CONTENT_LENGTH,
- len(str(documents)),
+ SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS,
+ truncate_content(str(instructions)),
)
- # Set execution metrics
- span.set_attribute(
- SemanticConvention.GEN_AI_KNOWLEDGE_OPERATION_DURATION, execution_time
- )
+ _set_tool_definitions(span, getattr(instance, "tools", None) or [])
- # Process result
- if response:
- span.set_attribute(SemanticConvention.GEN_AI_KNOWLEDGE_OPERATION_SUCCESS, True)
- if operation_type == "knowledge_search" and hasattr(response, "__len__"):
+ server_address, server_port = set_server_address_and_port(instance)
+ if server_address:
+ span.set_attribute(SemanticConvention.SERVER_ADDRESS, server_address)
+ if server_port:
+ span.set_attribute(SemanticConvention.SERVER_PORT, server_port)
+
+ span.set_attribute(DEPLOYMENT_ENVIRONMENT, environment)
+ span.set_attribute(SERVICE_NAME, application_name)
+ span.set_attribute(SemanticConvention.GEN_AI_SDK_VERSION, version)
span.set_attribute(
- SemanticConvention.GEN_AI_KNOWLEDGE_SEARCH_RESULTS_COUNT, len(response)
+ SemanticConvention.GEN_AI_CLIENT_OPERATION_DURATION,
+ time.time() - start_time,
)
- else:
- span.set_attribute(SemanticConvention.GEN_AI_KNOWLEDGE_OPERATION_SUCCESS, False)
+ span.set_status(Status(StatusCode.OK))
+ return span.get_span_context()
+ except Exception:
+ return None
-def process_workflow_request(
+
+# ---------------------------------------------------------------------------
+# Main response processor (replaces all process_*_request functions)
+# ---------------------------------------------------------------------------
+def process_agno_response(
+ response,
+ endpoint,
span,
instance,
args,
kwargs,
- response,
start_time,
- pricing_info,
environment,
application_name,
metrics,
@@ -681,143 +734,139 @@ def process_workflow_request(
disable_metrics,
version,
):
- """
- Process workflow operation request and generate ALL telemetry attributes from semcov
- """
+ """Set OTel-compliant span attributes, capture content, and record metrics."""
+ end_time = time.time()
+ duration = end_time - start_time
+ operation_type = OPERATION_MAP.get(
+ endpoint, SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT
+ )
+
+ # -- common framework attributes --
+ scope = type("Scope", (), {})()
+ scope._span = span
+ scope._start_time = start_time
+ scope._end_time = end_time
+
+ request_model = _extract_model_name(instance)
+ server_address, server_port = set_server_address_and_port(instance)
- execution_time = time.time() - start_time
- workflow_name = getattr(instance, "name", "unknown_workflow")
+ class _ModelProxy: # pylint: disable=too-few-public-methods
+ def __init__(self, orig, model):
+ self._original = orig
+ self.model_name = model
- # Create scope object for common_span_attributes compatibility
- scope = _ScopeWrapper(span, instance, kwargs, args, start_time)
+ def __getattr__(self, name):
+ return getattr(self._original, name)
- # Use common span attributes for workflow operations
- common_span_attributes(
+ proxy = _ModelProxy(instance, request_model) if instance else None
+
+ common_framework_span_attributes(
scope,
- SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,
SemanticConvention.GEN_AI_SYSTEM_AGNO,
- "localhost", # server_address
- 80, # server_port
- None, # request_model
- None, # response_model
+ server_address,
+ server_port,
environment,
application_name,
- False, # is_stream
- 0, # tbt
- 0, # ttft
version,
+ endpoint,
+ proxy,
)
- # Set workflow-specific attributes using semcov
- span.set_attribute(SemanticConvention.GEN_AI_WORKFLOW_NAME, workflow_name)
+ # Override raw endpoint with standard OTel operation name
+ span.set_attribute(SemanticConvention.GEN_AI_OPERATION, operation_type)
- if hasattr(instance, "agents") and instance.agents:
- span.set_attribute(
- SemanticConvention.GEN_AI_WORKFLOW_AGENT_COUNT, len(instance.agents)
- )
-
- if hasattr(instance, "description") and instance.description:
- span.set_attribute(
- SemanticConvention.GEN_AI_WORKFLOW_DESCRIPTION,
- truncate_content(instance.description),
- )
-
- # Set execution metrics
- span.set_attribute(
- SemanticConvention.GEN_AI_WORKFLOW_EXECUTION_DURATION, execution_time
+ # -- entity-specific attributes --
+ _set_agent_attributes(span, instance, endpoint, capture_message_content)
+ _set_team_attributes(span, instance, endpoint)
+ _set_workflow_attributes(span, instance, endpoint)
+ tool_errored = _set_tool_attributes(
+ span, instance, endpoint, capture_message_content, args, kwargs, response
)
- span.set_attribute(
- SemanticConvention.GEN_AI_WORKFLOW_OPERATION_SUCCESS, response is not None
+ _set_retrieval_attributes(span, instance, endpoint, args, kwargs)
+ _set_memory_attributes(
+ span, instance, endpoint, args, kwargs, capture_message_content
)
+ # -- content capture as structured JSON --
+ if capture_message_content:
+ _capture_content_as_attributes(span, instance, response, endpoint, args, kwargs)
-def process_team_request(
- span,
- instance,
- args,
- kwargs,
- response,
- start_time,
- pricing_info,
- environment,
- application_name,
- metrics,
- capture_message_content,
- disable_metrics,
- version,
-):
- """
- Process team operation request and generate ALL telemetry attributes from semcov
- """
-
- execution_time = time.time() - start_time
- team_name = getattr(instance, "name", "unknown_team")
+ # -- output type (not applicable for tool spans) --
+ if operation_type != SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_TYPE,
+ SemanticConvention.GEN_AI_OUTPUT_TYPE_TEXT,
+ )
- # Create scope object for common_span_attributes compatibility
- scope = _ScopeWrapper(span, instance, kwargs, args, start_time)
+ # -- token usage from RunOutput/TeamRunOutput --
+ if response and (endpoint.startswith("agent_") or endpoint.startswith("team_")):
+ input_tokens, output_tokens = _extract_token_usage(response)
+ if input_tokens:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, input_tokens
+ )
+ if output_tokens:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, output_tokens
+ )
- # Use common span attributes for team operations
- common_span_attributes(
- scope,
- SemanticConvention.GEN_AI_OPERATION_TYPE_TEAM,
- SemanticConvention.GEN_AI_SYSTEM_AGNO,
- "localhost", # server_address
- 80, # server_port
- None, # request_model
- None, # response_model
- environment,
- application_name,
- False, # is_stream
- 0, # tbt
- 0, # ttft
- version,
- )
+ # -- run_id from RunOutput --
+ if response:
+ run_id = getattr(response, "run_id", None)
+ if run_id:
+ span.set_attribute("gen_ai.response.id", str(run_id))
+
+ # -- session/conversation from kwargs or parent contextvar --
+ if kwargs:
+ session_id = kwargs.get("session_id")
+ if not session_id:
+ session = kwargs.get("session")
+ if session and hasattr(session, "session_id"):
+ session_id = session.session_id
+ if session_id:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_CONVERSATION_ID, str(session_id)
+ )
- # Set team-specific attributes using semcov
- span.set_attribute(SemanticConvention.GEN_AI_TEAM_NAME, team_name)
+ user_id = kwargs.get("user_id")
+ if user_id:
+ span.set_attribute(SemanticConvention.GEN_AI_REQUEST_USER, str(user_id))
- if hasattr(instance, "agents") and instance.agents:
- agent_names = [getattr(agent, "name", "unknown") for agent in instance.agents]
- span.set_attribute(
- SemanticConvention.GEN_AI_TEAM_AGENTS, agent_names[:10]
- ) # Limit to 10
- span.set_attribute(
- SemanticConvention.GEN_AI_TEAM_AGENT_COUNT, len(instance.agents)
- )
+ if endpoint.startswith("tool_"):
+ parent_agent = _agno_parent_agent.get()
+ if parent_agent:
+ parent_session_id = getattr(parent_agent, "session_id", None)
+ if parent_session_id:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_CONVERSATION_ID,
+ str(parent_session_id),
+ )
- if hasattr(instance, "members") and instance.members:
- agent_names = [getattr(agent, "name", "unknown") for agent in instance.members]
- span.set_attribute(
- SemanticConvention.GEN_AI_TEAM_AGENTS, agent_names[:10]
- ) # Limit to 10
- span.set_attribute(
- SemanticConvention.GEN_AI_TEAM_AGENT_COUNT, len(instance.members)
+ # -- metrics --
+ if not disable_metrics and metrics:
+ _record_agno_metrics(
+ metrics,
+ operation_type,
+ duration,
+ environment,
+ application_name,
+ request_model,
+ server_address,
+ server_port,
)
- # Set execution metrics
- span.set_attribute(
- SemanticConvention.GEN_AI_TEAM_EXECUTION_DURATION, execution_time
- )
- span.set_attribute(
- SemanticConvention.GEN_AI_TEAM_OPERATION_SUCCESS, response is not None
- )
+ if tool_errored:
+ span.set_status(Status(StatusCode.ERROR, "Tool execution failed"))
+ else:
+ span.set_status(Status(StatusCode.OK))
+ return response
+# ---------------------------------------------------------------------------
+# Version-compat target resolvers (kept as-is)
+# ---------------------------------------------------------------------------
def resolve_agno_memory_target():
- """
- Resolve the appropriate Agno memory target class.
-
- Attempts to find and import the correct memory class from Agno framework.
- Tries multiple candidate modules in order of preference.
-
- Returns:
- tuple: (module_name, class_name) if successful, (None, None) if no valid target found
-
- Example:
- >>> module, class_name = resolve_agno_memory_target()
- >>> if module:
- ... print(f"Found memory class: {class_name} in {module}")
- """
+ """Resolve the appropriate Agno memory target class."""
return resolve_target(
"agno.memory",
(
@@ -828,20 +877,7 @@ def resolve_agno_memory_target():
def resolve_agno_knowledge_target():
- """
- Resolve the appropriate Agno knowledge target class.
-
- Attempts to find and import the correct knowledge class from Agno framework.
- Tries multiple candidate modules in order of preference.
-
- Returns:
- tuple: (module_name, class_name) if successful, (None, None) if no valid target found
-
- Example:
- >>> module, class_name = resolve_agno_knowledge_target()
- >>> if module:
- ... print(f"Found knowledge class: {class_name} in {module}")
- """
+ """Resolve the appropriate Agno knowledge target class."""
return resolve_target(
"agno.knowledge",
(
@@ -852,28 +888,7 @@ def resolve_agno_knowledge_target():
def resolve_target(target_name, candidates):
- """
- Resolve a target class by trying multiple candidate modules.
-
- This function attempts to import and find a specific class from a list of candidate
- modules. It tries each candidate in order until it finds a valid module and class.
-
- Args:
- target_name (str): Name of the target being resolved (used for logging)
- candidates (tuple): Tuple of (module_name, class_name) pairs to try
-
- Returns:
- tuple: (module_name, class_name) if successful, (None, None) if no valid target found
-
- Example:
- >>> candidates = (
- ... ("agno.memory.v2.memory", "Memory"),
- ... ("agno.memory.manager", "MemoryManager")
- ... )
- >>> module, class_name = resolve_target("agno.memory", candidates)
- >>> if module:
- ... print(f"Found: {class_name} in {module}")
- """
+ """Resolve a target class by trying multiple candidate modules."""
for module_name, class_name in candidates:
try:
module = importlib.import_module(module_name)
@@ -882,6 +897,6 @@ def resolve_target(target_name, candidates):
except ModuleNotFoundError:
continue
except Exception as e:
- logger.info(f"Skip {target_name} candidate %s due to: %s", module_name, e)
+ logger.info("Skip %s candidate %s due to: %s", target_name, module_name, e)
continue
return None, None
diff --git a/sdk/python/src/openlit/instrumentation/anthropic/anthropic.py b/sdk/python/src/openlit/instrumentation/anthropic/anthropic.py
index e813e697..b226b886 100644
--- a/sdk/python/src/openlit/instrumentation/anthropic/anthropic.py
+++ b/sdk/python/src/openlit/instrumentation/anthropic/anthropic.py
@@ -8,6 +8,7 @@ from openlit.__helpers import (
handle_exception,
set_server_address_and_port,
record_completion_metrics,
+ is_framework_llm_active,
)
from openlit.instrumentation.anthropic.utils import (
process_chunk,
@@ -115,6 +116,9 @@ def messages(
Wraps the Anthropic Messages.create call.
"""
+ if is_framework_llm_active():
+ return wrapped(*args, **kwargs)
+
streaming = kwargs.get("stream", False)
server_address, server_port = set_server_address_and_port(
instance, "api.anthropic.com", 443
diff --git a/sdk/python/src/openlit/instrumentation/anthropic/async_anthropic.py b/sdk/python/src/openlit/instrumentation/anthropic/async_anthropic.py
index bc396793..aa8377c9 100644
--- a/sdk/python/src/openlit/instrumentation/anthropic/async_anthropic.py
+++ b/sdk/python/src/openlit/instrumentation/anthropic/async_anthropic.py
@@ -8,6 +8,7 @@ from openlit.__helpers import (
handle_exception,
set_server_address_and_port,
record_completion_metrics,
+ is_framework_llm_active,
)
from openlit.instrumentation.anthropic.utils import (
process_chunk,
@@ -115,6 +116,9 @@ def async_messages(
Wraps the Anthropic AsyncMessages.create call.
"""
+ if is_framework_llm_active():
+ return await wrapped(*args, **kwargs)
+
streaming = kwargs.get("stream", False)
server_address, server_port = set_server_address_and_port(
instance, "api.anthropic.com", 443
diff --git a/sdk/python/src/openlit/instrumentation/crewai/__init__.py b/sdk/python/src/openlit/instrumentation/crewai/__init__.py
index d32a3890..a2970161 100644
--- a/sdk/python/src/openlit/instrumentation/crewai/__init__.py
+++ b/sdk/python/src/openlit/instrumentation/crewai/__init__.py
@@ -1,5 +1,8 @@
"""
-OpenLIT CrewAI Instrumentation
+OpenLIT CrewAI Instrumentation — OTel GenAI semantic convention compliant.
+
+Targets CrewAI >= 1.10.0 (unified memory, Flow support).
+All module paths verified against the actual CrewAI SDK.
"""
from typing import Collection
@@ -10,46 +13,84 @@ from wrapt import wrap_function_wrapper
from openlit.instrumentation.crewai.crewai import general_wrap
from openlit.instrumentation.crewai.async_crewai import async_general_wrap
-_instruments = ("crewai >= 0.80.0",)
+_instruments = ("crewai >= 1.10.0",)
-# === WORKFLOW OPERATIONS (Always enabled) - 8 operations ===
+# === ALWAYS-ON OPERATIONS ===
+# Each tuple: (module, method, operation_key, sync_type)
WORKFLOW_OPERATIONS = [
- # Crew Execution Operations
- ("crewai.crew", "Crew.kickoff", "crew_kickoff"),
- ("crewai.crew", "Crew.kickoff_async", "crew_kickoff_async"),
- ("crewai.crew", "Crew.kickoff_for_each", "crew_kickoff_for_each"),
- ("crewai.crew", "Crew.kickoff_for_each_async", "crew_kickoff_for_each_async"),
- # High-level Agent and Task Operations
- ("crewai.agent", "Agent.execute_task", "agent_execute_task"),
- ("crewai.task", "Task.execute", "task_execute"),
- ("crewai.task", "Task.execute_async", "task_execute_async"),
+ # Crew construction — create_agent spans
+ ("crewai.crew", "Crew.__init__", "crew_init", "sync"),
+ # Crew execution — invoke_workflow (OTel spec)
+ ("crewai.crew", "Crew.kickoff", "crew_kickoff", "sync"),
+ ("crewai.crew", "Crew.kickoff_async", "crew_kickoff_async", "async"),
+ ("crewai.crew", "Crew.kickoff_for_each", "crew_kickoff_for_each", "sync"),
+ (
+ "crewai.crew",
+ "Crew.kickoff_for_each_async",
+ "crew_kickoff_for_each_async",
+ "async",
+ ),
+ # Task execution — invoke_agent
+ ("crewai.task", "Task._execute_core", "task_execute_core", "sync"),
+ # Tool execution — execute_tool (corrected module path)
+ ("crewai.tools.base_tool", "BaseTool.run", "tool_run", "sync"),
+ # Flow execution — invoke_workflow
+ ("crewai.flow.flow", "Flow.kickoff", "flow_kickoff", "sync"),
+ ("crewai.flow.flow", "Flow.kickoff_async", "flow_kickoff_async", "async"),
]
-# === COMPONENT OPERATIONS (Detailed tracing only) - 12 operations ===
-COMPONENT_OPERATIONS = [
- # Tool and Memory Operations
- ("crewai.tools.base", "BaseTool.run", "tool_run"),
- ("crewai.tools.base", "BaseTool._run", "tool_run_internal"),
- ("crewai.memory.base", "BaseMemory.save", "memory_save"),
- ("crewai.memory.base", "BaseMemory.search", "memory_search"),
- # Process and Collaboration Operations
- ("crewai.process", "Process.kickoff", "process_kickoff"),
- ("crewai.agent", "Agent.delegate", "agent_delegate"),
- ("crewai.agent", "Agent.ask_question", "agent_ask_question"),
- ("crewai.task", "Task.callback", "task_callback"),
- # Internal Task Management
- # Instrument only the core task execution (remove the sync duplicate)
- # Task Operations (keep only core execution)
- ("crewai.task", "Task._execute_core", "task_execute_core"),
+# === DETAILED-TRACING OPERATIONS ===
+DETAILED_OPERATIONS = [
+ # Agent standalone kickoff — invoke_agent
+ ("crewai", "Agent.kickoff", "agent_kickoff", "sync"),
+ # Flow node execution — invoke_agent
+ ("crewai.flow.flow", "Flow._execute_method", "flow_execute_method", "sync"),
]
-class CrewAIInstrumentor(BaseInstrumentor):
- """
- Modern instrumentor for CrewAI framework with comprehensive coverage.
- Implements OpenLIT Framework Instrumentation Guide patterns.
+class _ContextPropagatingDescriptor: # pylint: disable=too-few-public-methods
+ """Propagate OTel context from the calling thread into CrewAI's
+ ThreadPoolExecutor so that child spans (tool, task) are properly
+ parented under the agent / workflow span.
+
+ ``Agent._execute_without_timeout`` is resolved via ``__get__`` in the
+ *main* thread (which holds the correct OTel context) before being
+ submitted to the thread pool. The returned closure re-attaches that
+ context in the *worker* thread.
"""
+ def __init__(self, original):
+ self._original = original
+ self._name = None
+
+ def __set_name__(self, owner, name):
+ self._name = name
+
+ def __get__(self, obj, objtype=None):
+ if obj is None:
+ return self
+ from opentelemetry import context as context_api
+
+ bound = self._original.__get__(obj, objtype)
+ ctx = context_api.get_current()
+
+ def _propagating_wrapper(*args, **kwargs):
+ token = context_api.attach(ctx)
+ try:
+ return bound(*args, **kwargs)
+ finally:
+ context_api.detach(token)
+
+ return _propagating_wrapper
+
+
+class CrewAIInstrumentor(BaseInstrumentor):
+ """OTel GenAI semantic convention compliant instrumentor for CrewAI."""
+
+ def __init__(self):
+ super().__init__()
+ self._original_execute_without_timeout = None
+
def instrumentation_dependencies(self) -> Collection[str]:
return _instruments
@@ -64,74 +105,67 @@ class CrewAIInstrumentor(BaseInstrumentor):
disable_metrics = kwargs.get("disable_metrics")
detailed_tracing = kwargs.get("detailed_tracing", False)
- # === WORKFLOW OPERATIONS (Always enabled) ===
- for module, method, operation_type in WORKFLOW_OPERATIONS:
+ wrap_args = (
+ version,
+ environment,
+ application_name,
+ tracer,
+ pricing_info,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ )
+
+ # -- always-on operations --
+ for module, method, op_key, sync_type in WORKFLOW_OPERATIONS:
try:
- wrap_function_wrapper(
- module,
- method,
- general_wrap(
- operation_type,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
+ if sync_type == "async":
+ wrapper = async_general_wrap(op_key, *wrap_args)
+ else:
+ wrapper = general_wrap(op_key, *wrap_args)
+ wrap_function_wrapper(module, method, wrapper)
except Exception:
- # Graceful degradation for missing operations
pass
- # === ASYNC WORKFLOW OPERATIONS ===
- for module, method, operation_type in WORKFLOW_OPERATIONS:
- if "async" in operation_type:
- try:
- wrap_function_wrapper(
- module,
- method,
- async_general_wrap(
- operation_type,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
- except Exception:
- pass
-
- # === COMPONENT OPERATIONS (Detailed tracing only) ===
+ # -- detailed-tracing operations --
if detailed_tracing:
- for module, method, operation_type in COMPONENT_OPERATIONS:
+ for module, method, op_key, sync_type in DETAILED_OPERATIONS:
try:
- wrap_function_wrapper(
- module,
- method,
- general_wrap(
- operation_type,
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- ),
- )
+ if sync_type == "async":
+ wrapper = async_general_wrap(op_key, *wrap_args)
+ else:
+ wrapper = general_wrap(op_key, *wrap_args)
+ wrap_function_wrapper(module, method, wrapper)
except Exception:
pass
- # Total operations: 8 workflow + 4 async + (12 component if detailed) = 12 baseline, 24 with detailed tracing
- # Beats competitors (5-10 operations) by 140-380%
+ # -- thread context propagation --
+ self._install_context_propagation()
+
+ def _install_context_propagation(self):
+ """Replace ``Agent._execute_without_timeout`` with a descriptor that
+ propagates OTel context across CrewAI's thread-pool boundary."""
+ try:
+ import crewai.agent.core as _agent_core
+
+ original = getattr(_agent_core.Agent, "_execute_without_timeout", None)
+ if original is not None and not isinstance(
+ original, _ContextPropagatingDescriptor
+ ):
+ self._original_execute_without_timeout = original
+ _agent_core.Agent._execute_without_timeout = (
+ _ContextPropagatingDescriptor(original)
+ )
+ except Exception:
+ pass
def _uninstrument(self, **kwargs):
- """Uninstrument CrewAI operations"""
+ """Best-effort restoration of the context-propagation descriptor."""
+ try:
+ import crewai.agent.core as _agent_core
+
+ original = getattr(self, "_original_execute_without_timeout", None)
+ if original is not None:
+ _agent_core.Agent._execute_without_timeout = original
+ except Exception:
+ pass
diff --git a/sdk/python/src/openlit/instrumentation/crewai/async_crewai.py b/sdk/python/src/openlit/instrumentation/crewai/async_crewai.py
index 7fecede9..a4882ce6 100644
--- a/sdk/python/src/openlit/instrumentation/crewai/async_crewai.py
+++ b/sdk/python/src/openlit/instrumentation/crewai/async_crewai.py
@@ -1,15 +1,24 @@
"""
-CrewAI async wrapper using modern async_general_wrap pattern
+CrewAI async wrapper — OTel GenAI semantic convention compliant.
+
+Mirrors the sync wrapper with async/await support and checks
+deduplication flags set by the sync wrapper to prevent double-spanning.
"""
import time
-from opentelemetry.trace import SpanKind
from opentelemetry import context as context_api
+from opentelemetry.trace import Link
from openlit.__helpers import handle_exception
from openlit.instrumentation.crewai.utils import (
process_crewai_response,
OPERATION_MAP,
+ get_span_kind,
+ generate_span_name,
set_server_address_and_port,
+ _crewai_crew_active,
+ _crewai_flow_active,
+ _current_agent_model_info,
+ _compute_agent_model_info,
)
@@ -24,91 +33,74 @@ def async_general_wrap(
metrics,
disable_metrics,
):
- """
- Modern async wrapper for CrewAI operations following Framework Instrumentation Guide patterns.
- """
+ """Create an async wrapper for a CrewAI operation."""
async def wrapper(wrapped, instance, args, kwargs):
- """
- Wraps the async CrewAI operation call with comprehensive telemetry.
- """
-
- # CRITICAL: Suppression check
if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
return await wrapped(*args, **kwargs)
- # Get server address and port using the standard helper
- server_address, server_port = set_server_address_and_port(instance)
-
- # Get operation type from mapping
- operation_type = OPERATION_MAP.get(gen_ai_endpoint, "framework")
-
- # Generate span name following {operation_type} {operation_name} pattern
- span_name = _generate_span_name(
- operation_type, gen_ai_endpoint, instance, args, kwargs
- )
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
- response = await wrapped(*args, **kwargs)
-
- try:
- # Process response and generate comprehensive telemetry
- response = process_crewai_response(
- response,
- operation_type,
- server_address,
- server_port,
- environment,
- application_name,
- metrics,
- start_time,
- span,
- capture_message_content,
- disable_metrics,
- version,
- instance,
- args,
- endpoint=gen_ai_endpoint,
- **kwargs,
- )
-
- except Exception as e:
- handle_exception(span, e)
+ # Deduplication: if the sync variant already created a span, pass through.
+ if gen_ai_endpoint == "crew_kickoff_async" and _crewai_crew_active.get():
+ return await wrapped(*args, **kwargs)
+ if gen_ai_endpoint == "flow_kickoff_async" and _crewai_flow_active.get():
+ return await wrapped(*args, **kwargs)
- return response
+ server_address, server_port = set_server_address_and_port(instance)
+ operation_type = OPERATION_MAP.get(gen_ai_endpoint, "invoke_agent")
+ span_kind = get_span_kind(operation_type)
+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)
+
+ # Propagate agent model info to child execute_tool spans
+ model_info_token = None
+ if gen_ai_endpoint == "task_execute_core":
+ model_info_token = _current_agent_model_info.set(
+ _compute_agent_model_info(instance)
+ )
+
+ # Span links: connect invoke_workflow back to create_agent spans
+ links = []
+ if gen_ai_endpoint in (
+ "crew_kickoff_async",
+ "crew_kickoff_for_each_async",
+ ):
+ creation_ctxs = getattr(instance, "_openlit_creation_contexts", None)
+ if creation_ctxs:
+ links = [Link(ctx) for ctx in creation_ctxs]
+
+ try:
+ with tracer.start_as_current_span(
+ span_name, kind=span_kind, links=links
+ ) as span:
+ start_time = time.time()
+ try:
+ response = await wrapped(*args, **kwargs)
+
+ process_crewai_response(
+ response,
+ operation_type,
+ server_address,
+ server_port,
+ environment,
+ application_name,
+ metrics,
+ start_time,
+ span,
+ capture_message_content,
+ disable_metrics,
+ version,
+ instance,
+ args,
+ endpoint=gen_ai_endpoint,
+ **kwargs,
+ )
+
+ return response
+
+ except Exception as e:
+ handle_exception(span, e)
+ raise
+ finally:
+ if model_info_token is not None:
+ _current_agent_model_info.reset(model_info_token)
return wrapper
-
-
-def _generate_span_name(operation_type, endpoint, instance, args, kwargs):
- """
- Generate proper span names following {operation_type} {operation_name} convention.
- """
-
- # Crew-level operations
- if endpoint.startswith("crew_"):
- crew_name = getattr(instance, "name", None) or "CrewAI Workflow"
- if endpoint == "crew_kickoff_async":
- return f"{operation_type} {crew_name}"
- elif endpoint == "crew_kickoff_for_each_async":
- return f"{operation_type} {crew_name} Batch"
- else:
- return f"{operation_type} {crew_name}"
-
- # Agent-level operations
- elif endpoint.startswith("agent_"):
- agent_role = getattr(instance, "role", None) or "Agent"
- return f"{operation_type} {agent_role}"
-
- # Task-level operations
- elif endpoint.startswith("task_"):
- task_description = getattr(instance, "description", None)
- if task_description and len(task_description) < 50:
- return f"{operation_type} {task_description}"
- else:
- return f"{operation_type} Task"
-
- # Default naming for async operations
- else:
- return f"{operation_type} {endpoint}"
diff --git a/sdk/python/src/openlit/instrumentation/crewai/crewai.py b/sdk/python/src/openlit/instrumentation/crewai/crewai.py
index cfbd02ec..d137c1a1 100644
--- a/sdk/python/src/openlit/instrumentation/crewai/crewai.py
+++ b/sdk/python/src/openlit/instrumentation/crewai/crewai.py
@@ -1,15 +1,25 @@
"""
-CrewAI sync wrapper using modern general_wrap pattern
+CrewAI sync wrapper — OTel GenAI semantic convention compliant.
+
+Uses dynamic SpanKind from SPAN_KIND_MAP and deduplication contextvars
+to prevent sync→async double-spanning.
"""
import time
-from opentelemetry.trace import SpanKind
from opentelemetry import context as context_api
+from opentelemetry.trace import Link
from openlit.__helpers import handle_exception
from openlit.instrumentation.crewai.utils import (
process_crewai_response,
+ emit_create_agent_spans,
OPERATION_MAP,
+ get_span_kind,
+ generate_span_name,
set_server_address_and_port,
+ _crewai_crew_active,
+ _crewai_flow_active,
+ _current_agent_model_info,
+ _compute_agent_model_info,
)
@@ -24,103 +34,98 @@ def general_wrap(
metrics,
disable_metrics,
):
- """
- Modern wrapper for CrewAI operations following Framework Instrumentation Guide patterns.
- """
+ """Create a sync wrapper for a CrewAI operation."""
def wrapper(wrapped, instance, args, kwargs):
- """
- Wraps the CrewAI operation call with comprehensive telemetry.
- """
-
- # CRITICAL: Suppression check
if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
return wrapped(*args, **kwargs)
- # Get server address and port using the standard helper
- server_address, server_port = set_server_address_and_port(instance)
-
- # Get operation type from mapping
- operation_type = OPERATION_MAP.get(gen_ai_endpoint, "framework")
-
- # Generate span name following {operation_type} {operation_name} pattern
- span_name = _generate_span_name(
- operation_type, gen_ai_endpoint, instance, args, kwargs
- )
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
- response = wrapped(*args, **kwargs)
-
+ # crew_init: emit create_agent spans, then return
+ if gen_ai_endpoint == "crew_init":
+ result = wrapped(*args, **kwargs)
try:
- # Process response and generate comprehensive telemetry
- response = process_crewai_response(
- response,
- operation_type,
- server_address,
- server_port,
+ contexts = emit_create_agent_spans(
+ tracer,
+ instance,
+ version,
environment,
application_name,
- metrics,
- start_time,
- span,
capture_message_content,
- disable_metrics,
- version,
- instance,
- args,
- endpoint=gen_ai_endpoint,
- **kwargs,
)
+ if contexts:
+ instance._openlit_creation_contexts = contexts
+ except Exception:
+ pass
+ return result
- except Exception as e:
- handle_exception(span, e)
-
- return response
+ server_address, server_port = set_server_address_and_port(instance)
+ operation_type = OPERATION_MAP.get(gen_ai_endpoint, "invoke_agent")
+ span_kind = get_span_kind(operation_type)
+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)
+
+ # Deduplication: set flag so the async variant (called internally)
+ # knows a span already exists.
+ dedup_token = None
+ if gen_ai_endpoint == "crew_kickoff":
+ dedup_token = _crewai_crew_active.set(True)
+ elif gen_ai_endpoint == "flow_kickoff":
+ dedup_token = _crewai_flow_active.set(True)
+
+ # Propagate agent model info to child execute_tool spans
+ model_info_token = None
+ if gen_ai_endpoint == "task_execute_core":
+ model_info_token = _current_agent_model_info.set(
+ _compute_agent_model_info(instance)
+ )
+
+ # Span links: connect invoke_workflow back to create_agent spans
+ links = []
+ if gen_ai_endpoint in (
+ "crew_kickoff",
+ "crew_kickoff_for_each",
+ ):
+ creation_ctxs = getattr(instance, "_openlit_creation_contexts", None)
+ if creation_ctxs:
+ links = [Link(ctx) for ctx in creation_ctxs]
+
+ try:
+ with tracer.start_as_current_span(
+ span_name, kind=span_kind, links=links
+ ) as span:
+ start_time = time.time()
+ try:
+ response = wrapped(*args, **kwargs)
+
+ process_crewai_response(
+ response,
+ operation_type,
+ server_address,
+ server_port,
+ environment,
+ application_name,
+ metrics,
+ start_time,
+ span,
+ capture_message_content,
+ disable_metrics,
+ version,
+ instance,
+ args,
+ endpoint=gen_ai_endpoint,
+ **kwargs,
+ )
+
+ return response
+
+ except Exception as e:
+ handle_exception(span, e)
+ raise
+ finally:
+ if gen_ai_endpoint == "crew_kickoff" and dedup_token is not None:
+ _crewai_crew_active.reset(dedup_token)
+ elif gen_ai_endpoint == "flow_kickoff" and dedup_token is not None:
+ _crewai_flow_active.reset(dedup_token)
+ if model_info_token is not None:
+ _current_agent_model_info.reset(model_info_token)
return wrapper
-
-
-def _generate_span_name(operation_type, endpoint, instance, args, kwargs):
- """
- Generate proper span names following {operation_type} {operation_name} convention.
- """
-
- # Crew-level operations
- if endpoint.startswith("crew_"):
- crew_name = getattr(instance, "name", None) or "CrewAI Workflow"
- if endpoint == "crew_kickoff":
- return f"{operation_type} {crew_name}"
- elif endpoint == "crew_kickoff_for_each":
- return f"{operation_type} {crew_name} Batch"
- else:
- return f"{operation_type} {crew_name}"
-
- # Agent-level operations
- elif endpoint.startswith("agent_"):
- agent_role = getattr(instance, "role", None) or "Agent"
- return f"{operation_type} {agent_role}"
-
- # Task-level operations
- elif endpoint.startswith("task_"):
- task_description = getattr(instance, "description", None)
- if task_description and len(task_description) < 50:
- return f"{operation_type} {task_description}"
- else:
- return f"{operation_type} Task"
-
- # Tool-level operations
- elif endpoint.startswith("tool_"):
- tool_name = getattr(instance, "name", None) or "Tool"
- return f"{operation_type} {tool_name}"
-
- # Memory-level operations
- elif endpoint.startswith("memory_"):
- if "search" in endpoint:
- return "retrieve crew_memory"
- else:
- return f"{operation_type} crew_memory"
-
- # Default naming
- else:
- return f"{operation_type} {endpoint}"
diff --git a/sdk/python/src/openlit/instrumentation/crewai/utils.py b/sdk/python/src/openlit/instrumentation/crewai/utils.py
index 89c27679..34b0cc51 100644
--- a/sdk/python/src/openlit/instrumentation/crewai/utils.py
+++ b/sdk/python/src/openlit/instrumentation/crewai/utils.py
@@ -1,76 +1,193 @@
"""
-CrewAI utilities for comprehensive telemetry processing and business intelligence
+CrewAI utilities for OTel GenAI semantic convention compliant telemetry.
+
+Follows the same patterns as the LangGraph instrumentation (gold standard).
+All operation names, span kinds, and attributes comply with the OTel GenAI
+semantic conventions, particularly gen-ai-agent-spans.md which explicitly
+names CrewAI as a framework that SHOULD report invoke_workflow for crews.
"""
import time
import json
-from urllib.parse import urlparse
-from opentelemetry.trace import Status, StatusCode
+import contextvars
+from opentelemetry.trace import SpanKind, Status, StatusCode
from openlit.__helpers import (
common_framework_span_attributes,
- handle_exception,
+ get_server_address_for_provider,
+ truncate_content,
)
from openlit.semcov import SemanticConvention
-# === OPERATION MAPPING - Framework Guide Compliant ===
+# ---------------------------------------------------------------------------
+# Contextvars for span deduplication
+# Prevents sync→async double-spanning (Crew.kickoff -> Crew.kickoff_async
+# internally, and same for Flow).
+# ---------------------------------------------------------------------------
+_crewai_crew_active = contextvars.ContextVar(
+ "openlit_crewai_crew_active", default=False
+)
+_crewai_flow_active = contextvars.ContextVar(
+ "openlit_crewai_flow_active", default=False
+)
+
+# Propagates the executing agent's model info to child execute_tool spans
+_current_agent_model_info = contextvars.ContextVar(
+ "openlit_crewai_agent_model_info", default=None
+)
+
+# ---------------------------------------------------------------------------
+# OTel GenAI Operation Mapping
+# ---------------------------------------------------------------------------
OPERATION_MAP = {
- # === STANDARD OPENTELEMETRY OPERATION NAMES ===
- # Crew Operations (workflow management)
- "crew_kickoff": "invoke_agent",
- "crew_train": "invoke_agent",
- "crew_replay": "invoke_agent",
- "crew_test": "invoke_agent",
- # Agent Operations (core agent functions)
- "agent___init__": "create_agent",
- "agent_execute_task": "invoke_agent",
- "agent_backstory_property": "invoke_agent",
- # Task Operations (task execution)
- "task_execute": "invoke_agent",
- "task_execute_async": "invoke_agent",
+ "crew_init": "create_agent",
+ "crew_kickoff": "invoke_workflow",
+ "crew_kickoff_async": "invoke_workflow",
+ "crew_kickoff_for_each": "invoke_workflow",
+ "crew_kickoff_for_each_async": "invoke_workflow",
"task_execute_core": "invoke_agent",
- # Tool Operations (tool execution)
+ "agent_kickoff": "invoke_agent",
"tool_run": "execute_tool",
- "tool___call__": "execute_tool",
- "tool_execute": "execute_tool",
- # Memory Operations (knowledge management)
- "memory_save": "invoke_agent",
- "memory_search": "invoke_agent",
- "memory_reset": "invoke_agent",
+ "flow_kickoff": "invoke_workflow",
+ "flow_kickoff_async": "invoke_workflow",
+ "flow_execute_method": "invoke_agent",
}
+# ---------------------------------------------------------------------------
+# SpanKind per operation type (OTel GenAI spec)
+# ---------------------------------------------------------------------------
+SPAN_KIND_MAP = {
+ "invoke_workflow": SpanKind.INTERNAL,
+ "invoke_agent": SpanKind.INTERNAL,
+ "execute_tool": SpanKind.INTERNAL,
+ "retrieval": SpanKind.CLIENT,
+ "create_agent": SpanKind.CLIENT,
+}
-def set_server_address_and_port(instance):
- """
- Extract server information from CrewAI instance.
- Args:
- instance: CrewAI instance (Crew, Agent, Task, etc.)
+def get_span_kind(operation_type):
+ """Return the correct SpanKind for *operation_type* per OTel GenAI spec."""
+ return SPAN_KIND_MAP.get(operation_type, SpanKind.INTERNAL)
+
+
+_MODEL_PREFIX_TO_PROVIDER = {
+ "gpt-": "openai",
+ "o1": "openai",
+ "o3": "openai",
+ "o4": "openai",
+ "davinci": "openai",
+ "claude": "anthropic",
+ "gemini": "google",
+ "mistral": "mistral_ai",
+ "command": "cohere",
+ "deepseek": "deepseek",
+ "llama": "groq",
+ "mixtral": "groq",
+}
- Returns:
- tuple: (server_address, server_port)
- """
- server_address = "localhost"
- server_port = 8080
- # Try to extract LLM endpoint information
+def _infer_provider_from_model(model_name):
+ """Map a model name string to a provider key in PROVIDER_DEFAULT_ENDPOINTS."""
+ if not model_name:
+ return None
+ lower = model_name.lower()
+ for prefix, provider in _MODEL_PREFIX_TO_PROVIDER.items():
+ if lower.startswith(prefix):
+ return provider
+ return None
+
+
+def set_server_address_and_port(instance):
+ """Extract server address / port from a CrewAI instance's LLM config.
+
+ Falls back to PROVIDER_DEFAULT_ENDPOINTS when no explicit api_base is set.
+ For Tool instances, inherits from the parent agent via contextvar.
+ """
+ server_address = ""
+ server_port = 0
try:
- if hasattr(instance, "llm") and hasattr(instance.llm, "api_base"):
- parsed = urlparse(instance.llm.api_base)
- server_address = parsed.hostname or "localhost"
- server_port = parsed.port or 443
- elif hasattr(instance, "agent") and hasattr(instance.agent, "llm"):
- # For tasks that have an agent with LLM
- if hasattr(instance.agent.llm, "api_base"):
- parsed = urlparse(instance.agent.llm.api_base)
- server_address = parsed.hostname or "localhost"
+ llm = getattr(instance, "llm", None)
+ if not llm:
+ agent = getattr(instance, "agent", None)
+ if agent:
+ llm = getattr(agent, "llm", None)
+
+ # Crew instances: walk agents list
+ if not llm:
+ agents = getattr(instance, "agents", None)
+ if agents:
+ for ag in agents:
+ llm = getattr(ag, "llm", None)
+ if llm:
+ break
+
+ if llm:
+ api_base = getattr(llm, "api_base", None) or getattr(llm, "base_url", None)
+ if api_base:
+ from urllib.parse import urlparse
+
+ parsed = urlparse(str(api_base))
+ server_address = parsed.hostname or ""
server_port = parsed.port or 443
+
+ if not server_address:
+ model_name = _extract_model_name(instance)
+ provider = _infer_provider_from_model(model_name)
+ if provider:
+ server_address, server_port = get_server_address_for_provider(provider)
+
+ # Tool instances: inherit from parent agent via contextvar
+ if not server_address:
+ model_info = _current_agent_model_info.get()
+ if model_info:
+ server_address = model_info[1]
+ server_port = model_info[2]
except Exception:
- # Graceful degradation
pass
-
return server_address, server_port
+def _compute_agent_model_info(instance):
+ """Return (model_name, server_address, server_port) for a task's agent."""
+ model_name = _extract_model_name(instance)
+ server_address, server_port = set_server_address_and_port(instance)
+ return (model_name, server_address, server_port)
+
+
+def generate_span_name(endpoint, instance, args=None, kwargs=None):
+ """Return an OTel-compliant span name: ``{operation} {entity_name}``."""
+ operation = OPERATION_MAP.get(endpoint, "invoke_agent")
+
+ if endpoint.startswith("crew_"):
+ name = getattr(instance, "name", None) or "CrewAI"
+ return f"{operation} {name}"
+
+ if endpoint == "task_execute_core":
+ agent = getattr(instance, "agent", None)
+ role = getattr(agent, "role", None) if agent else None
+ return f"{operation} {role or 'agent'}"
+
+ if endpoint.startswith("agent_"):
+ role = getattr(instance, "role", None) or "agent"
+ return f"{operation} {role}"
+
+ if endpoint == "tool_run":
+ name = getattr(instance, "name", None) or type(instance).__name__
+ return f"{operation} {name}"
+
+ if endpoint in ("flow_kickoff", "flow_kickoff_async"):
+ name = getattr(instance, "name", None) or type(instance).__name__
+ return f"{operation} {name}"
+
+ if endpoint == "flow_execute_method":
+ node_name = args[0] if args else "node"
+ return f"{operation} {node_name}"
+
+ return f"{operation} {endpoint}"
+
+
+# ---------------------------------------------------------------------------
+# Main response processor
+# ---------------------------------------------------------------------------
def process_crewai_response(
response,
operation_type,
@@ -89,56 +206,27 @@ def process_crewai_response(
endpoint=None,
**kwargs,
):
- """
- Process CrewAI response with comprehensive business intelligence.
- OpenLIT's competitive advantage through superior observability.
- """
-
+ """Set OTel-compliant span attributes, capture content, and record metrics."""
end_time = time.time()
- duration_ms = (end_time - start_time) * 1000
- # Create proper scope object for common_framework_span_attributes
- scope = type("GenericScope", (), {})()
+ # -- common framework attributes (provider, model, server, duration …) --
+ scope = type("Scope", (), {})()
scope._span = span
scope._start_time = start_time
scope._end_time = end_time
- # Get standard operation name from mapping
- standard_operation = OPERATION_MAP.get(endpoint, "invoke_agent")
-
- # Extract model information from agent's LLM for proper attribution
- request_model = "unknown"
- if instance:
- llm = getattr(instance, "llm", None)
- if llm:
- # Try different model attribute names used by different LLM libraries
- request_model = (
- getattr(llm, "model_name", None)
- or getattr(llm, "model", None)
- or getattr(llm, "_model_name", None)
- or "unknown"
- )
- if request_model != "unknown":
- request_model = str(request_model)
-
- # Create a wrapper instance that exposes model_name for common_framework_span_attributes
- class ModelWrapper:
- """Wrapper class to expose model_name for framework span attributes."""
+ request_model = _extract_model_name(instance)
- def __init__(self, original_instance, model_name):
- self._original = original_instance
- self.model_name = model_name
+ class _ModelProxy: # pylint: disable=too-few-public-methods
+ def __init__(self, orig, model):
+ self._original = orig
+ self.model_name = model
def __getattr__(self, name):
return getattr(self._original, name)
- def get_original_instance(self):
- """Get the original wrapped instance."""
- return self._original
-
- model_instance = ModelWrapper(instance, request_model) if instance else None
+ proxy = _ModelProxy(instance, request_model) if instance else None
- # Set common framework span attributes
common_framework_span_attributes(
scope,
SemanticConvention.GEN_AI_SYSTEM_CREWAI,
@@ -148,464 +236,408 @@ def process_crewai_response(
application_name,
version,
endpoint,
- model_instance,
+ proxy,
)
- # Set span name following OpenTelemetry format
- _set_span_name(span, standard_operation, instance, endpoint, args, kwargs)
-
- # === CORE SEMANTIC ATTRIBUTES ===
+ # Override raw endpoint with standard OTel operation name
+ standard_operation = OPERATION_MAP.get(endpoint, "invoke_agent")
span.set_attribute(SemanticConvention.GEN_AI_OPERATION, standard_operation)
- # Remove gen_ai.endpoint as requested
-
- # === STANDARD BUSINESS INTELLIGENCE ===
- # Only use standard OpenTelemetry attributes, no framework-specific ones
- _set_agent_business_intelligence(span, instance, endpoint, args, kwargs)
- _set_tool_business_intelligence(span, instance, endpoint, args, kwargs)
- _set_task_business_intelligence(span, instance, endpoint, args, kwargs)
- _set_crew_business_intelligence(span, instance, endpoint, args, kwargs)
- # Remove framework-specific functions: _set_workflow_business_intelligence, _set_memory_business_intelligence
- # === PERFORMANCE INTELLIGENCE ===
- # Use standard OpenTelemetry duration attribute through common_framework_span_attributes
+ # -- entity-specific attributes --
+ _set_crew_attributes(span, instance, endpoint)
+ _set_agent_attributes(span, instance, endpoint, capture_message_content)
+ _set_task_attributes(span, instance, endpoint, capture_message_content)
+ _set_tool_attributes(
+ span, instance, endpoint, capture_message_content, args, kwargs, response
+ )
+ _set_flow_attributes(span, instance, endpoint)
- # === CONTENT CAPTURE ===
+ # -- content capture as span attributes (JSON), not legacy span events --
if capture_message_content:
- _capture_content(span, instance, response, endpoint)
+ _capture_content_as_attributes(span, instance, response, endpoint)
- # === COST TRACKING ===
- _track_cost_and_tokens(span, instance, response, endpoint)
+ # -- output type --
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_TYPE,
+ SemanticConvention.GEN_AI_OUTPUT_TYPE_TEXT,
+ )
- # === RECORD METRICS ===
+ # -- metrics --
if not disable_metrics and metrics:
_record_crewai_metrics(
- metrics, standard_operation, duration_ms, environment, application_name
+ metrics,
+ standard_operation,
+ end_time - start_time,
+ environment,
+ application_name,
+ request_model,
+ server_address,
+ server_port,
)
span.set_status(Status(StatusCode.OK))
return response
-def _set_span_name(span, operation_type, instance, endpoint, args, kwargs):
- """Set span name following OpenTelemetry format: '{operation_type} {name}'"""
- try:
- # Get the operation name from our mapping
- operation_name = OPERATION_MAP.get(endpoint, "invoke_agent")
-
- if endpoint.startswith("crew_"):
- # Crew operations: "invoke_agent {crew_name}"
- crew_name = getattr(instance, "name", None) or "crew"
- span.update_name(f"{operation_name} {crew_name}")
-
- elif endpoint.startswith("agent_"):
- if "create" in endpoint or endpoint == "agent___init__":
- # Agent creation: "create_agent {agent_name}"
- agent_name = getattr(instance, "name", None) or getattr(
- instance, "role", "agent"
- )
- span.update_name(f"create_agent {agent_name}")
- else:
- # Agent invocation: "invoke_agent {agent_name}"
- agent_name = getattr(instance, "name", None) or getattr(
- instance, "role", "agent"
- )
- span.update_name(f"invoke_agent {agent_name}")
-
- elif endpoint.startswith("task_"):
- # Task operations: "invoke_agent task"
- span.update_name("invoke_agent task")
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+def _extract_model_name(instance):
+ """Walk the instance hierarchy to find the LLM model name."""
+ if not instance:
+ return "unknown"
+
+ llm = getattr(instance, "llm", None)
+ if not llm:
+ agent = getattr(instance, "agent", None)
+ if agent:
+ llm = getattr(agent, "llm", None)
+
+ # Crew instances: walk agents list to find first agent's LLM
+ if not llm:
+ agents = getattr(instance, "agents", None)
+ if agents:
+ for ag in agents:
+ llm = getattr(ag, "llm", None)
+ if llm:
+ break
+
+ # Tool instances: inherit from parent agent via contextvar
+ if not llm:
+ model_info = _current_agent_model_info.get()
+ if model_info:
+ return model_info[0]
+
+ if llm:
+ name = (
+ getattr(llm, "model_name", None)
+ or getattr(llm, "model", None)
+ or getattr(llm, "_model_name", None)
+ )
+ if name:
+ return str(name)
+ return "unknown"
- elif endpoint.startswith("tool_"):
- # Tool operations: "execute_tool {tool_name}"
- tool_name = (
- getattr(instance, "name", None)
- or getattr(instance, "__class__", type(instance)).__name__
- )
- span.update_name(f"execute_tool {tool_name}")
- elif endpoint.startswith("memory_"):
- # Memory operations: "invoke_agent memory:{operation}"
- memory_op = endpoint.split("_", 1)[1] if "_" in endpoint else "operation"
- span.update_name(f"invoke_agent memory:{memory_op}")
+def _set_crew_attributes(span, instance, endpoint):
+ """Workflow attributes for Crew operations (OTel gen-ai-agent-spans)."""
+ if not endpoint.startswith("crew_"):
+ return
+ try:
+ crew_name = getattr(instance, "name", None) or "CrewAI"
+ span.set_attribute(SemanticConvention.GEN_AI_WORKFLOW_NAME, crew_name)
- else:
- # Default fallback
- span.update_name(f"{operation_name} {endpoint}")
+ process = getattr(instance, "process", None)
+ if process:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_EXECUTION_MODE,
+ getattr(process, "value", str(process)),
+ )
- except Exception as e:
- handle_exception(span, e)
- # Fallback naming
- span.update_name(f"invoke_agent {endpoint}")
+ agents = getattr(instance, "agents", None) or []
+ if agents:
+ agent_defs = []
+ for agent in agents[:10]:
+ entry = {}
+ role = getattr(agent, "role", None)
+ if role:
+ entry["role"] = str(role)
+ goal = getattr(agent, "goal", None)
+ if goal:
+ entry["goal"] = str(goal)
+ tools = getattr(agent, "tools", None) or []
+ if tools:
+ entry["tools"] = [
+ getattr(t, "name", type(t).__name__) for t in tools[:5]
+ ]
+ if entry:
+ agent_defs.append(entry)
+ if agent_defs:
+ span.set_attribute("gen_ai.crewai.crew.agents", json.dumps(agent_defs))
+
+ tasks = getattr(instance, "tasks", None) or []
+ if tasks:
+ span.set_attribute("gen_ai.crewai.crew.task_count", len(tasks))
+ except Exception:
+ pass
-def _set_agent_business_intelligence(span, instance, endpoint, args, kwargs):
- """Set agent business intelligence using standard OpenTelemetry semantic conventions"""
+def _set_agent_attributes(span, instance, endpoint, capture_message_content):
+ """Agent attributes per OTel GenAI semantic conventions."""
if not endpoint.startswith("agent_"):
return
-
try:
- # Standard OpenTelemetry Gen AI Agent attributes
- agent_id = getattr(instance, "id", "")
+ agent_id = getattr(instance, "id", None)
if agent_id:
span.set_attribute(SemanticConvention.GEN_AI_AGENT_ID, str(agent_id))
- agent_name = getattr(instance, "name", None) or getattr(instance, "role", "")
+ agent_name = getattr(instance, "role", None) or getattr(instance, "name", None)
if agent_name:
- span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, agent_name)
-
- # Agent description - use role + goal as description per OpenTelemetry spec
- agent_role = getattr(instance, "role", "")
- agent_goal = getattr(instance, "goal", "")
- if agent_role and agent_goal:
- description = f"{agent_role}: {agent_goal}"
- span.set_attribute(SemanticConvention.GEN_AI_AGENT_DESCRIPTION, description)
- elif agent_goal:
- span.set_attribute(SemanticConvention.GEN_AI_AGENT_DESCRIPTION, agent_goal)
-
- # Enhanced Agent Configuration Tracking using SemanticConvention
- max_retry_limit = getattr(instance, "max_retry_limit", None)
- if max_retry_limit is not None:
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_MAX_RETRY_LIMIT, max_retry_limit
- )
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(agent_name))
- allow_delegation = getattr(instance, "allow_delegation", None)
- if allow_delegation is not None:
+ role = getattr(instance, "role", "")
+ goal = getattr(instance, "goal", "")
+ if role and goal:
span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_ALLOW_DELEGATION, allow_delegation
+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION, f"{role}: {goal}"
)
+ elif goal:
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_DESCRIPTION, str(goal))
- allow_code_execution = getattr(instance, "allow_code_execution", None)
- if allow_code_execution is not None:
+ backstory = getattr(instance, "backstory", None)
+ if backstory and capture_message_content:
span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_ALLOW_CODE_EXECUTION,
- allow_code_execution,
+ SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS,
+ truncate_content(str(backstory)),
)
- # Tools tracking using SemanticConvention
- tools = getattr(instance, "tools", [])
- if tools:
- tool_names = [
- getattr(tool, "name", str(tool)) for tool in tools[:5]
- ] # Limit to first 5
- if tool_names:
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_TOOLS, ", ".join(tool_names)
- )
-
- # === OpenAI Agent-specific Attributes ===
- _set_openai_agent_attributes(span, instance, endpoint, args, kwargs)
-
- # === Conversation and Data Source Tracking ===
- _set_conversation_and_data_source_attributes(
- span, instance, endpoint, args, kwargs
- )
-
- except Exception as e:
- handle_exception(span, e)
+ _set_tool_definitions(span, getattr(instance, "tools", None) or [])
+ except Exception:
+ pass
-def _set_openai_agent_attributes(span, instance, endpoint, args, kwargs):
- """Set OpenAI-specific agent attributes when using OpenAI models"""
+def _set_task_attributes(span, instance, endpoint, capture_message_content):
+ """Attributes for task execution (invoke_agent spans)."""
+ if endpoint != "task_execute_core":
+ return
try:
- # Check if agent is using OpenAI LLM
- llm = getattr(instance, "llm", None)
- if llm:
- llm_class = llm.__class__.__name__.lower()
- llm_model = getattr(llm, "model_name", getattr(llm, "model", ""))
-
- # Set model information
- if llm_model:
- span.set_attribute(SemanticConvention.GEN_AI_REQUEST_MODEL, llm_model)
-
- # OpenAI-specific attributes (but keep gen_ai.system as crewai)
- if "openai" in llm_class or "gpt" in str(llm_model).lower():
- # OpenAI service tier if available
- service_tier = getattr(llm, "service_tier", None)
- if service_tier:
- span.set_attribute(
- SemanticConvention.GEN_AI_OPENAI_REQUEST_SERVICE_TIER,
- service_tier,
- )
-
- # OpenAI Assistant API attributes if available
- assistant_id = getattr(instance, "assistant_id", None) or kwargs.get(
- "assistant_id"
+ agent = getattr(instance, "agent", None)
+ if agent:
+ agent_name = getattr(agent, "role", None) or getattr(agent, "name", None)
+ if agent_name:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_AGENT_NAME, str(agent_name)
)
- if assistant_id:
- span.set_attribute(
- SemanticConvention.GEN_AI_OPENAI_ASSISTANT_ID, assistant_id
- )
+ agent_id = getattr(agent, "id", None)
+ if agent_id:
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_ID, str(agent_id))
- thread_id = getattr(instance, "thread_id", None) or kwargs.get(
- "thread_id"
+ role = getattr(agent, "role", "")
+ goal = getattr(agent, "goal", "")
+ if role and goal:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION,
+ f"{role}: {goal}",
)
- if thread_id:
- span.set_attribute(
- SemanticConvention.GEN_AI_OPENAI_THREAD_ID, thread_id
- )
-
- run_id = getattr(instance, "run_id", None) or kwargs.get("run_id")
- if run_id:
- span.set_attribute(SemanticConvention.GEN_AI_OPENAI_RUN_ID, run_id)
-
- # LiteLLM detection (but keep gen_ai.system as crewai)
- elif "litellm" in llm_class:
- # Could add LiteLLM-specific attributes here if needed
- pass
-
- except Exception as e:
- handle_exception(span, e)
-
-
-def _set_conversation_and_data_source_attributes(
- span, instance, endpoint, args, kwargs
-):
- """Set conversation tracking and data source attributes"""
- try:
- # Conversation ID for multi-turn interactions
- conversation_id = (
- getattr(instance, "conversation_id", None)
- or getattr(instance, "session_id", None)
- or kwargs.get("conversation_id")
- or kwargs.get("session_id")
- )
- if conversation_id:
- span.set_attribute(
- SemanticConvention.GEN_AI_CONVERSATION_ID, str(conversation_id)
- )
-
- # Data source tracking for RAG operations
- memory = getattr(instance, "memory", None)
- if memory:
- # Memory as data source
- memory_provider = getattr(memory, "provider", None)
- if memory_provider:
- span.set_attribute(SemanticConvention.GEN_AI_DATA_SOURCE_TYPE, "memory")
+ elif goal:
span.set_attribute(
- SemanticConvention.GEN_AI_DATA_SOURCE_ID, str(memory_provider)
+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION, str(goal)
)
- # Knowledge base or vector store detection
- knowledge_source = getattr(instance, "knowledge_source", None)
- if knowledge_source:
- span.set_attribute(
- SemanticConvention.GEN_AI_DATA_SOURCE_TYPE, "knowledge_base"
- )
- span.set_attribute(
- SemanticConvention.GEN_AI_DATA_SOURCE_ID, str(knowledge_source)
- )
-
- # Tool-based data sources
- tools = getattr(instance, "tools", [])
- for tool in tools:
- tool_name = getattr(tool, "name", "").lower()
- if any(
- keyword in tool_name
- for keyword in ["search", "retrieval", "database", "vector"]
- ):
+ backstory = getattr(agent, "backstory", None)
+ if backstory and capture_message_content:
span.set_attribute(
- SemanticConvention.GEN_AI_DATA_SOURCE_TYPE, "external_tool"
+ SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS,
+ truncate_content(str(backstory)),
)
- break
- except Exception as e:
- handle_exception(span, e)
+ _set_tool_definitions(span, getattr(agent, "tools", None) or [])
+ except Exception:
+ pass
-def _set_task_business_intelligence(span, instance, endpoint, args, kwargs):
- """Set task business intelligence using standard OpenTelemetry semantic conventions"""
- if not endpoint.startswith("task_"):
+def _set_tool_attributes(
+ span, instance, endpoint, capture_message_content, args, kwargs, response
+):
+ """Tool attributes per OTel GenAI semantic conventions."""
+ if endpoint != "tool_run":
return
-
try:
- # Task ID tracking
- task_id = getattr(instance, "id", None)
- if task_id:
- span.set_attribute(SemanticConvention.GEN_AI_AGENT_TASK_ID, str(task_id))
-
- # Task description
- task_description = getattr(instance, "description", "")
- if task_description:
- span.set_attribute(
- SemanticConvention.GEN_AI_TASK_DESCRIPTION, task_description
- )
+ tool_name = getattr(instance, "name", None) or type(instance).__name__
+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_NAME, str(tool_name))
+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_TYPE, "function")
- # Task expected output (keep only essential attributes that have semantic conventions or are critical)
- expected_output = getattr(instance, "expected_output", "")
- if expected_output:
+ tool_desc = getattr(instance, "description", None)
+ if tool_desc:
span.set_attribute(
- SemanticConvention.GEN_AI_TASK_EXPECTED_OUTPUT, expected_output
+ SemanticConvention.GEN_AI_TOOL_DESCRIPTION,
+ truncate_content(str(tool_desc)),
)
- except Exception as e:
- handle_exception(span, e)
+ if capture_message_content:
+ tool_input = None
+ if args:
+ try:
+ tool_input = (
+ json.dumps(args[0]) if len(args) == 1 else json.dumps(args)
+ )
+ except (TypeError, ValueError):
+ tool_input = str(args)
+ elif kwargs:
+ try:
+ tool_input = json.dumps(kwargs)
+ except (TypeError, ValueError):
+ tool_input = str(kwargs)
+ if tool_input:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS,
+ truncate_content(tool_input),
+ )
+ if response is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_RESULT,
+ truncate_content(str(response)),
+ )
+ except Exception:
+ pass
-def _set_crew_business_intelligence(span, instance, endpoint, args, kwargs):
- """Set crew business intelligence using standard OpenTelemetry semantic conventions"""
- if not endpoint.startswith("crew_"):
+def _set_flow_attributes(span, instance, endpoint):
+ """Workflow / agent attributes for Flow operations."""
+ if not endpoint.startswith("flow_"):
return
-
try:
- # Only capture essential crew attributes - remove custom ones that don't have semantic conventions
+ if endpoint in ("flow_kickoff", "flow_kickoff_async"):
+ flow_name = getattr(instance, "name", None) or type(instance).__name__
+ span.set_attribute(SemanticConvention.GEN_AI_WORKFLOW_NAME, str(flow_name))
+ if endpoint == "flow_execute_method":
+ node_name = getattr(instance, "_current_method_name", None)
+ if node_name:
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(node_name))
+ except Exception:
pass
- except Exception as e:
- handle_exception(span, e)
-
-def _set_tool_business_intelligence(span, instance, endpoint, args, kwargs):
- """Set tool business intelligence using standard OpenTelemetry semantic conventions"""
- if not endpoint.startswith("tool_"):
+def _set_tool_definitions(span, tools):
+ """Set gen_ai.tool.definitions from a list of CrewAI tool instances."""
+ if not tools:
return
-
- try:
- # Standard OpenTelemetry Gen AI Tool attributes
- tool_name = (
- getattr(instance, "name", None)
- or getattr(instance, "__class__", type(instance)).__name__
+ tool_defs = []
+ for tool in tools[:10]:
+ entry = {"type": "function"}
+ name = getattr(tool, "name", None)
+ if name:
+ entry["name"] = str(name)
+ desc = getattr(tool, "description", None)
+ if desc:
+ entry["description"] = truncate_content(str(desc))
+ if len(entry) > 1:
+ tool_defs.append(entry)
+ if tool_defs:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_DEFINITIONS, json.dumps(tool_defs)
)
- if tool_name:
- span.set_attribute(SemanticConvention.GEN_AI_TOOL_NAME, tool_name)
- # Tool call ID if available (for tracking specific tool invocations)
- tool_call_id = kwargs.get("call_id", None) or getattr(instance, "call_id", None)
- if tool_call_id:
- span.set_attribute(
- SemanticConvention.GEN_AI_TOOL_CALL_ID, str(tool_call_id)
- )
- # === OpenAI Function Calling Attributes ===
- _set_openai_tool_attributes(span, instance, endpoint, args, kwargs)
+def _capture_content_as_attributes(span, instance, response, endpoint):
+ """Record input/output as span attributes (JSON), not legacy span events."""
+ try:
+ if endpoint == "task_execute_core":
+ desc = getattr(instance, "description", None)
+ if desc:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_INPUT_MESSAGES,
+ json.dumps(
+ [{"role": "user", "content": truncate_content(str(desc))}]
+ ),
+ )
- except Exception as e:
- handle_exception(span, e)
+ if response is not None:
+ output = truncate_content(str(response))
+ if output:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_MESSAGES,
+ json.dumps([{"role": "assistant", "content": output}]),
+ )
+ except Exception:
+ pass
-def _set_openai_tool_attributes(span, instance, endpoint, args, kwargs):
- """Set OpenAI function calling specific attributes using standard conventions"""
- try:
- # Standard tool type classification (framework-agnostic)
- tool_class = instance.__class__.__name__.lower()
- if any(keyword in tool_class for keyword in ["search", "web", "browser"]):
- tool_type = "search"
- elif any(keyword in tool_class for keyword in ["file", "read", "write"]):
- tool_type = "file_system"
- elif any(keyword in tool_class for keyword in ["api", "http", "request"]):
- tool_type = "api_client"
- elif any(keyword in tool_class for keyword in ["database", "sql", "query"]):
- tool_type = "database"
- elif any(
- keyword in tool_class for keyword in ["vector", "embedding", "retrieval"]
- ):
- tool_type = "vector_store"
- else:
- tool_type = "custom"
-
- # Use standard tool type attribute from semcov
- span.set_attribute(SemanticConvention.GEN_AI_TOOL_TYPE, tool_type)
-
- except Exception as e:
- handle_exception(span, e)
-
-
-def _capture_content(span, instance, response, endpoint):
- """Capture input/output content with MIME types"""
+def emit_create_agent_spans(
+ tracer,
+ instance,
+ version,
+ environment,
+ application_name,
+ capture_message_content,
+):
+ """Emit a ``create_agent`` span per agent defined on a Crew instance.
- try:
- # Capture response content
- if response:
- span.add_event(
- name=SemanticConvention.GEN_AI_CONTENT_COMPLETION_EVENT,
- attributes={
- SemanticConvention.GEN_AI_OUTPUT_MESSAGES: str(response)[
- :1000
- ], # Limit size
- },
+ Returns a list of SpanContexts that the caller should store on
+ ``instance._openlit_creation_contexts`` so the ``invoke_workflow``
+ span created by ``Crew.kickoff`` can link back to them.
+ """
+ agents = getattr(instance, "agents", None) or []
+ if not agents:
+ return []
+
+ creation_contexts = []
+ for agent in agents:
+ role = getattr(agent, "role", None) or "agent"
+ span_name = f"create_agent {role}"
+ with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OPERATION,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,
)
+ span.set_attribute(
+ SemanticConvention.GEN_AI_PROVIDER_NAME,
+ SemanticConvention.GEN_AI_SYSTEM_CREWAI,
+ )
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(role))
- # Capture input content based on operation type
- if endpoint.startswith("task_"):
- task_description = getattr(instance, "description", "")
- if task_description:
- span.add_event(
- name=SemanticConvention.GEN_AI_CONTENT_PROMPT_EVENT,
- attributes={
- SemanticConvention.GEN_AI_INPUT_MESSAGES: task_description[
- :1000
- ],
- },
- )
+ agent_id = getattr(agent, "id", None)
+ if agent_id:
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_ID, str(agent_id))
- except Exception:
- # Graceful degradation
- pass
+ goal = getattr(agent, "goal", "")
+ if role and goal:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION,
+ f"{role}: {goal}",
+ )
+ elif goal:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION, str(goal)
+ )
+ backstory = getattr(agent, "backstory", None)
+ if backstory and capture_message_content:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS,
+ truncate_content(str(backstory)),
+ )
-def _track_cost_and_tokens(span, instance, response, endpoint):
- """Track cost and token usage for business intelligence"""
+ _set_tool_definitions(span, getattr(agent, "tools", None) or [])
- try:
- # Token tracking from LLM calls
- if hasattr(instance, "llm") and hasattr(instance.llm, "get_num_tokens"):
- # This would be framework-specific implementation
- pass
-
- # Response length as a proxy metric and token estimation
- if response:
- response_length = len(str(response))
- # Estimate token count (rough approximation: 4 chars per token)
- estimated_tokens = response_length // 4
+ span.set_attribute(SemanticConvention.GEN_AI_ENVIRONMENT, environment)
span.set_attribute(
- SemanticConvention.GEN_AI_CLIENT_TOKEN_USAGE, estimated_tokens
+ SemanticConvention.GEN_AI_APPLICATION_NAME, application_name
)
+ span.set_attribute(SemanticConvention.GEN_AI_SDK_VERSION, version)
+ span.set_status(Status(StatusCode.OK))
- # Cost estimation would require pricing information
- # This could be enhanced with actual cost tracking
+ creation_contexts.append(span.get_span_context())
- except Exception:
- # Graceful degradation
- pass
+ return creation_contexts
def _record_crewai_metrics(
- metrics, operation_type, duration_ms, environment, application_name
+ metrics,
+ operation_type,
+ duration,
+ environment,
+ application_name,
+ request_model,
+ server_address,
+ server_port,
):
- """Record CrewAI-specific metrics"""
-
+ """Record OTel-compliant metrics with correct attribute keys."""
try:
attributes = {
- "gen_ai.operation.name": operation_type,
- "gen_ai.system": SemanticConvention.GEN_AI_SYSTEM_CREWAI,
+ SemanticConvention.GEN_AI_OPERATION: operation_type,
+ SemanticConvention.GEN_AI_PROVIDER_NAME: SemanticConvention.GEN_AI_SYSTEM_CREWAI,
"service.name": application_name,
"deployment.environment": environment,
}
+ if request_model and request_model != "unknown":
+ attributes[SemanticConvention.GEN_AI_REQUEST_MODEL] = request_model
+ if server_address:
+ attributes[SemanticConvention.SERVER_ADDRESS] = server_address
+ if server_port:
+ attributes[SemanticConvention.SERVER_PORT] = server_port
- # Record operation duration
if "genai_client_operation_duration" in metrics:
- metrics["genai_client_operation_duration"].record(
- duration_ms / 1000, attributes
- )
-
+ metrics["genai_client_operation_duration"].record(duration, attributes)
except Exception:
- # Graceful degradation
pass
-
-
-def _parse_tools(tools):
- """Parse tools list into JSON format"""
-
- try:
- result = []
- for tool in tools:
- tool_info = {}
- if hasattr(tool, "name") and tool.name is not None:
- tool_info["name"] = tool.name
- if hasattr(tool, "description") and tool.description is not None:
- tool_info["description"] = tool.description
- if tool_info:
- result.append(tool_info)
- return json.dumps(result)
- except Exception:
- return "[]"
diff --git a/sdk/python/src/openlit/instrumentation/google_adk/__init__.py b/sdk/python/src/openlit/instrumentation/google_adk/__init__.py
new file mode 100644
index 00000000..27cf244c
--- /dev/null
+++ b/sdk/python/src/openlit/instrumentation/google_adk/__init__.py
@@ -0,0 +1,510 @@
+"""
+OpenLIT Google ADK Instrumentation — OTel GenAI semantic convention compliant.
+
+Provides auto-instrumentation for Google ADK (Agent Development Kit) including:
+- Agent construction (LlmAgent.__init__ -> create_agent spans)
+- Runner execution (Runner.run_async, Runner.run -> invoke_agent spans)
+- Agent execution (BaseAgent.run_async -> invoke_agent spans)
+- LLM call enrichment (trace_call_llm -> OTel semconv attributes on ADK spans)
+- Tool call enrichment (trace_tool_call -> OTel semconv attributes on ADK spans)
+
+Uses a selective _PassthroughTracer strategy:
+- Replaces ADK's runners.tracer and base_agent.tracer to suppress their spans
+ (OpenLIT creates invoke_agent spans instead).
+- Leaves ADK's telemetry.tracing.tracer intact so call_llm, generate_content,
+ and execute_tool spans remain as children, enriched with OTel attributes via
+ decorator-style wrappers on ADK's trace_call_llm / trace_tool_call functions.
+"""
+
+import json
+import threading
+from typing import Collection
+import importlib.metadata
+
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from opentelemetry.trace import SpanKind, Status, StatusCode
+from wrapt import wrap_function_wrapper
+
+from openlit.__helpers import handle_exception, truncate_content
+from openlit.semcov import SemanticConvention
+from openlit.instrumentation.google_adk.utils import (
+ _PassthroughTracer,
+ _resolve_model_string,
+ enrich_llm_span,
+ enrich_tool_span,
+ enrich_merged_tool_span,
+)
+
+_instruments = ("google-adk >= 1.2.0",)
+
+# Always-on wrapping operations
+# (module, method, endpoint_key, sync_type)
+WORKFLOW_OPERATIONS = [
+ ("google.adk.agents.llm_agent", "LlmAgent.__init__", "agent_init", "sync"),
+ ("google.adk.runners", "Runner.run_async", "runner_run_async", "async"),
+ ("google.adk.runners", "Runner.run", "runner_run", "sync"),
+ ("google.adk.agents.base_agent", "BaseAgent.run_async", "agent_run_async", "async"),
+]
+
+DETAILED_OPERATIONS = [
+ ("google.adk.runners", "Runner.run_live", "runner_run_live", "async"),
+]
+
+
+class _AgentCreationRegistry:
+ """Thread-safe registry mapping agent name -> SpanContext from create_agent spans.
+
+ Used to provide span links from invoke_agent / invoke_workflow
+ back to create_agent, matching the pattern used in CrewAI and
+ OpenAI Agents instrumentations.
+ """
+
+ def __init__(self):
+ self._lock = threading.Lock()
+ self._contexts: dict = {}
+
+ def register(self, agent_name, span_context):
+ """Store the span context for a given agent name."""
+ with self._lock:
+ self._contexts[agent_name] = span_context
+
+ def get(self, agent_name):
+ """Retrieve the span context for a given agent name, or ``None``."""
+ with self._lock:
+ return self._contexts.get(agent_name)
+
+ def get_all(self):
+ """Return all registered span contexts."""
+ with self._lock:
+ return list(self._contexts.values())
+
+
+def _wrap_agent_init(
+ tracer, environment, application_name, capture_message_content, registry
+):
+ """Return a wrapt wrapper for ``LlmAgent.__init__`` that emits a
+ ``create_agent`` span per agent construction."""
+
+ def wrapper(wrapped, instance, args, kwargs):
+ result = wrapped(*args, **kwargs)
+
+ try:
+ name = getattr(instance, "name", None) or "agent"
+ span_name = f"create_agent {name}"
+
+ with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OPERATION,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,
+ )
+ span.set_attribute(
+ SemanticConvention.GEN_AI_PROVIDER_NAME,
+ SemanticConvention.GEN_AI_SYSTEM_GOOGLE_ADK,
+ )
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(name))
+
+ description = getattr(instance, "description", None)
+ if description:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION,
+ str(description),
+ )
+
+ model = getattr(instance, "model", None)
+ if model:
+ model_str = _resolve_model_string(model) or str(model)
+ span.set_attribute(
+ SemanticConvention.GEN_AI_REQUEST_MODEL, model_str
+ )
+
+ instruction = getattr(instance, "instruction", None)
+ if instruction and capture_message_content:
+ instr_str = str(instruction)
+ span.set_attribute(
+ SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS,
+ json.dumps(
+ [
+ {
+ "type": "text",
+ "content": truncate_content(instr_str),
+ }
+ ]
+ ),
+ )
+
+ tools = getattr(instance, "tools", None)
+ if tools:
+ tool_defs = []
+ for t in tools[:20]:
+ t_name = (
+ getattr(t, "name", None)
+ or getattr(t, "__name__", None)
+ or type(t).__name__
+ )
+ entry = {"type": "function", "name": str(t_name)}
+ t_desc = getattr(t, "description", None) or getattr(
+ t, "__doc__", None
+ )
+ if t_desc:
+ entry["description"] = truncate_content(str(t_desc))
+ tool_defs.append(entry)
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_DEFINITIONS,
+ json.dumps(tool_defs),
+ )
+
+ sub_agents = getattr(instance, "sub_agents", None)
+ if sub_agents:
+ handoff_names = [
+ str(getattr(sa, "name", "unknown")) for sa in sub_agents[:20]
+ ]
+ span.set_attribute(
+ "gen_ai.agent.handoffs", json.dumps(handoff_names)
+ )
+
+ span.set_attribute(SemanticConvention.GEN_AI_ENVIRONMENT, environment)
+ span.set_attribute(
+ SemanticConvention.GEN_AI_APPLICATION_NAME, application_name
+ )
+ span.set_status(Status(StatusCode.OK))
+
+ creation_ctx = span.get_span_context()
+ instance._openlit_creation_context = creation_ctx
+ registry.register(str(name), creation_ctx)
+ except Exception as e:
+ handle_exception(span, e)
+
+ return result
+
+ return wrapper
+
+
+def _disable_existing_tracers():
+ """Replace ADK's internal tracers with ``_PassthroughTracer`` to suppress
+ duplicate spans for operations that OpenLIT controls.
+
+ Returns a dict of original tracers for restoration in ``_uninstrument()``.
+ """
+ originals = {}
+
+ try:
+ import google.adk.runners as runners_mod
+
+ originals["runners.tracer"] = getattr(runners_mod, "tracer", None)
+ if originals["runners.tracer"] is not None:
+ runners_mod.tracer = _PassthroughTracer(originals["runners.tracer"])
+ except Exception:
+ pass
+
+ try:
+ import google.adk.agents.base_agent as base_agent_mod
+
+ originals["base_agent.tracer"] = getattr(base_agent_mod, "tracer", None)
+ if originals["base_agent.tracer"] is not None:
+ base_agent_mod.tracer = _PassthroughTracer(originals["base_agent.tracer"])
+ except Exception:
+ pass
+
+ return originals
+
+
+def _wrap_trace_call_llm(capture_message_content):
+ """Create and install a decorator wrapper around ADK's ``trace_call_llm``
+ that enriches the current span with OTel GenAI semconv attributes.
+
+ Returns the original function for restoration.
+ """
+ original = None
+ try:
+ import google.adk.flows.llm_flows.base_llm_flow as blf_mod
+
+ original_fn = getattr(blf_mod, "trace_call_llm", None)
+ if original_fn is None:
+ return None
+
+ original = original_fn
+
+ def enriched_trace_call_llm(*args, **kwargs):
+ # ADK signature: trace_call_llm(invocation_context, event_id, llm_request, llm_response, span=None)
+ result = original_fn(*args, **kwargs)
+ try:
+ from opentelemetry import trace as trace_api
+
+ span = trace_api.get_current_span()
+ llm_request = args[2] if len(args) > 2 else kwargs.get("llm_request")
+ llm_response = args[3] if len(args) > 3 else kwargs.get("llm_response")
+ enrich_llm_span(
+ span, llm_request, llm_response, capture_message_content
+ )
+ except Exception:
+ pass
+ return result
+
+ blf_mod.trace_call_llm = enriched_trace_call_llm
+ except Exception:
+ pass
+
+ return original
+
+
+def _wrap_trace_tool_call(capture_message_content):
+ """Create and install a decorator wrapper around ADK's ``trace_tool_call``
+ that enriches the current span with OTel GenAI semconv attributes.
+
+ Returns the original function for restoration.
+ """
+ original = None
+ try:
+ import google.adk.flows.llm_flows.functions as functions_mod
+
+ original_fn = getattr(functions_mod, "trace_tool_call", None)
+ if original_fn is None:
+ return None
+
+ original = original_fn
+
+ def enriched_trace_tool_call(*args, **kwargs):
+ # ADK signature: trace_tool_call(tool, args, function_response_event, error=None)
+ result = original_fn(*args, **kwargs)
+ try:
+ from opentelemetry import trace as trace_api
+
+ span = trace_api.get_current_span()
+ tool = args[0] if len(args) > 0 else kwargs.get("tool")
+ function_args = args[1] if len(args) > 1 else kwargs.get("args")
+ function_response_event = (
+ args[2] if len(args) > 2 else kwargs.get("function_response_event")
+ )
+ tool_error = args[3] if len(args) > 3 else kwargs.get("error")
+ enrich_tool_span(
+ span,
+ tool,
+ function_args,
+ function_response_event,
+ capture_message_content,
+ error=tool_error,
+ )
+ except Exception:
+ pass
+ return result
+
+ functions_mod.trace_tool_call = enriched_trace_tool_call
+ except Exception:
+ pass
+
+ return original
+
+
+def _wrap_trace_merged_tool_calls(capture_message_content):
+ """Create and install a decorator wrapper around ADK's ``trace_merged_tool_calls``
+ that enriches the current span with OTel GenAI semconv attributes.
+
+ Returns the original function for restoration.
+ """
+ original = None
+ try:
+ import google.adk.flows.llm_flows.functions as functions_mod
+
+ original_fn = getattr(functions_mod, "trace_merged_tool_calls", None)
+ if original_fn is None:
+ return None
+
+ original = original_fn
+
+ def enriched_trace_merged(*args, **kwargs):
+ # ADK signature: trace_merged_tool_calls(response_event_id, function_response_event)
+ result = original_fn(*args, **kwargs)
+ try:
+ from opentelemetry import trace as trace_api
+
+ span = trace_api.get_current_span()
+ response_event_id = (
+ args[0] if len(args) > 0 else kwargs.get("response_event_id")
+ )
+ function_response_event = (
+ args[1] if len(args) > 1 else kwargs.get("function_response_event")
+ )
+ enrich_merged_tool_span(
+ span,
+ response_event_id,
+ function_response_event,
+ capture_message_content,
+ )
+ except Exception:
+ pass
+ return result
+
+ functions_mod.trace_merged_tool_calls = enriched_trace_merged
+ except Exception:
+ pass
+
+ return original
+
+
+class GoogleADKInstrumentor(BaseInstrumentor):
+ """OTel GenAI semantic convention compliant instrumentor for Google ADK."""
+
+ def __init__(self):
+ super().__init__()
+ self._original_tracers: dict = {}
+ self._original_trace_call_llm = None
+ self._original_trace_tool_call = None
+ self._original_trace_merged = None
+
+ def instrumentation_dependencies(self) -> Collection[str]:
+ return _instruments
+
+ def _instrument(self, **kwargs):
+ version = importlib.metadata.version("google-adk")
+ environment = kwargs.get("environment", "default")
+ application_name = kwargs.get("application_name", "default")
+ tracer = kwargs.get("tracer")
+ pricing_info = kwargs.get("pricing_info", {})
+ capture_message_content = kwargs.get("capture_message_content", False)
+ metrics = kwargs.get("metrics_dict")
+ disable_metrics = kwargs.get("disable_metrics")
+ detailed_tracing = kwargs.get("detailed_tracing", False)
+
+ agent_registry = _AgentCreationRegistry()
+
+ self._original_tracers = _disable_existing_tracers()
+
+ self._original_trace_call_llm = _wrap_trace_call_llm(capture_message_content)
+ self._original_trace_tool_call = _wrap_trace_tool_call(capture_message_content)
+ self._original_trace_merged = _wrap_trace_merged_tool_calls(
+ capture_message_content
+ )
+
+ from openlit.instrumentation.google_adk.async_google_adk import (
+ async_runner_wrap,
+ async_agent_wrap,
+ )
+ from openlit.instrumentation.google_adk.google_adk import sync_runner_wrap
+
+ for module, method, op_key, _ in WORKFLOW_OPERATIONS:
+ try:
+ if op_key == "agent_init":
+ wrapper = _wrap_agent_init(
+ tracer,
+ environment,
+ application_name,
+ capture_message_content,
+ agent_registry,
+ )
+ elif op_key == "runner_run":
+ wrapper = sync_runner_wrap(
+ op_key,
+ version,
+ environment,
+ application_name,
+ tracer,
+ pricing_info,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ agent_registry,
+ )
+ elif op_key == "runner_run_async":
+ wrapper = async_runner_wrap(
+ op_key,
+ version,
+ environment,
+ application_name,
+ tracer,
+ pricing_info,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ agent_registry,
+ )
+ elif op_key == "agent_run_async":
+ wrapper = async_agent_wrap(
+ op_key,
+ version,
+ environment,
+ application_name,
+ tracer,
+ pricing_info,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ agent_registry,
+ )
+ else:
+ continue
+
+ wrap_function_wrapper(module, method, wrapper)
+ except Exception:
+ pass
+
+ if detailed_tracing:
+ for module, method, op_key, _ in DETAILED_OPERATIONS:
+ try:
+ wrapper = async_runner_wrap(
+ op_key,
+ version,
+ environment,
+ application_name,
+ tracer,
+ pricing_info,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ agent_registry,
+ )
+ wrap_function_wrapper(module, method, wrapper)
+ except Exception:
+ pass
+
+ def _uninstrument(self, **kwargs):
+ """Restore original ADK tracers and tracing functions."""
+ originals = getattr(self, "_original_tracers", {})
+
+ try:
+ if (
+ "runners.tracer" in originals
+ and originals["runners.tracer"] is not None
+ ):
+ import google.adk.runners as runners_mod
+
+ runners_mod.tracer = originals["runners.tracer"]
+ except Exception:
+ pass
+
+ try:
+ if (
+ "base_agent.tracer" in originals
+ and originals["base_agent.tracer"] is not None
+ ):
+ import google.adk.agents.base_agent as base_agent_mod
+
+ base_agent_mod.tracer = originals["base_agent.tracer"]
+ except Exception:
+ pass
+
+ try:
+ original_fn = getattr(self, "_original_trace_call_llm", None)
+ if original_fn is not None:
+ import google.adk.flows.llm_flows.base_llm_flow as blf_mod
+
+ blf_mod.trace_call_llm = original_fn
+ except Exception:
+ pass
+
+ try:
+ original_fn = getattr(self, "_original_trace_tool_call", None)
+ if original_fn is not None:
+ import google.adk.flows.llm_flows.functions as functions_mod
+
+ functions_mod.trace_tool_call = original_fn
+ except Exception:
+ pass
+
+ try:
+ original_fn = getattr(self, "_original_trace_merged", None)
+ if original_fn is not None:
+ import google.adk.flows.llm_flows.functions as functions_mod
+
+ functions_mod.trace_merged_tool_calls = original_fn
+ except Exception:
+ pass
diff --git a/sdk/python/src/openlit/instrumentation/google_adk/async_google_adk.py b/sdk/python/src/openlit/instrumentation/google_adk/async_google_adk.py
new file mode 100644
index 00000000..c536066d
--- /dev/null
+++ b/sdk/python/src/openlit/instrumentation/google_adk/async_google_adk.py
@@ -0,0 +1,178 @@
+"""
+Google ADK async wrappers — OTel GenAI semantic convention compliant.
+
+Handles the async-generator pattern used by ``Runner.run_async``,
+``Runner.run_live``, and ``BaseAgent.run_async``.
+"""
+
+import time
+from opentelemetry import context as context_api
+from opentelemetry.trace import Link
+
+from openlit.__helpers import handle_exception
+from openlit.instrumentation.google_adk.utils import (
+ _ADK_WORKFLOW_ACTIVE,
+ OPERATION_MAP,
+ get_span_kind,
+ generate_span_name,
+ process_google_adk_response,
+ capture_event_output,
+ SemanticConvention,
+)
+
+
+def async_runner_wrap(
+ gen_ai_endpoint,
+ version,
+ environment,
+ application_name,
+ tracer,
+ pricing_info,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ agent_registry,
+):
+ """Create an async-generator wrapper for ``Runner.run_async`` / ``Runner.run_live``."""
+
+ def wrapper(wrapped, instance, args, kwargs):
+ if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
+ return wrapped(*args, **kwargs)
+
+ if _ADK_WORKFLOW_ACTIVE.get(False):
+ return wrapped(*args, **kwargs)
+
+ operation_type = OPERATION_MAP.get(
+ gen_ai_endpoint, SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT
+ )
+ span_kind = get_span_kind(operation_type)
+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)
+
+ links = []
+ all_contexts = agent_registry.get_all()
+ if all_contexts:
+ links = [Link(ctx) for ctx in all_contexts]
+
+ async def _instrumented():
+ with tracer.start_as_current_span(
+ span_name, kind=span_kind, links=links
+ ) as span:
+ start_time = time.time()
+
+ session_id = kwargs.get("session_id")
+ if session_id:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_CONVERSATION_ID,
+ str(session_id),
+ )
+
+ try:
+ generator = wrapped(*args, **kwargs)
+ async for event in generator:
+ if (
+ hasattr(event, "is_final_response")
+ and event.is_final_response()
+ ):
+ capture_event_output(span, event, capture_message_content)
+ yield event
+
+ process_google_adk_response(
+ span,
+ gen_ai_endpoint,
+ instance,
+ start_time,
+ version,
+ environment,
+ application_name,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ )
+
+ except Exception as e:
+ handle_exception(span, e)
+ raise
+
+ return _instrumented()
+
+ return wrapper
+
+
+def async_agent_wrap(
+ gen_ai_endpoint,
+ version,
+ environment,
+ application_name,
+ tracer,
+ pricing_info,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ agent_registry,
+):
+ """Create an async-generator wrapper for ``BaseAgent.run_async``."""
+
+ def wrapper(wrapped, instance, args, kwargs):
+ if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
+ return wrapped(*args, **kwargs)
+
+ operation_type = OPERATION_MAP.get(
+ gen_ai_endpoint, SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT
+ )
+ span_kind = get_span_kind(operation_type)
+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)
+
+ links = []
+ agent_name = getattr(instance, "name", None)
+ if agent_name:
+ creation_ctx = agent_registry.get(str(agent_name))
+ if creation_ctx:
+ links = [Link(creation_ctx)]
+
+ async def _instrumented():
+ with tracer.start_as_current_span(
+ span_name, kind=span_kind, links=links
+ ) as span:
+ start_time = time.time()
+
+ ctx = args[0] if args else kwargs.get("ctx")
+ if ctx:
+ session = getattr(ctx, "session", None)
+ if session:
+ session_id = getattr(session, "id", None)
+ if session_id:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_CONVERSATION_ID,
+ str(session_id),
+ )
+
+ try:
+ generator = wrapped(*args, **kwargs)
+ async for event in generator:
+ if (
+ hasattr(event, "is_final_response")
+ and event.is_final_response()
+ ):
+ capture_event_output(span, event, capture_message_content)
+ yield event
+
+ process_google_adk_response(
+ span,
+ gen_ai_endpoint,
+ instance,
+ start_time,
+ version,
+ environment,
+ application_name,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ )
+
+ except Exception as e:
+ handle_exception(span, e)
+ raise
+
+ return _instrumented()
+
+ return wrapper
diff --git a/sdk/python/src/openlit/instrumentation/google_adk/google_adk.py b/sdk/python/src/openlit/instrumentation/google_adk/google_adk.py
new file mode 100644
index 00000000..0b0921be
--- /dev/null
+++ b/sdk/python/src/openlit/instrumentation/google_adk/google_adk.py
@@ -0,0 +1,89 @@
+"""
+Google ADK sync wrapper — OTel GenAI semantic convention compliant.
+
+Wraps ``Runner.run`` which is a synchronous method that internally
+calls ``Runner.run_async`` via ``asyncio.run``.
+"""
+
+import time
+from opentelemetry import context as context_api
+from opentelemetry.trace import Link
+
+from openlit.__helpers import handle_exception
+from openlit.instrumentation.google_adk.utils import (
+ _ADK_WORKFLOW_ACTIVE,
+ OPERATION_MAP,
+ get_span_kind,
+ generate_span_name,
+ process_google_adk_response,
+ SemanticConvention,
+)
+
+
+def sync_runner_wrap(
+ gen_ai_endpoint,
+ version,
+ environment,
+ application_name,
+ tracer,
+ pricing_info,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ agent_registry,
+):
+ """Create a sync wrapper for ``Runner.run``."""
+
+ def wrapper(wrapped, instance, args, kwargs):
+ if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):
+ return wrapped(*args, **kwargs)
+
+ operation_type = OPERATION_MAP.get(
+ gen_ai_endpoint, SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT
+ )
+ span_kind = get_span_kind(operation_type)
+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)
+
+ links = []
+ all_contexts = agent_registry.get_all()
+ if all_contexts:
+ links = [Link(ctx) for ctx in all_contexts]
+
+ with tracer.start_as_current_span(
+ span_name, kind=span_kind, links=links
+ ) as span:
+ start_time = time.time()
+
+ session_id = kwargs.get("session_id")
+ if session_id:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_CONVERSATION_ID,
+ str(session_id),
+ )
+
+ tok = _ADK_WORKFLOW_ACTIVE.set(True)
+ try:
+ response = wrapped(*args, **kwargs)
+
+ process_google_adk_response(
+ span,
+ gen_ai_endpoint,
+ instance,
+ start_time,
+ version,
+ environment,
+ application_name,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ )
+
+ return response
+
+ except Exception as e:
+ handle_exception(span, e)
+ raise
+ finally:
+ _ADK_WORKFLOW_ACTIVE.reset(tok)
+
+ return wrapper
diff --git a/sdk/python/src/openlit/instrumentation/google_adk/utils.py b/sdk/python/src/openlit/instrumentation/google_adk/utils.py
new file mode 100644
index 00000000..008f1d5d
--- /dev/null
+++ b/sdk/python/src/openlit/instrumentation/google_adk/utils.py
@@ -0,0 +1,883 @@
+"""
+Google ADK utilities for OTel GenAI semantic convention compliant telemetry.
+
+Follows the same patterns as the CrewAI / LangGraph / OpenAI Agents
+instrumentations. All operation names, span kinds, and attributes comply
+with the OTel GenAI semantic conventions (gen-ai-spans.md,
+gen-ai-agent-spans.md).
+
+Key technique: ``_PassthroughTracer`` (adopted from OpenInference) replaces
+ADK's internal tracers so that OpenLIT controls span creation for
+``invoke_agent`` (both Runner and BaseAgent), while ADK's ``call_llm``,
+``generate_content``, and ``execute_tool`` spans remain as children enriched
+via decorator-style wrappers on ADK's tracing functions.
+"""
+
+import os
+import json
+import time
+from contextvars import ContextVar
+from contextlib import contextmanager
+
+import wrapt
+from opentelemetry import trace
+from opentelemetry.trace import SpanKind, Status, StatusCode
+
+from openlit.__helpers import (
+ common_framework_span_attributes,
+ truncate_content,
+ truncate_message_content,
+)
+from openlit.semcov import SemanticConvention
+
+# Deduplication: prevents Runner.run_async from creating a second workflow
+# span when called internally by Runner.run.
+_ADK_WORKFLOW_ACTIVE: ContextVar[bool] = ContextVar(
+ "_adk_workflow_active", default=False
+)
+
+# ---------------------------------------------------------------------------
+# OTel GenAI operation mapping
+# ---------------------------------------------------------------------------
+OPERATION_MAP = {
+ "agent_init": SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,
+ "runner_run_async": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ "runner_run": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ "runner_run_live": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ "agent_run_async": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+}
+
+# ---------------------------------------------------------------------------
+# SpanKind per operation (OTel GenAI spec)
+# ---------------------------------------------------------------------------
+SPAN_KIND_MAP = {
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT: SpanKind.CLIENT,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK: SpanKind.INTERNAL,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT: SpanKind.INTERNAL,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS: SpanKind.INTERNAL,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT: SpanKind.CLIENT,
+}
+
+
+def get_operation_type(endpoint):
+ """Return the standard ``gen_ai.operation.name`` for an ADK endpoint."""
+ return OPERATION_MAP.get(endpoint, SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT)
+
+
+def get_span_kind(operation_type):
+ """Return the correct ``SpanKind`` per OTel GenAI spec."""
+ return SPAN_KIND_MAP.get(operation_type, SpanKind.INTERNAL)
+
+
+# ---------------------------------------------------------------------------
+# Span name generation
+# ---------------------------------------------------------------------------
+def generate_span_name(endpoint, instance, args=None, kwargs=None):
+ """Return an OTel-compliant span name: ``{operation} {entity_name}``."""
+ operation = get_operation_type(endpoint)
+
+ if endpoint == "agent_init":
+ name = getattr(instance, "name", None) or "agent"
+ return f"create_agent {name}"
+
+ if endpoint in ("runner_run_async", "runner_run", "runner_run_live"):
+ app_name = (
+ getattr(instance, "app_name", None)
+ or getattr(instance, "_app_name", None)
+ or "google_adk"
+ )
+ return f"invoke_agent {app_name}"
+
+ if endpoint == "agent_run_async":
+ name = getattr(instance, "name", None) or "agent"
+ return f"invoke_agent {name}"
+
+ return f"{operation} {endpoint}"
+
+
+# ---------------------------------------------------------------------------
+# _PassthroughTracer
+# ---------------------------------------------------------------------------
+class _PassthroughTracer(wrapt.ObjectProxy): # pylint: disable=too-few-public-methods
+ """Drop-in replacement for ADK's ``tracer`` objects.
+
+ Overrides ``start_as_current_span`` to yield the **current** span
+ instead of creating a new one. This lets OpenLIT own top-level spans
+ while ADK's tracing code still runs (setting attributes, etc.) on
+ OpenLIT's spans.
+ """
+
+ @contextmanager
+ def start_as_current_span(self, *args, **kwargs):
+ """Yield the current span instead of starting a new one."""
+ yield trace.get_current_span()
+
+
+# ---------------------------------------------------------------------------
+# Server address resolution
+# ---------------------------------------------------------------------------
+_NON_GOOGLE_PROVIDERS = {
+ "anthropic": ("api.anthropic.com", 443, "anthropic"),
+ "claude": ("api.anthropic.com", 443, "anthropic"),
+ "openai": ("api.openai.com", 443, "openai"),
+ "gpt": ("api.openai.com", 443, "openai"),
+ "mistral": ("api.mistral.ai", 443, "mistral"),
+ "cohere": ("api.cohere.ai", 443, "cohere"),
+}
+
+
+def _detect_provider_from_model_str(model_str):
+ """Detect non-Google provider from a model name string like ``anthropic/claude-...``."""
+ if not model_str:
+ return None
+ lower = model_str.lower()
+ prefix = lower.split("/")[0] if "/" in lower else lower.split("-")[0]
+ return _NON_GOOGLE_PROVIDERS.get(prefix)
+
+
+def resolve_server_info(instance=None, model_name=None):
+ """Return ``(server_address, server_port, provider_name)`` for Google ADK.
+
+ Attempts to detect the backend from a model name string or the
+ agent/runner instance's model object (e.g. LiteLlm with a
+ non-Google model). Falls back to the ``GOOGLE_GENAI_USE_VERTEXAI``
+ env var to distinguish Vertex AI from Gemini API.
+ """
+ if model_name:
+ detected = _detect_provider_from_model_str(model_name)
+ if detected:
+ return detected
+
+ if instance is not None:
+ try:
+ model_obj = getattr(instance, "model", None)
+ if model_obj is None:
+ agent = getattr(instance, "agent", None)
+ if agent:
+ model_obj = getattr(agent, "model", None)
+ if model_obj:
+ resolved = _resolve_model_string(model_obj)
+ if resolved:
+ detected = _detect_provider_from_model_str(resolved)
+ if detected:
+ return detected
+ except Exception:
+ pass
+
+ if os.getenv("GOOGLE_GENAI_USE_VERTEXAI", "").lower() in ("true", "1"):
+ return "aiplatform.googleapis.com", 443, "gcp.vertex_ai"
+ return "generativelanguage.googleapis.com", 443, "gcp.gemini"
+
+
+# ---------------------------------------------------------------------------
+# Model extraction
+# ---------------------------------------------------------------------------
+def _resolve_model_string(model_obj):
+ """Extract the model name string from a model object (e.g. LiteLlm, BaseLlm).
+
+ Handles Pydantic model objects where ``.model`` is a ``str`` field,
+ as well as objects with a ``model_name`` attribute.
+ """
+ if isinstance(model_obj, str):
+ return model_obj
+ model_name = getattr(model_obj, "model_name", None)
+ if model_name and isinstance(model_name, str):
+ return model_name
+ inner_model = getattr(model_obj, "model", None)
+ if inner_model and isinstance(inner_model, str):
+ return inner_model
+ return None
+
+
+def extract_model_name(instance):
+ """Best-effort model name extraction from an ADK agent/runner instance."""
+ try:
+ model = getattr(instance, "model", None)
+ if model:
+ resolved = _resolve_model_string(model)
+ if resolved:
+ return resolved
+
+ root_agent = getattr(instance, "agent", None)
+ if root_agent:
+ return extract_model_name(root_agent)
+ except Exception:
+ pass
+ return "unknown"
+
+
+# ---------------------------------------------------------------------------
+# Content capture helpers
+# ---------------------------------------------------------------------------
+def _extract_parts(parts):
+ """Extract text, function_call, and function_response data from Content parts."""
+ text_parts = []
+ tool_calls = []
+ tool_responses = []
+ for part in parts or []:
+ text = getattr(part, "text", None)
+ if text:
+ text_parts.append(truncate_content(str(text)))
+
+ fc = getattr(part, "function_call", None)
+ if fc:
+ call_entry = {"name": getattr(fc, "name", ""), "id": getattr(fc, "id", "")}
+ fc_args = getattr(fc, "args", None)
+ if fc_args:
+ try:
+ call_entry["arguments"] = (
+ json.dumps(fc_args)
+ if isinstance(fc_args, dict)
+ else str(fc_args)
+ )
+ except (TypeError, ValueError):
+ call_entry["arguments"] = str(fc_args)
+ tool_calls.append(call_entry)
+
+ fr = getattr(part, "function_response", None)
+ if fr:
+ resp_entry = {"name": getattr(fr, "name", ""), "id": getattr(fr, "id", "")}
+ fr_resp = getattr(fr, "response", None)
+ if fr_resp is not None:
+ try:
+ resp_entry["content"] = (
+ json.dumps(fr_resp)
+ if isinstance(fr_resp, dict)
+ else str(fr_resp)
+ )
+ except (TypeError, ValueError):
+ resp_entry["content"] = str(fr_resp)
+ tool_responses.append(resp_entry)
+
+ return text_parts, tool_calls, tool_responses
+
+
+def capture_input_messages(span, llm_request, capture_message_content):
+ """Set ``gen_ai.input.messages`` from an ADK ``LlmRequest``.
+
+ Produces the OTel parts-based schema:
+ ``[{"role": ..., "parts": [{"type": "text", "content": ...}, ...]}]``
+ """
+ if not capture_message_content:
+ return
+ try:
+ contents = getattr(llm_request, "contents", None)
+ if not contents:
+ return
+ messages = []
+ for content in contents[:20]:
+ role = getattr(content, "role", "user")
+ raw_parts = getattr(content, "parts", [])
+ text_parts, tool_calls, tool_responses = _extract_parts(raw_parts)
+
+ parts = []
+ for text in text_parts:
+ parts.append({"type": "text", "content": text})
+ for tc in tool_calls:
+ parts.append(
+ {
+ "type": "tool_call",
+ "id": tc.get("id", ""),
+ "name": tc.get("name", ""),
+ "arguments": tc.get("arguments", ""),
+ }
+ )
+ for tr in tool_responses:
+ parts.append(
+ {
+ "type": "tool_call_response",
+ "id": tr.get("id", ""),
+ "response": tr.get("content", ""),
+ }
+ )
+ if parts:
+ messages.append({"role": str(role), "parts": parts})
+ if messages:
+ truncate_message_content(messages)
+ span.set_attribute(
+ SemanticConvention.GEN_AI_INPUT_MESSAGES, json.dumps(messages)
+ )
+ except Exception:
+ pass
+
+
+def capture_output_messages(
+ span, llm_response, capture_message_content, finish_reason="stop"
+):
+ """Set ``gen_ai.output.messages`` from an ADK ``LlmResponse``.
+
+ Produces the OTel parts-based schema with ``finish_reason``:
+ ``[{"role": "assistant", "parts": [...], "finish_reason": "stop"}]``
+ """
+ if not capture_message_content:
+ return
+ try:
+ content = getattr(llm_response, "content", None)
+ if not content:
+ return
+ raw_parts = getattr(content, "parts", [])
+ text_parts, tool_calls, _ = _extract_parts(raw_parts)
+
+ parts = []
+ for text in text_parts:
+ parts.append({"type": "text", "content": text})
+ for tc in tool_calls:
+ parts.append(
+ {
+ "type": "tool_call",
+ "id": tc.get("id", ""),
+ "name": tc.get("name", ""),
+ "arguments": tc.get("arguments", ""),
+ }
+ )
+ if parts:
+ messages = [
+ {"role": "assistant", "parts": parts, "finish_reason": finish_reason}
+ ]
+ truncate_message_content(messages)
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_MESSAGES,
+ json.dumps(messages),
+ )
+ except Exception:
+ pass
+
+
+def capture_event_output(span, event, capture_message_content):
+ """Capture final response output from an ADK ``Event``.
+
+ Produces the OTel parts-based schema with ``finish_reason``:
+ ``[{"role": "assistant", "parts": [...], "finish_reason": "stop"}]``
+ """
+ if not capture_message_content:
+ return
+ try:
+ content = getattr(event, "content", None)
+ if not content:
+ return
+ raw_parts = getattr(content, "parts", [])
+ text_parts, tool_calls, _ = _extract_parts(raw_parts)
+
+ parts = []
+ for text in text_parts:
+ parts.append({"type": "text", "content": text})
+ for tc in tool_calls:
+ parts.append(
+ {
+ "type": "tool_call",
+ "id": tc.get("id", ""),
+ "name": tc.get("name", ""),
+ "arguments": tc.get("arguments", ""),
+ }
+ )
+ if parts:
+ messages = [{"role": "assistant", "parts": parts, "finish_reason": "stop"}]
+ truncate_message_content(messages)
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_MESSAGES,
+ json.dumps(messages),
+ )
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Token extraction
+# ---------------------------------------------------------------------------
+def extract_token_usage(llm_response):
+ """Return token usage tuple from an ADK response.
+
+ Returns ``(input_tokens, output_tokens, reasoning_tokens, cached_tokens, total_tokens)``.
+ ``output_tokens`` is ``candidates_token_count`` only (excluding reasoning).
+ ``reasoning_tokens`` is ``thoughts_token_count`` separately.
+ """
+ try:
+ usage = getattr(llm_response, "usage_metadata", None)
+ if not usage:
+ return None, None, None, None, None
+ input_tokens = getattr(usage, "prompt_token_count", None)
+ output_tokens = getattr(usage, "candidates_token_count", None)
+ reasoning_tokens = getattr(usage, "thoughts_token_count", None)
+ cached_tokens = getattr(usage, "cached_content_token_count", None)
+ total_tokens = getattr(usage, "total_token_count", None)
+ return (
+ input_tokens,
+ output_tokens,
+ reasoning_tokens,
+ cached_tokens,
+ total_tokens,
+ )
+ except Exception:
+ return None, None, None, None, None
+
+
+# ---------------------------------------------------------------------------
+# LLM span enrichment (called from trace_call_llm wrapper)
+# ---------------------------------------------------------------------------
+def enrich_llm_span(span, llm_request, llm_response, capture_message_content):
+ """Add OTel GenAI semantic convention attributes to an ADK ``call_llm`` span."""
+ try:
+ request_model = getattr(llm_request, "model", None) if llm_request else None
+ model_str = str(request_model) if request_model else None
+ server_address, server_port, provider_name = resolve_server_info(
+ model_name=model_str
+ )
+
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OPERATION,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ )
+ span.set_attribute(SemanticConvention.GEN_AI_PROVIDER_NAME, provider_name)
+ span.set_attribute(SemanticConvention.SERVER_ADDRESS, server_address)
+ span.set_attribute(SemanticConvention.SERVER_PORT, server_port)
+
+ if llm_request:
+ if model_str:
+ span.set_attribute(SemanticConvention.GEN_AI_REQUEST_MODEL, model_str)
+ config = getattr(llm_request, "config", None)
+ if config:
+ temp = getattr(config, "temperature", None)
+ if temp is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_REQUEST_TEMPERATURE, float(temp)
+ )
+ top_p = getattr(config, "top_p", None)
+ if top_p is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_REQUEST_TOP_P, float(top_p)
+ )
+ max_tokens = getattr(config, "max_output_tokens", None)
+ if max_tokens is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_REQUEST_MAX_TOKENS, int(max_tokens)
+ )
+ if capture_message_content:
+ config = config or getattr(llm_request, "config", None)
+ sys_instr = (
+ getattr(config, "system_instruction", None) if config else None
+ )
+ if sys_instr:
+ instr_text = (
+ str(sys_instr) if not isinstance(sys_instr, str) else sys_instr
+ )
+ span.set_attribute(
+ SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS,
+ json.dumps(
+ [
+ {
+ "type": "text",
+ "content": truncate_content(instr_text),
+ }
+ ]
+ ),
+ )
+ capture_input_messages(span, llm_request, capture_message_content)
+
+ if llm_response:
+ (
+ input_tokens,
+ output_tokens,
+ reasoning_tokens,
+ cached_tokens,
+ total_tokens,
+ ) = extract_token_usage(llm_response)
+ if input_tokens is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, input_tokens
+ )
+ if output_tokens is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, output_tokens
+ )
+ if reasoning_tokens is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_COMPLETION_TOKENS_DETAILS_REASONING,
+ reasoning_tokens,
+ )
+ if cached_tokens is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS,
+ cached_tokens,
+ )
+ if total_tokens is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_TOTAL_TOKENS, total_tokens
+ )
+
+ response_model = getattr(llm_response, "model_version", None)
+ if response_model:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_RESPONSE_MODEL, str(response_model)
+ )
+
+ fr_str = "stop"
+ finish_reason = getattr(llm_response, "finish_reason", None)
+ if finish_reason:
+ try:
+ fr_str = finish_reason.value.lower()
+ except AttributeError:
+ fr_str = str(finish_reason).lower()
+ span.set_attribute(
+ SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON,
+ [fr_str],
+ )
+
+ response_id = getattr(llm_response, "response_id", None) or getattr(
+ llm_response, "id", None
+ )
+ if response_id:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_RESPONSE_ID, str(response_id)
+ )
+
+ error_code = getattr(llm_response, "error_code", None)
+ if error_code:
+ span.set_attribute(SemanticConvention.ERROR_TYPE, str(error_code))
+ error_message = getattr(llm_response, "error_message", None)
+ if error_message:
+ span.set_status(Status(StatusCode.ERROR, str(error_message)))
+
+ capture_output_messages(span, llm_response, capture_message_content, fr_str)
+
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_TYPE,
+ _determine_output_type(llm_response),
+ )
+
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# ADK Event -> function response extraction
+# ---------------------------------------------------------------------------
+def _determine_output_type(llm_response):
+ """Determine the output type from an LLM response: ``text`` or ``tool_calls``."""
+ try:
+ content = getattr(llm_response, "content", None)
+ if content:
+ for part in getattr(content, "parts", []) or []:
+ if getattr(part, "function_call", None):
+ return "tool_calls"
+ except Exception:
+ pass
+ return "text"
+
+
+def _extract_from_event(event_obj):
+ """Extract ``(response_dict, tool_call_id)`` from an ADK ``Event``.
+
+ ADK's ``trace_tool_call`` passes a ``function_response_event`` (an Event)
+ whose response payload lives at
+ ``event.content.parts[0].function_response.response`` and the tool call
+ ID at ``event.content.parts[0].function_response.id``.
+ """
+ try:
+ content = getattr(event_obj, "content", None)
+ if content is None:
+ return None, None
+ parts = getattr(content, "parts", None)
+ if not parts or len(parts) == 0:
+ return None, None
+ fn_resp = getattr(parts[0], "function_response", None)
+ if fn_resp is None:
+ return None, None
+ resp = getattr(fn_resp, "response", None)
+ call_id = getattr(fn_resp, "id", None)
+ return resp, call_id
+ except Exception:
+ return None, None
+
+
+def _is_adk_event(obj):
+ """Return True if *obj* looks like a ``google.adk.events.event.Event``."""
+ cls_qual = getattr(type(obj), "__qualname__", "")
+ return cls_qual == "Event" and hasattr(obj, "content")
+
+
+# ---------------------------------------------------------------------------
+# Tool span enrichment (called from trace_tool_call wrapper)
+# ---------------------------------------------------------------------------
+def enrich_tool_span(
+ span,
+ tool,
+ function_args,
+ function_response_event,
+ capture_message_content,
+ error=None,
+):
+ """Add OTel GenAI semantic convention attributes to an ADK ``execute_tool`` span.
+
+ ``function_response_event`` is the raw ADK ``Event`` passed by
+ ``trace_tool_call``. We extract the actual response dict and tool-call
+ ID from it.
+ """
+ try:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OPERATION,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
+ )
+ span.set_attribute(
+ SemanticConvention.GEN_AI_PROVIDER_NAME,
+ SemanticConvention.GEN_AI_SYSTEM_GOOGLE_ADK,
+ )
+
+ if tool:
+ tool_name = getattr(tool, "name", None) or type(tool).__name__
+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_NAME, str(tool_name))
+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_TYPE, type(tool).__name__)
+ tool_desc = getattr(tool, "description", None)
+ if tool_desc:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_DESCRIPTION,
+ truncate_content(str(tool_desc)),
+ )
+
+ response_dict, tool_call_id = None, None
+ if _is_adk_event(function_response_event):
+ response_dict, tool_call_id = _extract_from_event(function_response_event)
+ elif isinstance(function_response_event, dict):
+ response_dict = function_response_event
+ tool_call_id = function_response_event.get("id")
+
+ if capture_message_content:
+ if function_args is not None:
+ try:
+ args_str = (
+ json.dumps(function_args)
+ if isinstance(function_args, dict)
+ else str(function_args)
+ )
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS,
+ truncate_content(args_str),
+ )
+ except (TypeError, ValueError):
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS,
+ truncate_content(str(function_args)),
+ )
+
+ if response_dict is not None:
+ try:
+ result_str = (
+ json.dumps(response_dict)
+ if isinstance(response_dict, dict)
+ else str(response_dict)
+ )
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_RESULT,
+ truncate_content(result_str),
+ )
+ except (TypeError, ValueError):
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_RESULT,
+ truncate_content(str(response_dict)),
+ )
+
+ if tool_call_id:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_ID, str(tool_call_id)
+ )
+
+ if error is not None:
+ error_type = type(error).__name__ if type(error).__name__ else "_OTHER"
+ span.set_attribute(SemanticConvention.ERROR_TYPE, error_type)
+ span.set_status(Status(StatusCode.ERROR, str(error)))
+
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Merged tool span enrichment (called from trace_merged_tool_calls wrapper)
+# ---------------------------------------------------------------------------
+def enrich_merged_tool_span(
+ span, response_event_id, function_response_event, capture_message_content
+):
+ """Add OTel GenAI semantic convention attributes to a merged ``execute_tool`` span."""
+ try:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OPERATION,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
+ )
+ span.set_attribute(
+ SemanticConvention.GEN_AI_PROVIDER_NAME,
+ SemanticConvention.GEN_AI_SYSTEM_GOOGLE_ADK,
+ )
+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_NAME, "(merged tools)")
+
+ if response_event_id:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_ID, str(response_event_id)
+ )
+
+ if capture_message_content and function_response_event is not None:
+ try:
+ content = getattr(function_response_event, "content", None)
+ if content:
+ parts = getattr(content, "parts", []) or []
+ tool_results = []
+ for part in parts:
+ fn_resp = getattr(part, "function_response", None)
+ if fn_resp:
+ resp = getattr(fn_resp, "response", None)
+ name = getattr(fn_resp, "name", None)
+ entry = {}
+ if name:
+ entry["name"] = str(name)
+ if resp is not None:
+ entry["response"] = resp
+ if entry:
+ tool_results.append(entry)
+ if tool_results:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_RESULT,
+ truncate_content(json.dumps(tool_results)),
+ )
+ except (TypeError, ValueError):
+ pass
+
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Response processor for Runner/Agent spans
+# ---------------------------------------------------------------------------
+def process_google_adk_response(
+ span,
+ endpoint,
+ instance,
+ start_time,
+ version,
+ environment,
+ application_name,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+):
+ """Set OTel-compliant span attributes and record metrics for a completed span."""
+ end_time = time.time()
+
+ operation_type = get_operation_type(endpoint)
+ server_address, server_port, _ = resolve_server_info(instance)
+ request_model = extract_model_name(instance)
+
+ scope = type("Scope", (), {})()
+ scope._span = span
+ scope._start_time = start_time
+ scope._end_time = end_time
+
+ model_proxy = (
+ type("P", (), {"model_name": request_model})() if request_model else None
+ )
+
+ common_framework_span_attributes(
+ scope,
+ SemanticConvention.GEN_AI_SYSTEM_GOOGLE_ADK,
+ server_address,
+ server_port,
+ environment,
+ application_name,
+ version,
+ operation_type,
+ model_proxy,
+ )
+
+ if endpoint in ("runner_run_async", "runner_run", "runner_run_live"):
+ _set_runner_agent_attributes(span, instance, endpoint)
+ elif endpoint == "agent_run_async":
+ _set_agent_attributes(span, instance)
+
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_TYPE,
+ SemanticConvention.GEN_AI_OUTPUT_TYPE_TEXT,
+ )
+
+ if not disable_metrics and metrics:
+ record_google_adk_metrics(
+ metrics,
+ operation_type,
+ end_time - start_time,
+ environment,
+ application_name,
+ request_model,
+ server_address,
+ server_port,
+ )
+
+ span.set_status(Status(StatusCode.OK))
+
+
+# ---------------------------------------------------------------------------
+# Attribute setters
+# ---------------------------------------------------------------------------
+def _set_runner_agent_attributes(span, instance, endpoint):
+ """Set attributes for Runner ``invoke_agent`` spans."""
+ try:
+ app_name = (
+ getattr(instance, "app_name", None)
+ or getattr(instance, "_app_name", None)
+ or "google_adk"
+ )
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(app_name))
+
+ if endpoint == "runner_run_live":
+ span.set_attribute(SemanticConvention.GEN_AI_EXECUTION_MODE, "live")
+ elif endpoint == "runner_run":
+ span.set_attribute(SemanticConvention.GEN_AI_EXECUTION_MODE, "sync")
+ else:
+ span.set_attribute(SemanticConvention.GEN_AI_EXECUTION_MODE, "async")
+ except Exception:
+ pass
+
+
+def _set_agent_attributes(span, instance):
+ """Set attributes for ``invoke_agent`` (BaseAgent.run_async) spans."""
+ try:
+ name = getattr(instance, "name", None)
+ if name:
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(name))
+
+ description = getattr(instance, "description", None)
+ if description:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION, str(description)
+ )
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Metrics
+# ---------------------------------------------------------------------------
+def record_google_adk_metrics(
+ metrics,
+ operation_type,
+ duration,
+ environment,
+ application_name,
+ request_model,
+ server_address,
+ server_port,
+):
+ """Record OTel-compliant metrics."""
+ try:
+ attributes = {
+ SemanticConvention.GEN_AI_OPERATION: operation_type,
+ SemanticConvention.GEN_AI_PROVIDER_NAME: SemanticConvention.GEN_AI_SYSTEM_GOOGLE_ADK,
+ "service.name": application_name,
+ "deployment.environment": environment,
+ }
+ if request_model and request_model != "unknown":
+ attributes[SemanticConvention.GEN_AI_REQUEST_MODEL] = request_model
+ if server_address:
+ attributes[SemanticConvention.SERVER_ADDRESS] = server_address
+ if server_port:
+ attributes[SemanticConvention.SERVER_PORT] = server_port
+
+ if "genai_client_operation_duration" in metrics:
+ metrics["genai_client_operation_duration"].record(duration, attributes)
+ except Exception:
+ pass
diff --git a/sdk/python/src/openlit/instrumentation/litellm/async_litellm.py b/sdk/python/src/openlit/instrumentation/litellm/async_litellm.py
index 298235f3..0b31c2f0 100644
--- a/sdk/python/src/openlit/instrumentation/litellm/async_litellm.py
+++ b/sdk/python/src/openlit/instrumentation/litellm/async_litellm.py
@@ -9,6 +9,11 @@ from openlit.__helpers import (
handle_exception,
record_completion_metrics,
record_embedding_metrics,
+ is_litellm_span_active,
+ set_litellm_span_active,
+ reset_litellm_span_active,
+ set_framework_llm_active,
+ reset_framework_llm_active,
)
from openlit.instrumentation.litellm.utils import (
get_litellm_server_address,
@@ -59,6 +64,7 @@ def acompletion(
self._response_model = ""
self._finish_reason = ""
self._response_service_tier = ""
+ self._response_system_fingerprint = ""
self._tools = None
self._input_tokens = 0
self._output_tokens = 0
@@ -143,34 +149,136 @@ def acompletion(
"""
Wraps the GenAI function call.
"""
- # Check if streaming is enabled for the API call
- streaming = kwargs.get("stream", False)
- server_address, server_port = get_litellm_server_address(instance, kwargs)
- request_model = kwargs.get("model", "openai/gpt-4o")
-
- span_name = f"{SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT} {request_model}"
-
- if streaming:
- # Special handling for streaming response
- awaited_wrapped = await wrapped(*args, **kwargs)
- span = tracer.start_span(span_name, kind=SpanKind.CLIENT)
- return TracedAsyncStream(
- awaited_wrapped,
- span,
- span_name,
- kwargs,
- server_address,
- server_port,
- event_provider=event_provider,
+ if is_litellm_span_active():
+ return await wrapped(*args, **kwargs)
+
+ litellm_token = set_litellm_span_active()
+ try:
+ streaming = kwargs.get("stream", False)
+ server_address, server_port = get_litellm_server_address(instance, kwargs)
+ request_model = kwargs.get("model", "openai/gpt-4o")
+
+ span_name = (
+ f"{SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT} {request_model}"
+ )
+
+ if streaming:
+ fw_token = set_framework_llm_active()
+ try:
+ awaited_wrapped = await wrapped(*args, **kwargs)
+ finally:
+ reset_framework_llm_active(fw_token)
+ span = tracer.start_span(span_name, kind=SpanKind.CLIENT)
+ return TracedAsyncStream(
+ awaited_wrapped,
+ span,
+ span_name,
+ kwargs,
+ server_address,
+ server_port,
+ event_provider=event_provider,
+ )
+ else:
+ with tracer.start_as_current_span(
+ span_name, kind=SpanKind.CLIENT
+ ) as span:
+ start_time = time.time()
+ fw_token = set_framework_llm_active()
+ try:
+ response = await wrapped(*args, **kwargs)
+ finally:
+ reset_framework_llm_active(fw_token)
+
+ try:
+ response = process_chat_response(
+ response=response,
+ request_model=request_model,
+ pricing_info=pricing_info,
+ server_port=server_port,
+ server_address=server_address,
+ environment=environment,
+ application_name=application_name,
+ metrics=metrics,
+ start_time=start_time,
+ span=span,
+ capture_message_content=capture_message_content,
+ disable_metrics=disable_metrics,
+ version=version,
+ event_provider=event_provider,
+ **kwargs,
+ )
+
+ except Exception as e:
+ handle_exception(span, e)
+ if not disable_metrics and metrics:
+ record_completion_metrics(
+ metrics,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ SemanticConvention.GEN_AI_SYSTEM_LITELLM,
+ server_address,
+ server_port,
+ request_model,
+ "unknown",
+ environment,
+ application_name,
+ start_time,
+ time.time(),
+ 0,
+ 0,
+ 0,
+ None,
+ None,
+ error_type=type(e).__name__ or "_OTHER",
+ )
+
+ return response
+ finally:
+ reset_litellm_span_active(litellm_token)
+
+ return wrapper
+
+
+def aembedding(
+ version,
+ environment,
+ application_name,
+ tracer,
+ pricing_info,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ event_provider=None,
+):
+ """
+ Generates a telemetry wrapper for GenAI embedding function call
+ """
+
+ async def wrapper(wrapped, instance, args, kwargs):
+ """
+ Wraps the GenAI embedding function call.
+ """
+ if is_litellm_span_active():
+ return await wrapped(*args, **kwargs)
+
+ litellm_token = set_litellm_span_active()
+ try:
+ server_address, server_port = get_litellm_server_address(instance, kwargs)
+ request_model = kwargs.get("model", "text-embedding-ada-002")
+
+ span_name = (
+ f"{SemanticConvention.GEN_AI_OPERATION_TYPE_EMBEDDING} {request_model}"
)
- else:
- # Handling for non-streaming responses
+
with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
start_time = time.time()
- response = await wrapped(*args, **kwargs)
+ fw_token = set_framework_llm_active()
+ try:
+ response = await wrapped(*args, **kwargs)
+ finally:
+ reset_framework_llm_active(fw_token)
try:
- response = process_chat_response(
+ response = process_embedding_response(
response=response,
request_model=request_model,
pricing_info=pricing_info,
@@ -191,9 +299,9 @@ def acompletion(
except Exception as e:
handle_exception(span, e)
if not disable_metrics and metrics:
- record_completion_metrics(
+ record_embedding_metrics(
metrics,
- SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_EMBEDDING,
SemanticConvention.GEN_AI_SYSTEM_LITELLM,
server_address,
server_port,
@@ -205,86 +313,11 @@ def acompletion(
time.time(),
0,
0,
- 0,
- None,
- None,
error_type=type(e).__name__ or "_OTHER",
)
return response
-
- return wrapper
-
-
-def aembedding(
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- event_provider=None,
-):
- """
- Generates a telemetry wrapper for GenAI embedding function call
- """
-
- async def wrapper(wrapped, instance, args, kwargs):
- """
- Wraps the GenAI embedding function call.
- """
- server_address, server_port = get_litellm_server_address(instance, kwargs)
- request_model = kwargs.get("model", "text-embedding-ada-002")
-
- span_name = (
- f"{SemanticConvention.GEN_AI_OPERATION_TYPE_EMBEDDING} {request_model}"
- )
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
- response = await wrapped(*args, **kwargs)
-
- try:
- response = process_embedding_response(
- response=response,
- request_model=request_model,
- pricing_info=pricing_info,
- server_port=server_port,
- server_address=server_address,
- environment=environment,
- application_name=application_name,
- metrics=metrics,
- start_time=start_time,
- span=span,
- capture_message_content=capture_message_content,
- disable_metrics=disable_metrics,
- version=version,
- event_provider=event_provider,
- **kwargs,
- )
-
- except Exception as e:
- handle_exception(span, e)
- if not disable_metrics and metrics:
- record_embedding_metrics(
- metrics,
- SemanticConvention.GEN_AI_OPERATION_TYPE_EMBEDDING,
- SemanticConvention.GEN_AI_SYSTEM_LITELLM,
- server_address,
- server_port,
- request_model,
- "unknown",
- environment,
- application_name,
- start_time,
- time.time(),
- 0,
- 0,
- error_type=type(e).__name__ or "_OTHER",
- )
-
- return response
+ finally:
+ reset_litellm_span_active(litellm_token)
return wrapper
diff --git a/sdk/python/src/openlit/instrumentation/litellm/litellm.py b/sdk/python/src/openlit/instrumentation/litellm/litellm.py
index e1372484..d6e53627 100644
--- a/sdk/python/src/openlit/instrumentation/litellm/litellm.py
+++ b/sdk/python/src/openlit/instrumentation/litellm/litellm.py
@@ -8,6 +8,11 @@ from openlit.__helpers import (
handle_exception,
record_completion_metrics,
record_embedding_metrics,
+ is_litellm_span_active,
+ set_litellm_span_active,
+ reset_litellm_span_active,
+ set_framework_llm_active,
+ reset_framework_llm_active,
)
from openlit.instrumentation.litellm.utils import (
get_litellm_server_address,
@@ -58,6 +63,7 @@ def completion(
self._response_model = ""
self._finish_reason = ""
self._response_service_tier = ""
+ self._response_system_fingerprint = ""
self._tools = None
self._input_tokens = 0
self._output_tokens = 0
@@ -120,34 +126,136 @@ def completion(
"""
Wraps the GenAI function call.
"""
- # Check if streaming is enabled for the API call
- streaming = kwargs.get("stream", False)
- server_address, server_port = get_litellm_server_address(instance, kwargs)
- request_model = kwargs.get("model", "openai/gpt-4o")
+ if is_litellm_span_active():
+ return wrapped(*args, **kwargs)
- span_name = f"{SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT} {request_model}"
+ litellm_token = set_litellm_span_active()
+ try:
+ streaming = kwargs.get("stream", False)
+ server_address, server_port = get_litellm_server_address(instance, kwargs)
+ request_model = kwargs.get("model", "openai/gpt-4o")
- if streaming:
- # Special handling for streaming response
- awaited_wrapped = wrapped(*args, **kwargs)
- span = tracer.start_span(span_name, kind=SpanKind.CLIENT)
- return TracedSyncStream(
- awaited_wrapped,
- span,
- span_name,
- kwargs,
- server_address,
- server_port,
- event_provider=event_provider,
+ span_name = (
+ f"{SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT} {request_model}"
)
- else:
- # Handling for non-streaming responses
+
+ if streaming:
+ fw_token = set_framework_llm_active()
+ try:
+ awaited_wrapped = wrapped(*args, **kwargs)
+ finally:
+ reset_framework_llm_active(fw_token)
+ span = tracer.start_span(span_name, kind=SpanKind.CLIENT)
+ return TracedSyncStream(
+ awaited_wrapped,
+ span,
+ span_name,
+ kwargs,
+ server_address,
+ server_port,
+ event_provider=event_provider,
+ )
+ else:
+ with tracer.start_as_current_span(
+ span_name, kind=SpanKind.CLIENT
+ ) as span:
+ start_time = time.time()
+ fw_token = set_framework_llm_active()
+ try:
+ response = wrapped(*args, **kwargs)
+ finally:
+ reset_framework_llm_active(fw_token)
+
+ try:
+ response = process_chat_response(
+ response=response,
+ request_model=request_model,
+ pricing_info=pricing_info,
+ server_port=server_port,
+ server_address=server_address,
+ environment=environment,
+ application_name=application_name,
+ metrics=metrics,
+ start_time=start_time,
+ span=span,
+ capture_message_content=capture_message_content,
+ disable_metrics=disable_metrics,
+ version=version,
+ event_provider=event_provider,
+ **kwargs,
+ )
+
+ except Exception as e:
+ handle_exception(span, e)
+ if not disable_metrics and metrics:
+ record_completion_metrics(
+ metrics,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ SemanticConvention.GEN_AI_SYSTEM_LITELLM,
+ server_address,
+ server_port,
+ request_model,
+ "unknown",
+ environment,
+ application_name,
+ start_time,
+ time.time(),
+ 0,
+ 0,
+ 0,
+ None,
+ None,
+ error_type=type(e).__name__ or "_OTHER",
+ )
+
+ return response
+ finally:
+ reset_litellm_span_active(litellm_token)
+
+ return wrapper
+
+
+def embedding(
+ version,
+ environment,
+ application_name,
+ tracer,
+ pricing_info,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ event_provider=None,
+):
+ """
+ Generates a telemetry wrapper for GenAI embedding function call
+ """
+
+ def wrapper(wrapped, instance, args, kwargs):
+ """
+ Wraps the GenAI embedding function call.
+ """
+ if is_litellm_span_active():
+ return wrapped(*args, **kwargs)
+
+ litellm_token = set_litellm_span_active()
+ try:
+ server_address, server_port = get_litellm_server_address(instance, kwargs)
+ request_model = kwargs.get("model", "text-embedding-ada-002")
+
+ span_name = (
+ f"{SemanticConvention.GEN_AI_OPERATION_TYPE_EMBEDDING} {request_model}"
+ )
+
with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
start_time = time.time()
- response = wrapped(*args, **kwargs)
+ fw_token = set_framework_llm_active()
+ try:
+ response = wrapped(*args, **kwargs)
+ finally:
+ reset_framework_llm_active(fw_token)
try:
- response = process_chat_response(
+ response = process_embedding_response(
response=response,
request_model=request_model,
pricing_info=pricing_info,
@@ -168,9 +276,9 @@ def completion(
except Exception as e:
handle_exception(span, e)
if not disable_metrics and metrics:
- record_completion_metrics(
+ record_embedding_metrics(
metrics,
- SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_EMBEDDING,
SemanticConvention.GEN_AI_SYSTEM_LITELLM,
server_address,
server_port,
@@ -182,86 +290,11 @@ def completion(
time.time(),
0,
0,
- 0,
- None,
- None,
error_type=type(e).__name__ or "_OTHER",
)
return response
-
- return wrapper
-
-
-def embedding(
- version,
- environment,
- application_name,
- tracer,
- pricing_info,
- capture_message_content,
- metrics,
- disable_metrics,
- event_provider=None,
-):
- """
- Generates a telemetry wrapper for GenAI embedding function call
- """
-
- def wrapper(wrapped, instance, args, kwargs):
- """
- Wraps the GenAI embedding function call.
- """
- server_address, server_port = get_litellm_server_address(instance, kwargs)
- request_model = kwargs.get("model", "text-embedding-ada-002")
-
- span_name = (
- f"{SemanticConvention.GEN_AI_OPERATION_TYPE_EMBEDDING} {request_model}"
- )
-
- with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
- start_time = time.time()
- response = wrapped(*args, **kwargs)
-
- try:
- response = process_embedding_response(
- response=response,
- request_model=request_model,
- pricing_info=pricing_info,
- server_port=server_port,
- server_address=server_address,
- environment=environment,
- application_name=application_name,
- metrics=metrics,
- start_time=start_time,
- span=span,
- capture_message_content=capture_message_content,
- disable_metrics=disable_metrics,
- version=version,
- event_provider=event_provider,
- **kwargs,
- )
-
- except Exception as e:
- handle_exception(span, e)
- if not disable_metrics and metrics:
- record_embedding_metrics(
- metrics,
- SemanticConvention.GEN_AI_OPERATION_TYPE_EMBEDDING,
- SemanticConvention.GEN_AI_SYSTEM_LITELLM,
- server_address,
- server_port,
- request_model,
- "unknown",
- environment,
- application_name,
- start_time,
- time.time(),
- 0,
- 0,
- error_type=type(e).__name__ or "_OTHER",
- )
-
- return response
+ finally:
+ reset_litellm_span_active(litellm_token)
return wrapper
diff --git a/sdk/python/src/openlit/instrumentation/litellm/utils.py b/sdk/python/src/openlit/instrumentation/litellm/utils.py
index 76796b78..80abcdf1 100644
--- a/sdk/python/src/openlit/instrumentation/litellm/utils.py
+++ b/sdk/python/src/openlit/instrumentation/litellm/utils.py
@@ -134,7 +134,7 @@ def build_input_messages(messages):
# Handle tool calls (for assistant messages)
if "tool_calls" in msg:
- for tool_call in msg.get("tool_calls", []):
+ for tool_call in msg.get("tool_calls") or []:
parts.append(
{
"type": "tool_call",
@@ -385,19 +385,24 @@ def process_chunk(scope, chunk):
except (IndexError, AttributeError, TypeError):
pass
scope._response_service_tier = (
- str(chunked.get("system_fingerprint", "")) or scope._response_service_tier
+ str(chunked.get("service_tier") or "") or scope._response_service_tier
+ )
+ scope._response_system_fingerprint = (
+ str(chunked.get("system_fingerprint") or "")
+ or scope._response_system_fingerprint
)
if chunked.get("usage"):
usage = chunked.get("usage", {})
scope._input_tokens = usage.get("prompt_tokens", 0)
scope._output_tokens = usage.get("completion_tokens", 0)
- prompt_tokens_details = usage.get(
- "prompt_tokens_details", usage.get("input_tokens_details", {})
+ prompt_tokens_details = (
+ usage.get("prompt_tokens_details", usage.get("input_tokens_details", {}))
+ or {}
)
scope._cache_read_input_tokens = prompt_tokens_details.get("cached_tokens", 0)
- scope._cache_creation_input_tokens = usage.get(
- "completion_tokens_details", {}
+ scope._cache_creation_input_tokens = (
+ usage.get("completion_tokens_details") or {}
).get("cached_tokens", 0)
scope._end_time = time.time()
@@ -465,7 +470,8 @@ def common_chat_logic(
safe_get(scope._kwargs.get("presence_penalty"), 0.0),
)
scope._span.set_attribute(
- SemanticConvention.GEN_AI_REQUEST_STOP_SEQUENCES, scope._kwargs.get("stop", [])
+ SemanticConvention.GEN_AI_REQUEST_STOP_SEQUENCES,
+ safe_get(scope._kwargs.get("stop"), []),
)
scope._span.set_attribute(
SemanticConvention.GEN_AI_REQUEST_TEMPERATURE,
@@ -478,23 +484,40 @@ def common_chat_logic(
scope._span.set_attribute(
SemanticConvention.GEN_AI_REQUEST_USER, safe_get(scope._kwargs.get("user"), "")
)
- scope._span.set_attribute(
- SemanticConvention.GEN_AI_REQUEST_SERVICE_TIER,
- safe_get(scope._kwargs.get("service_tier"), "auto"),
+
+ # OpenAI-specific attributes: only set for OpenAI-compatible providers
+ provider_prefix = request_model.split("/", 1)[0] if "/" in request_model else ""
+ is_openai_compatible = provider_prefix in (
+ "openai",
+ "azure",
+ "azure_text",
+ "azure_ai",
+ "",
)
+ if is_openai_compatible:
+ scope._span.set_attribute(
+ SemanticConvention.GEN_AI_REQUEST_SERVICE_TIER,
+ safe_get(scope._kwargs.get("service_tier"), "auto"),
+ )
# Span Attributes for Response parameters
- scope._span.set_attribute(SemanticConvention.GEN_AI_RESPONSE_ID, scope._response_id)
- scope._span.set_attribute(
- SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON, [scope._finish_reason or ""]
- )
- scope._span.set_attribute(
- SemanticConvention.GEN_AI_RESPONSE_SERVICE_TIER, scope._response_service_tier
- )
scope._span.set_attribute(
- SemanticConvention.GEN_AI_RESPONSE_SYSTEM_FINGERPRINT,
- scope._response_service_tier,
+ SemanticConvention.GEN_AI_RESPONSE_ID, scope._response_id or ""
)
+ if scope._finish_reason:
+ scope._span.set_attribute(
+ SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON,
+ [scope._finish_reason.lower()],
+ )
+ if is_openai_compatible:
+ scope._span.set_attribute(
+ SemanticConvention.GEN_AI_RESPONSE_SERVICE_TIER,
+ scope._response_service_tier,
+ )
+ scope._span.set_attribute(
+ SemanticConvention.GEN_AI_RESPONSE_SYSTEM_FINGERPRINT,
+ scope._response_system_fingerprint,
+ )
scope._span.set_attribute(
SemanticConvention.GEN_AI_OUTPUT_TYPE,
"text" if isinstance(scope._llmresponse, str) else "json",
@@ -569,7 +592,9 @@ def common_chat_logic(
tool_defs = build_tool_definitions(scope._kwargs.get("tools"))
extra = {
"response_id": scope._response_id,
- "finish_reasons": [scope._finish_reason],
+ "finish_reasons": [scope._finish_reason.lower()]
+ if scope._finish_reason
+ else None,
"output_type": "text"
if isinstance(scope._llmresponse, str)
else "json",
@@ -701,19 +726,23 @@ def process_chat_response(
# Handle token usage including reasoning tokens and cached tokens
scope._input_tokens = usage.get("prompt_tokens", 0)
scope._output_tokens = usage.get("completion_tokens", 0)
- prompt_tokens_details = usage.get(
- "prompt_tokens_details", usage.get("input_tokens_details", {})
+ prompt_tokens_details = (
+ usage.get("prompt_tokens_details", usage.get("input_tokens_details", {})) or {}
)
scope._cache_read_input_tokens = prompt_tokens_details.get("cached_tokens", 0)
- scope._cache_creation_input_tokens = usage.get("completion_tokens_details", {}).get(
- "cached_tokens", 0
+ scope._cache_creation_input_tokens = (
+ usage.get("completion_tokens_details") or {}
+ ).get("cached_tokens", 0)
+ scope._response_id = response_dict.get("id") or ""
+ scope._response_model = response_dict.get("model") or ""
+ choices = response_dict.get("choices", [])
+ first_choice = choices[0] if choices else {}
+ raw_fr = first_choice.get("finish_reason")
+ scope._finish_reason = str(raw_fr).lower() if raw_fr else ""
+ scope._response_service_tier = str(response_dict.get("service_tier") or "")
+ scope._response_system_fingerprint = str(
+ response_dict.get("system_fingerprint") or ""
)
- scope._response_id = response_dict.get("id")
- scope._response_model = response_dict.get("model")
- scope._finish_reason = str(
- response_dict.get("choices", [])[0].get("finish_reason", "")
- )
- scope._response_service_tier = str(response_dict.get("system_fingerprint", ""))
scope._timestamps = []
scope._ttft, scope._tbt = scope._end_time - scope._start_time, 0
scope._server_address, scope._server_port = server_address, server_port
@@ -721,9 +750,7 @@ def process_chat_response(
# Handle tool calls
if scope._kwargs.get("tools"):
- scope._tools = (
- response_dict.get("choices", [{}])[0].get("message", {}).get("tool_calls")
- )
+ scope._tools = first_choice.get("message", {}).get("tool_calls")
else:
scope._tools = None
@@ -772,7 +799,7 @@ def process_embedding_response(
scope._end_time = time.time()
scope._span = span
scope._input_tokens = response_dict.get("usage", {}).get("prompt_tokens", 0)
- scope._response_model = response_dict.get("model")
+ scope._response_model = response_dict.get("model") or ""
scope._server_address, scope._server_port = server_address, server_port
scope._kwargs = kwargs
diff --git a/sdk/python/src/openlit/instrumentation/openai_agents/__init__.py b/sdk/python/src/openlit/instrumentation/openai_agents/__init__.py
index 1d44f874..7331fd42 100644
--- a/sdk/python/src/openlit/instrumentation/openai_agents/__init__.py
+++ b/sdk/python/src/openlit/instrumentation/openai_agents/__init__.py
@@ -2,15 +2,120 @@
OpenLIT OpenAI Agents Instrumentation
"""
+import json
+import threading
from typing import Collection
import importlib.metadata
+
from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from opentelemetry.trace import SpanKind
+from wrapt import wrap_function_wrapper
+from openlit.__helpers import handle_exception
+from openlit.semcov import SemanticConvention
from openlit.instrumentation.openai_agents.processor import OpenLITTracingProcessor
_instruments = ("openai-agents >= 0.0.3",)
+class _AgentCreationRegistry:
+ """Thread-safe registry mapping agent name -> SpanContext from create_agent spans.
+
+ Used to provide span links from invoke_agent back to create_agent,
+ matching the pattern used in CrewAI and LangGraph instrumentations.
+ """
+
+ def __init__(self):
+ self._lock = threading.Lock()
+ self._contexts: dict = {}
+
+ def register(self, agent_name, span_context):
+ """Store the span context for a given agent name."""
+ with self._lock:
+ self._contexts[agent_name] = span_context
+
+ def get(self, agent_name):
+ """Retrieve the span context for a given agent name, or ``None``."""
+ with self._lock:
+ return self._contexts.get(agent_name)
+
+
+def _wrap_agent_init(
+ tracer, environment, application_name, capture_message_content, registry
+):
+ """Return a wrapt wrapper for ``Agent.__init__`` that emits a
+ ``create_agent`` span per agent construction."""
+
+ def wrapper(wrapped, instance, args, kwargs):
+ result = wrapped(*args, **kwargs)
+
+ try:
+ name = getattr(instance, "name", None) or "agent"
+ span_name = f"create_agent {name}"
+
+ with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OPERATION,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,
+ )
+ span.set_attribute(
+ SemanticConvention.GEN_AI_PROVIDER_NAME,
+ SemanticConvention.GEN_AI_SYSTEM_OPENAI,
+ )
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(name))
+
+ model = getattr(instance, "model", None)
+ if model:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_REQUEST_MODEL, str(model)
+ )
+
+ instructions = getattr(instance, "instructions", None)
+ if instructions and capture_message_content:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS,
+ str(instructions)[:4096],
+ )
+
+ tools = getattr(instance, "tools", None)
+ if tools:
+ tool_defs = []
+ for t in tools[:20]:
+ t_name = getattr(t, "name", None) or getattr(
+ t, "__name__", str(t)
+ )
+ tool_defs.append({"type": "function", "name": str(t_name)})
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_DEFINITIONS,
+ json.dumps(tool_defs),
+ )
+
+ handoffs = getattr(instance, "handoffs", None)
+ if handoffs:
+ handoff_names = []
+ for h in handoffs[:20]:
+ h_name = getattr(h, "name", None) or str(h)
+ handoff_names.append(str(h_name))
+ span.set_attribute(
+ "gen_ai.agent.handoffs", json.dumps(handoff_names)
+ )
+
+ span.set_attribute(SemanticConvention.GEN_AI_ENVIRONMENT, environment)
+ span.set_attribute(
+ SemanticConvention.GEN_AI_APPLICATION_NAME, application_name
+ )
+
+ creation_ctx = span.get_span_context()
+ instance._openlit_creation_context = creation_ctx
+ registry.register(str(name), creation_ctx)
+ except Exception as e:
+ handle_exception(None, e)
+
+ return result
+
+ return wrapper
+
+
class OpenAIAgentsInstrumentor(BaseInstrumentor):
"""OpenLIT instrumentor for OpenAI Agents using native tracing system"""
@@ -28,6 +133,25 @@ class OpenAIAgentsInstrumentor(BaseInstrumentor):
disable_metrics = kwargs.get("disable_metrics")
detailed_tracing = kwargs.get("detailed_tracing", False)
+ # Shared registry: create_agent span contexts keyed by agent name
+ agent_registry = _AgentCreationRegistry()
+
+ # Wrap Agent.__init__ to emit create_agent spans
+ try:
+ wrap_function_wrapper(
+ "agents",
+ "Agent.__init__",
+ _wrap_agent_init(
+ tracer,
+ environment,
+ application_name,
+ capture_message_content,
+ agent_registry,
+ ),
+ )
+ except Exception:
+ pass
+
# Create our processor with OpenLIT enhancements
processor = OpenLITTracingProcessor(
tracer=tracer,
@@ -39,25 +163,23 @@ class OpenAIAgentsInstrumentor(BaseInstrumentor):
metrics=metrics,
disable_metrics=disable_metrics,
detailed_tracing=detailed_tracing,
+ agent_creation_registry=agent_registry,
)
# Integrate with OpenAI Agents' native tracing system
try:
from agents import set_trace_processors
- # Replace existing processors with our enhanced processor
set_trace_processors([processor])
except ImportError:
- # Fallback: Add our processor to existing ones
try:
from agents import add_trace_processor
add_trace_processor(processor)
except ImportError:
- pass # Agents package may not have tracing
+ pass
def _uninstrument(self, **kwargs):
- # Clear our processors
try:
from agents import set_trace_processors
diff --git a/sdk/python/src/openlit/instrumentation/openai_agents/processor.py b/sdk/python/src/openlit/instrumentation/openai_agents/processor.py
index 8964db5e..7e915cc6 100644
--- a/sdk/python/src/openlit/instrumentation/openai_agents/processor.py
+++ b/sdk/python/src/openlit/instrumentation/openai_agents/processor.py
@@ -1,21 +1,33 @@
"""
OpenLIT OpenAI Agents Instrumentation - Native TracingProcessor Implementation
+
+Integrates with the OpenAI Agents SDK ``TracingProcessor`` interface.
+All span data fields are read at ``on_span_end`` (when fully populated).
+Compliant with OTel GenAI semantic conventions (gen-ai-spans.md,
+gen-ai-agent-spans.md).
"""
import time
-from typing import Any, Dict, TYPE_CHECKING
+import threading
+from collections import OrderedDict
+from typing import Any, TYPE_CHECKING
-from opentelemetry.trace import SpanKind, Status, StatusCode, set_span_in_context
+from opentelemetry import context as context_api
+from opentelemetry.trace import SpanKind, Status, StatusCode, Link, set_span_in_context
from openlit.__helpers import (
common_framework_span_attributes,
handle_exception,
- get_chat_model_cost,
- truncate_content,
)
from openlit.semcov import SemanticConvention
+from openlit.instrumentation.openai_agents.utils import (
+ get_operation_type,
+ get_span_kind,
+ generate_span_name,
+ is_detailed_only,
+ process_span_end,
+)
-# Try to import agents framework components with fallback
try:
from agents import TracingProcessor
@@ -23,33 +35,33 @@ try:
from agents import Trace, Span
TRACING_AVAILABLE = True
except ImportError:
- # Create dummy class for when agents is not available
+
class TracingProcessor:
- """Dummy TracingProcessor class for when agents is not available"""
+ """Dummy TracingProcessor for when agents is not available."""
def force_flush(self):
- """Dummy force_flush method"""
+ """No-op flush for the dummy processor."""
return None
def shutdown(self):
- """Dummy shutdown method"""
+ """No-op shutdown for the dummy processor."""
return None
if TYPE_CHECKING:
- # Type hints only - these don't exist at runtime when agents unavailable
Trace = Any
Span = Any
TRACING_AVAILABLE = False
+_MAX_HANDOFFS = 1000
+
class OpenLITTracingProcessor(TracingProcessor):
"""
- OpenAI Agents tracing processor that integrates with OpenLIT observability.
+ OpenAI Agents tracing processor that emits OTel GenAI-compliant spans.
- This processor enhances OpenAI Agents' native tracing system with OpenLIT's
- comprehensive observability features including business intelligence,
- cost tracking, and performance metrics.
+ Thread-safety: internal dicts are protected by a lock; no shared list
+ (``span_stack``) is used.
"""
def __init__(
@@ -63,12 +75,11 @@ class OpenLITTracingProcessor(TracingProcessor):
metrics,
disable_metrics,
detailed_tracing,
+ agent_creation_registry=None,
**kwargs,
):
- """Initialize the OpenLIT tracing processor."""
super().__init__()
- # Core configuration
self.tracer = tracer
self.version = version
self.environment = environment
@@ -78,401 +89,270 @@ class OpenLITTracingProcessor(TracingProcessor):
self.metrics = metrics
self.disable_metrics = disable_metrics
self.detailed_tracing = detailed_tracing
-
- # Internal tracking
- self.active_spans = {}
- self.span_stack = []
-
- def start_trace(self, trace_id: str, name: str, **kwargs):
- """
- Start a new trace with OpenLIT enhancements.
-
- Args:
- trace_id: Unique trace identifier
- name: Trace name
- **kwargs: Additional trace metadata
- """
- try:
- # Generate span name using OpenTelemetry conventions
- span_name = self._get_span_name(name, **kwargs)
-
- # Start root span with OpenLIT context
- span = self.tracer.start_as_current_span(
- span_name,
- kind=SpanKind.CLIENT,
- attributes={
- SemanticConvention.GEN_AI_PROVIDER_NAME: "openai_agents",
- SemanticConvention.GEN_AI_OPERATION: SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,
- "trace.id": trace_id,
- "trace.name": name,
- },
- )
-
- # Create scope for common attributes
- scope = type("GenericScope", (), {})()
- scope._span = span # pylint: disable=protected-access
- scope._start_time = time.time() # pylint: disable=protected-access
- scope._end_time = None # pylint: disable=protected-access
-
- # Apply common framework attributes
- common_framework_span_attributes(
- scope,
- "openai_agents",
- "api.openai.com",
- 443,
- self.environment,
- self.application_name,
- self.version,
- name,
- )
-
- # Track active span
- self.active_spans[trace_id] = span
- self.span_stack.append(span)
-
- return span
-
- except Exception as e: # pylint: disable=broad-exception-caught
- # Graceful degradation
- handle_exception(None, e)
- return None
-
- def end_trace(self, trace_id: str, **kwargs):
- """
- End an active trace.
-
- Args:
- trace_id: Trace identifier to end
- **kwargs: Additional metadata
- """
+ self._agent_creation_registry = agent_creation_registry
+
+ self._lock = threading.Lock()
+ # SDK span_id -> (otel_span, start_time, ctx, context_token)
+ self._otel_spans: dict = {}
+ # SDK trace_id -> (otel_span, start_time, ctx, context_token)
+ self._root_spans: dict = {}
+ # trace_id -> group_id (conversation id)
+ self._trace_group_ids: dict = {}
+ # Agent handoff tracker (bounded OrderedDict)
+ self._handoff_tracker: OrderedDict = OrderedDict()
+
+ # ------------------------------------------------------------------
+ # Trace lifecycle
+ # ------------------------------------------------------------------
+ def on_trace_start(self, trace): # pylint: disable=missing-function-docstring
try:
- span = self.active_spans.get(trace_id)
- if span:
- # Set final attributes and status
- span.set_status(Status(StatusCode.OK))
+ trace_id = getattr(trace, "trace_id", "unknown")
+ trace_name = getattr(trace, "name", "workflow")
+ group_id = getattr(trace, "group_id", None)
- # End span
- span.end()
-
- # Cleanup tracking
- if trace_id in self.active_spans:
- del self.active_spans[trace_id]
- if span in self.span_stack:
- self.span_stack.remove(span)
-
- except Exception as e: # pylint: disable=broad-exception-caught
- handle_exception(span if span else None, e)
-
- def _get_span_name(self, operation_name: str, **metadata) -> str:
- """
- Generate OpenTelemetry-compliant span names.
-
- Args:
- operation_name: Base operation name
- **metadata: Additional context for naming
-
- Returns:
- Formatted span name following semantic conventions
- """
- # Extract context for naming
- agent_name = metadata.get("agent_name", "")
- model_name = metadata.get("model_name", "")
- tool_name = metadata.get("tool_name", "")
- workflow_name = metadata.get("workflow_name", "")
-
- # Apply OpenTelemetry semantic conventions for GenAI agents
- if "agent" in operation_name.lower():
- if agent_name:
- return f"invoke_agent {agent_name}"
- return "invoke_agent"
- if "chat" in operation_name.lower():
- if model_name:
- return f"chat {model_name}"
- return "chat response"
- if "tool" in operation_name.lower():
- if tool_name:
- return f"execute_tool {tool_name}"
- return "execute_tool"
- if "handoff" in operation_name.lower():
- target_agent = metadata.get("target_agent", "unknown")
- return f"invoke_agent {target_agent}"
- if "workflow" in operation_name.lower():
- if workflow_name:
- return f"invoke_workflow {workflow_name}"
- return "invoke_workflow"
-
- # Default case
- return operation_name
-
- def span_start(self, span_data, trace_id: str):
- """
- Handle span start events from OpenAI Agents.
-
- Args:
- span_data: Span data from agents framework
- trace_id: Associated trace identifier
- """
- try:
- # Extract span information
- span_name = getattr(span_data, "name", "unknown_operation")
- span_type = getattr(span_data, "type", "unknown")
+ operation = SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK
+ span_name = f"{operation} {trace_name}"
- # Generate enhanced span name
- enhanced_name = self._get_span_name(
+ span = self.tracer.start_span(
span_name,
- agent_name=getattr(span_data, "agent_name", None),
- model_name=getattr(span_data, "model_name", None),
- tool_name=getattr(span_data, "tool_name", None),
- )
-
- # Determine span operation type
- operation_type = self._get_operation_type(span_type, span_name)
-
- # Start span with proper context
- parent_span = self.span_stack[-1] if self.span_stack else None
- context = set_span_in_context(parent_span) if parent_span else None
-
- span = self.tracer.start_as_current_span(
- enhanced_name,
- kind=SpanKind.CLIENT,
- context=context,
+ kind=SpanKind.INTERNAL,
attributes={
- SemanticConvention.GEN_AI_PROVIDER_NAME: "openai_agents",
- SemanticConvention.GEN_AI_OPERATION: operation_type,
- "span.type": span_type,
- "span.id": getattr(span_data, "span_id", ""),
+ SemanticConvention.GEN_AI_OPERATION: operation,
+ SemanticConvention.GEN_AI_PROVIDER_NAME: SemanticConvention.GEN_AI_SYSTEM_OPENAI,
},
)
- # Process specific span types
- self._process_span_attributes(span, span_data, span_type)
+ start_time = time.time()
+ ctx = set_span_in_context(span)
+ token = context_api.attach(ctx)
- # Track span
- span_id = getattr(span_data, "span_id", len(self.span_stack))
- self.active_spans[f"{trace_id}:{span_id}"] = span
- self.span_stack.append(span)
+ with self._lock:
+ self._root_spans[trace_id] = (span, start_time, ctx, token)
+ if group_id:
+ self._trace_group_ids[trace_id] = str(group_id)
- except Exception as e: # pylint: disable=broad-exception-caught
+ except Exception as e:
handle_exception(None, e)
- def _get_operation_type(self, span_type: str, span_name: str) -> str:
- """Get operation type based on span characteristics."""
- type_mapping = {
- "agent": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
- "generation": SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
- "function": SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
- "tool": SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
- "handoff": SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
- }
-
- # Check span type first
- for key, operation in type_mapping.items():
- if key in span_type.lower():
- return operation
-
- # Check span name
- for key, operation in type_mapping.items():
- if key in span_name.lower():
- return operation
-
- return SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT
-
- def _process_span_attributes(self, span, span_data, span_type: str):
- """Process and set span attributes based on span type."""
+ def on_trace_end(self, trace): # pylint: disable=missing-function-docstring
try:
- # Common attributes
- if hasattr(span_data, "agent_name"):
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_NAME, span_data.agent_name
- )
-
- if hasattr(span_data, "model_name"):
- span.set_attribute(
- SemanticConvention.GEN_AI_REQUEST_MODEL, span_data.model_name
- )
-
- # Agent-specific attributes
- if span_type == "agent":
- self._process_agent_span(span, span_data)
+ trace_id = getattr(trace, "trace_id", "unknown")
+ trace_name = getattr(trace, "name", "workflow")
+ group_id = None
- # Generation-specific attributes
- elif span_type == "generation":
- self._process_generation_span(span, span_data)
+ with self._lock:
+ entry = self._root_spans.pop(trace_id, None)
+ group_id = self._trace_group_ids.pop(trace_id, None)
- # Function/Tool-specific attributes
- elif span_type in ["function", "tool"]:
- self._process_function_span(span, span_data)
+ if entry is None:
+ return
- # Handoff-specific attributes
- elif span_type == "handoff":
- self._process_handoff_span(span, span_data)
+ span, start_time, _ctx, token = entry
+ end_time = time.time()
- except Exception as e: # pylint: disable=broad-exception-caught
- handle_exception(span, e)
+ scope = type("Scope", (), {})()
+ scope._span = span
+ scope._start_time = start_time
+ scope._end_time = end_time
- def _process_agent_span(self, span, agent_span):
- """Process agent span data (unused parameter)."""
- # Agent-specific processing
- if hasattr(agent_span, "instructions"):
- span.set_attribute(
- SemanticConvention.GEN_AI_AGENT_DESCRIPTION,
- truncate_content(agent_span.instructions),
+ common_framework_span_attributes(
+ scope,
+ SemanticConvention.GEN_AI_SYSTEM_OPENAI,
+ "api.openai.com",
+ 443,
+ self.environment,
+ self.application_name,
+ self.version,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,
)
- if hasattr(agent_span, "model"):
span.set_attribute(
- SemanticConvention.GEN_AI_REQUEST_MODEL, agent_span.model
+ SemanticConvention.GEN_AI_OPERATION,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,
)
-
- def _process_generation_span(self, span, generation_span):
- """Process generation span data."""
- # Set generation-specific attributes
- if hasattr(generation_span, "prompt"):
span.set_attribute(
- SemanticConvention.GEN_AI_PROMPT,
- truncate_content(generation_span.prompt),
+ SemanticConvention.GEN_AI_PROVIDER_NAME,
+ SemanticConvention.GEN_AI_SYSTEM_OPENAI,
)
+ span.set_attribute(SemanticConvention.GEN_AI_WORKFLOW_NAME, trace_name)
- if hasattr(generation_span, "completion"):
- span.set_attribute(
- SemanticConvention.GEN_AI_COMPLETION,
- truncate_content(generation_span.completion),
- )
+ if group_id:
+ span.set_attribute(SemanticConvention.GEN_AI_CONVERSATION_ID, group_id)
- if hasattr(generation_span, "usage"):
- usage = generation_span.usage
- if hasattr(usage, "prompt_tokens"):
- span.set_attribute(
- SemanticConvention.GEN_AI_USAGE_PROMPT_TOKENS, usage.prompt_tokens
+ error = getattr(trace, "error", None)
+ if error:
+ error_msg = (
+ error.get("message", "unknown")
+ if isinstance(error, dict)
+ else str(error)
)
- if hasattr(usage, "completion_tokens"):
- span.set_attribute(
- SemanticConvention.GEN_AI_USAGE_COMPLETION_TOKENS,
- usage.completion_tokens,
+ span.set_attribute(SemanticConvention.ERROR_TYPE, error_msg)
+ span.set_status(Status(StatusCode.ERROR, error_msg))
+ else:
+ span.set_status(Status(StatusCode.OK))
+
+ if not self.disable_metrics and self.metrics:
+ from openlit.instrumentation.openai_agents.utils import _record_metrics
+
+ _record_metrics(
+ self.metrics,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,
+ end_time - start_time,
+ self.environment,
+ self.application_name,
+ None,
+ "api.openai.com",
+ 443,
)
- def _process_function_span(self, span, function_span):
- """Process function/tool span data."""
- if hasattr(function_span, "function_name"):
- span.set_attribute(
- SemanticConvention.GEN_AI_TOOL_NAME, function_span.function_name
- )
+ if token is not None:
+ context_api.detach(token)
- if hasattr(function_span, "arguments"):
- span.set_attribute(
- "gen_ai.tool.arguments", truncate_content(function_span.arguments)
- )
+ span.end()
- if hasattr(function_span, "result"):
- span.set_attribute(
- "gen_ai.tool.result", truncate_content(function_span.result)
- )
-
- def _process_handoff_span(self, span, handoff_span):
- """Process handoff span data."""
- if hasattr(handoff_span, "target_agent"):
- span.set_attribute("gen_ai.handoff.target_agent", handoff_span.target_agent)
+ except Exception as e:
+ handle_exception(None, e)
- if hasattr(handoff_span, "reason"):
- span.set_attribute(
- "gen_ai.handoff.reason", truncate_content(handoff_span.reason)
- )
+ # ------------------------------------------------------------------
+ # Span lifecycle
+ # ------------------------------------------------------------------
+ # LLM span types handled by the OpenAI SDK instrumentation, which
+ # produces richer telemetry (events, cost, TTFT, streaming flags, etc.).
+ _LLM_SPAN_TYPES = frozenset(("response", "generation"))
- def span_end(self, span_data, trace_id: str):
- """Handle span end events."""
+ def on_span_start(self, span): # pylint: disable=missing-function-docstring
try:
- span_id = getattr(span_data, "span_id", "")
- span_key = f"{trace_id}:{span_id}"
-
- span = self.active_spans.get(span_key)
- if span:
- # Set final status
- if hasattr(span_data, "error") and span_data.error:
- span.set_status(Status(StatusCode.ERROR, str(span_data.error)))
- else:
- span.set_status(Status(StatusCode.OK))
-
- # End span
- span.end()
-
- # Cleanup
- if span_key in self.active_spans:
- del self.active_spans[span_key]
- if span in self.span_stack:
- self.span_stack.remove(span)
+ sdk_span = span
+ span_data = sdk_span.span_data
+ span_type = getattr(span_data, "type", "unknown")
- except Exception as e: # pylint: disable=broad-exception-caught
- handle_exception(span if "span" in locals() else None, e)
+ if span_type in self._LLM_SPAN_TYPES:
+ return
+
+ if is_detailed_only(span_type) and not self.detailed_tracing:
+ return
+
+ trace_id = getattr(sdk_span, "trace_id", "unknown")
+ sdk_span_id = getattr(sdk_span, "span_id", None)
+ parent_sdk_id = getattr(sdk_span, "parent_id", None)
+
+ operation = get_operation_type(span_type)
+ kind = get_span_kind(operation)
+ span_name = generate_span_name(span_data)
+
+ # Find parent OTel span context
+ parent_ctx = None
+ with self._lock:
+ if parent_sdk_id and parent_sdk_id in self._otel_spans:
+ parent_otel, _, _, _ = self._otel_spans[parent_sdk_id]
+ parent_ctx = set_span_in_context(parent_otel)
+ elif trace_id in self._root_spans:
+ _, _, parent_ctx, _ = self._root_spans[trace_id]
+
+ # Span links: connect invoke_agent back to create_agent
+ links = []
+ if span_type == "agent" and self._agent_creation_registry:
+ agent_name = getattr(span_data, "name", None)
+ if agent_name:
+ creation_ctx = self._agent_creation_registry.get(str(agent_name))
+ if creation_ctx:
+ links.append(Link(creation_ctx))
+
+ otel_span = self.tracer.start_span(
+ span_name,
+ kind=kind,
+ context=parent_ctx,
+ links=links,
+ attributes={
+ SemanticConvention.GEN_AI_OPERATION: operation,
+ SemanticConvention.GEN_AI_PROVIDER_NAME: SemanticConvention.GEN_AI_SYSTEM_OPENAI,
+ },
+ )
- def force_flush(self):
- """Force flush all pending spans."""
- try:
- # End any remaining spans
- for span in list(self.active_spans.values()):
- span.end()
+ start_time = time.time()
+ ctx = set_span_in_context(otel_span)
+ token = context_api.attach(ctx)
- self.active_spans.clear()
- self.span_stack.clear()
+ if sdk_span_id:
+ with self._lock:
+ self._otel_spans[sdk_span_id] = (otel_span, start_time, ctx, token)
- except Exception as e: # pylint: disable=broad-exception-caught
+ except Exception as e:
handle_exception(None, e)
- def shutdown(self):
- """Shutdown the processor."""
- self.force_flush()
-
- def _extract_model_info(self, span_data) -> Dict[str, Any]:
- """Extract model information from span data."""
- model_info = {}
-
- if hasattr(span_data, "model"):
- model_info["model"] = span_data.model
- if hasattr(span_data, "model_name"):
- model_info["model"] = span_data.model_name
-
- return model_info
-
- def _calculate_cost(
- self, model: str, prompt_tokens: int, completion_tokens: int
- ) -> float:
- """Calculate cost based on token usage."""
+ def on_span_end(self, span): # pylint: disable=missing-function-docstring
try:
- return get_chat_model_cost(
- model, self.pricing_info, prompt_tokens, completion_tokens
- )
- except Exception: # pylint: disable=broad-exception-caught
- return 0.0
+ sdk_span = span
+ span_data = sdk_span.span_data
+ span_type = getattr(span_data, "type", "unknown")
- # Abstract method implementations required by OpenAI Agents framework
- def on_trace_start(self, trace):
- """Called when a trace starts - required by OpenAI Agents framework"""
- try:
- self.start_trace(
- getattr(trace, "trace_id", "unknown"),
- getattr(trace, "name", "workflow"),
+ if span_type in self._LLM_SPAN_TYPES:
+ return
+
+ if is_detailed_only(span_type) and not self.detailed_tracing:
+ return
+
+ sdk_span_id = getattr(sdk_span, "span_id", None)
+ trace_id = getattr(sdk_span, "trace_id", "unknown")
+
+ entry = None
+ with self._lock:
+ entry = self._otel_spans.pop(sdk_span_id, None) if sdk_span_id else None
+ conversation_id = self._trace_group_ids.get(trace_id)
+
+ if entry is None:
+ return
+
+ otel_span, start_time, _ctx, token = entry
+
+ process_span_end(
+ otel_span=otel_span,
+ sdk_span=sdk_span,
+ start_time=start_time,
+ version=self.version,
+ environment=self.environment,
+ application_name=self.application_name,
+ capture_message_content=self.capture_message_content,
+ metrics=self.metrics,
+ disable_metrics=self.disable_metrics,
+ conversation_id=conversation_id,
+ handoff_tracker=self._handoff_tracker,
)
- except Exception: # pylint: disable=broad-exception-caught
- pass
- def on_trace_end(self, trace):
- """Called when a trace ends - required by OpenAI Agents framework"""
- try:
- self.end_trace(getattr(trace, "trace_id", "unknown"))
- except Exception: # pylint: disable=broad-exception-caught
- pass
+ if token is not None:
+ context_api.detach(token)
- def on_span_start(self, span):
- """Called when a span starts - required by OpenAI Agents framework"""
- try:
- trace_id = getattr(span, "trace_id", "unknown")
- self.span_start(span, trace_id)
- except Exception: # pylint: disable=broad-exception-caught
- pass
+ otel_span.end()
+
+ except Exception as e:
+ handle_exception(None, e)
- def on_span_end(self, span):
- """Called when a span ends - required by OpenAI Agents framework"""
+ # ------------------------------------------------------------------
+ # Lifecycle management
+ # ------------------------------------------------------------------
+ def force_flush(self):
try:
- trace_id = getattr(span, "trace_id", "unknown")
- self.span_end(span, trace_id)
- except Exception: # pylint: disable=broad-exception-caught
- pass
+ with self._lock:
+ for otel_span, _, _, token in self._otel_spans.values():
+ try:
+ if token is not None:
+ context_api.detach(token)
+ otel_span.end()
+ except Exception:
+ pass
+ self._otel_spans.clear()
+
+ for otel_span, _, _, token in self._root_spans.values():
+ try:
+ if token is not None:
+ context_api.detach(token)
+ otel_span.end()
+ except Exception:
+ pass
+ self._root_spans.clear()
+ self._trace_group_ids.clear()
+ except Exception as e:
+ handle_exception(None, e)
+
+ def shutdown(self):
+ self.force_flush()
diff --git a/sdk/python/src/openlit/instrumentation/openai_agents/utils.py b/sdk/python/src/openlit/instrumentation/openai_agents/utils.py
new file mode 100644
index 00000000..fb338149
--- /dev/null
+++ b/sdk/python/src/openlit/instrumentation/openai_agents/utils.py
@@ -0,0 +1,714 @@
+"""
+OpenAI Agents utilities for OTel GenAI semantic convention compliant telemetry.
+
+Follows the same patterns as the CrewAI / LangGraph instrumentations.
+All operation names, span kinds, and attributes comply with the OTel GenAI
+semantic conventions (gen-ai-spans.md, gen-ai-agent-spans.md).
+
+The OpenAI Agents SDK reports span data via TracingProcessor callbacks.
+Span data fields are populated *during* execution and are only fully
+available at ``on_span_end`` -- all attribute setting therefore happens
+in ``process_span_end``.
+"""
+
+import json
+import time
+from opentelemetry.trace import SpanKind, Status, StatusCode
+
+from openlit.__helpers import (
+ common_framework_span_attributes,
+ handle_exception,
+ truncate_content,
+)
+from openlit.semcov import SemanticConvention
+
+# ---------------------------------------------------------------------------
+# OTel GenAI operation mapping (SDK span_data.type -> gen_ai.operation.name)
+# ---------------------------------------------------------------------------
+OPERATION_MAP = {
+ "agent": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ "generation": SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ "response": SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ "function": SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
+ "handoff": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ "guardrail": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ "custom": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ "transcription": SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ "speech": SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ "speech_group": SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,
+ "mcp_tools": SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
+}
+
+# ---------------------------------------------------------------------------
+# SpanKind per operation (OTel GenAI spec)
+# ---------------------------------------------------------------------------
+SPAN_KIND_MAP = {
+ SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK: SpanKind.INTERNAL,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT: SpanKind.INTERNAL,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS: SpanKind.INTERNAL,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT: SpanKind.CLIENT,
+}
+
+_DETAILED_SPAN_TYPES = frozenset(
+ {"custom", "transcription", "speech", "speech_group", "mcp_tools"}
+)
+
+_MAX_HANDOFFS = 1000
+
+
+def get_operation_type(span_type):
+ """Return the standard ``gen_ai.operation.name`` for an SDK span type."""
+ return OPERATION_MAP.get(span_type, SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT)
+
+
+def get_span_kind(operation_type):
+ """Return the correct ``SpanKind`` per OTel GenAI spec."""
+ return SPAN_KIND_MAP.get(operation_type, SpanKind.INTERNAL)
+
+
+def generate_span_name(span_data):
+ """Return an OTel-compliant span name: ``{operation} {entity}``."""
+ span_type = getattr(span_data, "type", "unknown")
+ operation = get_operation_type(span_type)
+
+ if span_type == "agent":
+ name = getattr(span_data, "name", None) or "agent"
+ return f"{operation} {name}"
+
+ if span_type in ("generation", "response"):
+ model = _extract_model_from_span_data(span_data)
+ if model:
+ return f"{operation} {model}"
+ return operation
+
+ if span_type == "function":
+ name = getattr(span_data, "name", None) or "function"
+ return f"{operation} {name}"
+
+ if span_type == "handoff":
+ to_agent = getattr(span_data, "to_agent", None) or "unknown"
+ return f"{operation} {to_agent}"
+
+ if span_type == "guardrail":
+ name = getattr(span_data, "name", None) or "guardrail"
+ return f"{operation} {name}"
+
+ if span_type == "mcp_tools":
+ server = getattr(span_data, "server", None) or "mcp"
+ return f"{operation} {server}"
+
+ if span_type == "transcription":
+ return f"{operation} transcription"
+
+ if span_type == "speech":
+ return f"{operation} speech"
+
+ if span_type == "speech_group":
+ return f"{operation} speech_group"
+
+ if span_type == "custom":
+ name = getattr(span_data, "name", None) or "custom"
+ return f"{operation} {name}"
+
+ return operation
+
+
+def is_detailed_only(span_type):
+ """Return True if *span_type* should only be traced under detailed_tracing."""
+ return span_type in _DETAILED_SPAN_TYPES
+
+
+# ---------------------------------------------------------------------------
+# Main dispatcher -- called from ``on_span_end``
+# ---------------------------------------------------------------------------
+def process_span_end(
+ otel_span,
+ sdk_span,
+ start_time,
+ version,
+ environment,
+ application_name,
+ capture_message_content,
+ metrics,
+ disable_metrics,
+ conversation_id,
+ handoff_tracker,
+):
+ """Set all OTel-compliant attributes on *otel_span* using fully-populated SDK data."""
+ try:
+ end_time = time.time()
+ span_data = sdk_span.span_data
+ span_type = getattr(span_data, "type", "unknown")
+ operation = get_operation_type(span_type)
+ model_name = _extract_model_from_span_data(span_data)
+
+ updated_name = generate_span_name(span_data)
+ try:
+ otel_span.update_name(updated_name)
+ except Exception:
+ pass
+
+ scope = type("Scope", (), {})()
+ scope._span = otel_span
+ scope._start_time = start_time
+ scope._end_time = end_time
+
+ server_address = "api.openai.com"
+ server_port = 443
+
+ model_proxy = (
+ type("P", (), {"model_name": model_name})() if model_name else None
+ )
+
+ common_framework_span_attributes(
+ scope,
+ SemanticConvention.GEN_AI_SYSTEM_OPENAI,
+ server_address,
+ server_port,
+ environment,
+ application_name,
+ version,
+ span_type,
+ model_proxy,
+ )
+
+ otel_span.set_attribute(SemanticConvention.GEN_AI_OPERATION, operation)
+ otel_span.set_attribute(
+ SemanticConvention.GEN_AI_PROVIDER_NAME,
+ SemanticConvention.GEN_AI_SYSTEM_OPENAI,
+ )
+
+ if conversation_id:
+ otel_span.set_attribute(
+ SemanticConvention.GEN_AI_CONVERSATION_ID, conversation_id
+ )
+
+ if model_name:
+ otel_span.set_attribute(SemanticConvention.GEN_AI_REQUEST_MODEL, model_name)
+
+ # Dispatch to type-specific handler
+ if span_type == "agent":
+ _set_agent_attributes(otel_span, span_data, capture_message_content)
+ elif span_type == "response":
+ _set_response_attributes(otel_span, span_data, capture_message_content)
+ elif span_type == "generation":
+ _set_generation_attributes(otel_span, span_data, capture_message_content)
+ elif span_type == "function":
+ _set_function_attributes(otel_span, span_data, capture_message_content)
+ elif span_type == "handoff":
+ _set_handoff_attributes(
+ otel_span, span_data, handoff_tracker, getattr(sdk_span, "trace_id", "")
+ )
+ elif span_type == "guardrail":
+ _set_guardrail_attributes(otel_span, span_data)
+ elif span_type == "transcription":
+ _set_transcription_attributes(otel_span, span_data, capture_message_content)
+ elif span_type == "speech":
+ _set_speech_attributes(otel_span, span_data, capture_message_content)
+ elif span_type == "mcp_tools":
+ _set_mcp_tools_attributes(otel_span, span_data)
+ elif span_type == "custom":
+ _set_custom_attributes(otel_span, span_data)
+
+ # Error handling per OTel recording-errors spec
+ error = getattr(sdk_span, "error", None)
+ if error:
+ error_msg = (
+ error.get("message", "unknown")
+ if isinstance(error, dict)
+ else str(error)
+ )
+ otel_span.set_attribute(SemanticConvention.ERROR_TYPE, error_msg)
+ otel_span.set_status(Status(StatusCode.ERROR, error_msg))
+ else:
+ otel_span.set_status(Status(StatusCode.OK))
+
+ # Metrics
+ if not disable_metrics and metrics:
+ _record_metrics(
+ metrics,
+ operation,
+ end_time - start_time,
+ environment,
+ application_name,
+ model_name,
+ server_address,
+ server_port,
+ )
+
+ except Exception as e:
+ handle_exception(otel_span, e)
+
+
+# ---------------------------------------------------------------------------
+# Agent (invoke_agent)
+# ---------------------------------------------------------------------------
+def _set_agent_attributes(span, span_data, capture_message_content):
+ try:
+ name = getattr(span_data, "name", None)
+ if name:
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(name))
+
+ output_type = getattr(span_data, "output_type", None)
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_TYPE,
+ str(output_type)
+ if output_type
+ else SemanticConvention.GEN_AI_OUTPUT_TYPE_TEXT,
+ )
+
+ if capture_message_content:
+ tools = getattr(span_data, "tools", None)
+ if tools:
+ tool_defs = [{"type": "function", "name": t} for t in tools[:20]]
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_DEFINITIONS,
+ json.dumps(tool_defs),
+ )
+
+ handoffs = getattr(span_data, "handoffs", None)
+ if handoffs:
+ span.set_attribute(
+ "gen_ai.agent.handoffs", json.dumps(list(handoffs[:20]))
+ )
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Response (chat -- Response API, the primary LLM call type)
+# ---------------------------------------------------------------------------
+def _set_response_attributes(span, span_data, capture_message_content):
+ try:
+ response = getattr(span_data, "response", None)
+ if not response:
+ return
+
+ model = getattr(response, "model", None)
+ if model:
+ span.set_attribute(SemanticConvention.GEN_AI_REQUEST_MODEL, str(model))
+ span.set_attribute(SemanticConvention.GEN_AI_RESPONSE_MODEL, str(model))
+
+ resp_id = getattr(response, "id", None)
+ if resp_id:
+ span.set_attribute(SemanticConvention.GEN_AI_RESPONSE_ID, str(resp_id))
+
+ usage = getattr(response, "usage", None)
+ if usage:
+ input_tokens = getattr(usage, "input_tokens", None)
+ output_tokens = getattr(usage, "output_tokens", None)
+ if input_tokens is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, input_tokens
+ )
+ if output_tokens is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, output_tokens
+ )
+
+ # finish reasons from output items (OTel spec: string[] array)
+ output_items = getattr(response, "output", None)
+ if output_items:
+ finish_reasons = []
+ for item in output_items:
+ status = getattr(item, "status", None)
+ if status:
+ finish_reasons.append(str(status))
+ if finish_reasons:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON,
+ finish_reasons,
+ )
+
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_TYPE,
+ SemanticConvention.GEN_AI_OUTPUT_TYPE_TEXT,
+ )
+ span.set_attribute(SemanticConvention.SERVER_ADDRESS, "api.openai.com")
+ span.set_attribute(SemanticConvention.SERVER_PORT, 443)
+
+ if capture_message_content:
+ _capture_response_messages(span, span_data, response)
+
+ except Exception:
+ pass
+
+
+def _capture_response_messages(span, span_data, response):
+ """Capture input/output messages from ResponseSpanData."""
+ try:
+ raw_input = getattr(span_data, "input", None)
+ if raw_input:
+ if isinstance(raw_input, str):
+ messages = [{"role": "user", "content": truncate_content(raw_input)}]
+ elif isinstance(raw_input, (list, tuple)):
+ messages = []
+ for item in raw_input[:20]:
+ if isinstance(item, dict):
+ messages.append(item)
+ else:
+ role = getattr(item, "role", "user")
+ content = getattr(item, "content", str(item))
+ messages.append(
+ {
+ "role": str(role),
+ "content": truncate_content(str(content)),
+ }
+ )
+ else:
+ messages = [
+ {"role": "user", "content": truncate_content(str(raw_input))}
+ ]
+ span.set_attribute(
+ SemanticConvention.GEN_AI_INPUT_MESSAGES, json.dumps(messages)
+ )
+
+ output_items = getattr(response, "output", None)
+ if output_items:
+ out_messages = []
+ for item in output_items[:20]:
+ item_type = getattr(item, "type", None)
+ if item_type == "message":
+ content_parts = getattr(item, "content", [])
+ text_parts = []
+ for part in content_parts:
+ text = getattr(part, "text", None)
+ if text:
+ text_parts.append(truncate_content(str(text)))
+ if text_parts:
+ out_messages.append(
+ {
+ "role": "assistant",
+ "content": " ".join(text_parts),
+ }
+ )
+ elif item_type == "function_call":
+ fname = getattr(item, "name", "unknown")
+ fargs = getattr(item, "arguments", "")
+ out_messages.append(
+ {
+ "role": "assistant",
+ "content": json.dumps(
+ {"tool_call": fname, "arguments": fargs}
+ ),
+ }
+ )
+ if out_messages:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_MESSAGES, json.dumps(out_messages)
+ )
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Generation (chat -- Chat Completions API, used for non-OpenAI models)
+# ---------------------------------------------------------------------------
+def _set_generation_attributes(span, span_data, capture_message_content):
+ try:
+ model = getattr(span_data, "model", None)
+ if model:
+ span.set_attribute(SemanticConvention.GEN_AI_REQUEST_MODEL, str(model))
+ span.set_attribute(SemanticConvention.GEN_AI_RESPONSE_MODEL, str(model))
+
+ usage = getattr(span_data, "usage", None)
+ if usage and isinstance(usage, dict):
+ input_tokens = usage.get("input_tokens")
+ output_tokens = usage.get("output_tokens")
+ if input_tokens is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, input_tokens
+ )
+ if output_tokens is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, output_tokens
+ )
+
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_TYPE,
+ SemanticConvention.GEN_AI_OUTPUT_TYPE_TEXT,
+ )
+ span.set_attribute(SemanticConvention.SERVER_ADDRESS, "api.openai.com")
+ span.set_attribute(SemanticConvention.SERVER_PORT, 443)
+
+ if capture_message_content:
+ raw_input = getattr(span_data, "input", None)
+ if raw_input:
+ if isinstance(raw_input, (list, tuple)):
+ messages = []
+ for msg in raw_input[:20]:
+ if isinstance(msg, dict):
+ messages.append(msg)
+ else:
+ messages.append(
+ {"role": "user", "content": truncate_content(str(msg))}
+ )
+ span.set_attribute(
+ SemanticConvention.GEN_AI_INPUT_MESSAGES, json.dumps(messages)
+ )
+ else:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_INPUT_MESSAGES,
+ json.dumps(
+ [
+ {
+ "role": "user",
+ "content": truncate_content(str(raw_input)),
+ }
+ ]
+ ),
+ )
+
+ raw_output = getattr(span_data, "output", None)
+ if raw_output:
+ if isinstance(raw_output, (list, tuple)):
+ messages = []
+ for msg in raw_output[:20]:
+ if isinstance(msg, dict):
+ messages.append(msg)
+ else:
+ messages.append(
+ {
+ "role": "assistant",
+ "content": truncate_content(str(msg)),
+ }
+ )
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_MESSAGES, json.dumps(messages)
+ )
+ else:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_MESSAGES,
+ json.dumps(
+ [
+ {
+ "role": "assistant",
+ "content": truncate_content(str(raw_output)),
+ }
+ ]
+ ),
+ )
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Function / Tool (execute_tool)
+# ---------------------------------------------------------------------------
+def _set_function_attributes(span, span_data, capture_message_content):
+ try:
+ name = getattr(span_data, "name", None)
+ if name:
+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_NAME, str(name))
+
+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_TYPE, "function")
+
+ if capture_message_content:
+ tool_input = getattr(span_data, "input", None)
+ if tool_input is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS,
+ truncate_content(str(tool_input)),
+ )
+
+ tool_output = getattr(span_data, "output", None)
+ if tool_output is not None:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_RESULT,
+ truncate_content(str(tool_output)),
+ )
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Handoff (invoke_agent for target)
+# ---------------------------------------------------------------------------
+def _set_handoff_attributes(span, span_data, handoff_tracker, trace_id):
+ try:
+ to_agent = getattr(span_data, "to_agent", None)
+ from_agent = getattr(span_data, "from_agent", None)
+
+ if to_agent:
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(to_agent))
+ # Track for parent-child agent graph
+ if handoff_tracker is not None:
+ key = f"{to_agent}:{trace_id}"
+ handoff_tracker[key] = str(from_agent) if from_agent else "unknown"
+ if len(handoff_tracker) > _MAX_HANDOFFS:
+ handoff_tracker.popitem(last=False)
+
+ if from_agent:
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_SOURCE, str(from_agent))
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Guardrail (invoke_agent)
+# ---------------------------------------------------------------------------
+def _set_guardrail_attributes(span, span_data):
+ try:
+ name = getattr(span_data, "name", None)
+ if name:
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(name))
+
+ triggered = getattr(span_data, "triggered", None)
+ if triggered is not None:
+ span.set_attribute("gen_ai.guardrail.triggered", bool(triggered))
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Transcription (chat)
+# ---------------------------------------------------------------------------
+def _set_transcription_attributes(span, span_data, capture_message_content):
+ try:
+ model = getattr(span_data, "model", None)
+ if model:
+ span.set_attribute(SemanticConvention.GEN_AI_REQUEST_MODEL, str(model))
+ span.set_attribute(SemanticConvention.GEN_AI_RESPONSE_MODEL, str(model))
+
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_TYPE,
+ SemanticConvention.GEN_AI_OUTPUT_TYPE_TEXT,
+ )
+ span.set_attribute(SemanticConvention.SERVER_ADDRESS, "api.openai.com")
+ span.set_attribute(SemanticConvention.SERVER_PORT, 443)
+
+ if capture_message_content:
+ output = getattr(span_data, "output", None)
+ if output:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_OUTPUT_MESSAGES,
+ json.dumps(
+ [
+ {
+ "role": "assistant",
+ "content": truncate_content(str(output)),
+ }
+ ]
+ ),
+ )
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Speech (chat)
+# ---------------------------------------------------------------------------
+def _set_speech_attributes(span, span_data, capture_message_content):
+ try:
+ model = getattr(span_data, "model", None)
+ if model:
+ span.set_attribute(SemanticConvention.GEN_AI_REQUEST_MODEL, str(model))
+ span.set_attribute(SemanticConvention.GEN_AI_RESPONSE_MODEL, str(model))
+
+ span.set_attribute(SemanticConvention.GEN_AI_OUTPUT_TYPE, "speech")
+ span.set_attribute(SemanticConvention.SERVER_ADDRESS, "api.openai.com")
+ span.set_attribute(SemanticConvention.SERVER_PORT, 443)
+
+ if capture_message_content:
+ text_input = getattr(span_data, "input", None)
+ if text_input:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_INPUT_MESSAGES,
+ json.dumps(
+ [{"role": "user", "content": truncate_content(str(text_input))}]
+ ),
+ )
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# MCP List Tools (execute_tool)
+# ---------------------------------------------------------------------------
+def _set_mcp_tools_attributes(span, span_data):
+ try:
+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_NAME, "mcp_list_tools")
+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_TYPE, "function")
+
+ server = getattr(span_data, "server", None)
+ if server:
+ span.set_attribute("gen_ai.mcp.server", str(server))
+
+ result = getattr(span_data, "result", None)
+ if result:
+ span.set_attribute(
+ SemanticConvention.GEN_AI_TOOL_CALL_RESULT,
+ json.dumps(list(result[:50])),
+ )
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Custom (invoke_agent)
+# ---------------------------------------------------------------------------
+def _set_custom_attributes(span, span_data):
+ try:
+ name = getattr(span_data, "name", None)
+ if name:
+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(name))
+
+ data = getattr(span_data, "data", None)
+ if data and isinstance(data, dict):
+ try:
+ span.set_attribute("gen_ai.custom.data", json.dumps(data))
+ except (TypeError, ValueError):
+ pass
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Metrics
+# ---------------------------------------------------------------------------
+def _record_metrics(
+ metrics,
+ operation_type,
+ duration,
+ environment,
+ application_name,
+ request_model,
+ server_address,
+ server_port,
+):
+ try:
+ attributes = {
+ SemanticConvention.GEN_AI_OPERATION: operation_type,
+ SemanticConvention.GEN_AI_PROVIDER_NAME: SemanticConvention.GEN_AI_SYSTEM_OPENAI,
+ "service.name": application_name,
+ "deployment.environment": environment,
+ }
+ if request_model:
+ attributes[SemanticConvention.GEN_AI_REQUEST_MODEL] = request_model
+ if server_address:
+ attributes[SemanticConvention.SERVER_ADDRESS] = server_address
+ if server_port:
+ attributes[SemanticConvention.SERVER_PORT] = server_port
+
+ if "genai_client_operation_duration" in metrics:
+ metrics["genai_client_operation_duration"].record(duration, attributes)
+ except Exception:
+ pass
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def _extract_model_from_span_data(span_data):
+ """Best-effort model name extraction from any span_data type."""
+ model = getattr(span_data, "model", None)
+ if model:
+ return str(model)
+
+ response = getattr(span_data, "response", None)
+ if response:
+ model = getattr(response, "model", None)
+ if model:
+ return str(model)
+
+ return None
diff --git a/sdk/python/src/openlit/semcov/__init__.py b/sdk/python/src/openlit/semcov/__init__.py
index 1480a808..359db518 100644
--- a/sdk/python/src/openlit/semcov/__init__.py
+++ b/sdk/python/src/openlit/semcov/__init__.py
@@ -264,7 +264,7 @@ class SemanticConvention:
GEN_AI_OPERATION_TYPE_VECTORDB = "vectordb"
GEN_AI_OPERATION_TYPE_FRAMEWORK = "invoke_workflow"
GEN_AI_OPERATION_TYPE_AGENT = "invoke_agent"
- GEN_AI_OPERATION_TYPE_TEAM = "team"
+ GEN_AI_OPERATION_TYPE_TEAM = "invoke_workflow"
GEN_AI_OPERATION_TYPE_CREATE_AGENT = "create_agent"
GEN_AI_OPERATION_TYPE_EXECUTE_AGENT_TASK = "execute_task"
GEN_AI_OPERATION_TYPE_GRAPH_EXECUTION = "invoke_workflow"
@@ -357,6 +357,7 @@ class SemanticConvention:
GEN_AI_SYSTEM_SARVAM = "sarvam"
GEN_AI_SYSTEM_BROWSER_USE = "browser_use"
GEN_AI_SYSTEM_LANGGRAPH = "langgraph"
+ GEN_AI_SYSTEM_GOOGLE_ADK = "google_adk"
# Graph Execution Attributes (framework-agnostic, usable across LangGraph, CrewAI, etc.)
GEN_AI_GRAPH_NODES = "gen_ai.graph.nodes"
diff --git a/sdk/python/tests/test_google_adk.py b/sdk/python/tests/test_google_adk.py
new file mode 100644
index 00000000..bc7c279e
--- /dev/null
+++ b/sdk/python/tests/test_google_adk.py
@@ -0,0 +1,977 @@
+# pylint: disable=duplicate-code, no-member, too-few-public-methods, missing-class-docstring, missing-function-docstring
+"""
+Tests for Google ADK instrumentation using the google-adk Python library.
+
+Tests cover:
+- Instrumentor import and basic instantiation
+- Utils: OPERATION_MAP, SPAN_KIND_MAP, generate_span_name, _PassthroughTracer
+- Agent creation registry
+- Server address resolution
+- Token extraction
+- LLM span enrichment
+- Tool span enrichment
+
+Note: These tests do NOT require google-adk to be installed -- they mock
+all ADK internals so the test suite can run in any environment.
+"""
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from openlit.instrumentation.google_adk.utils import (
+ OPERATION_MAP,
+ SPAN_KIND_MAP,
+ _ADK_WORKFLOW_ACTIVE,
+ _detect_provider_from_model_str,
+ _determine_output_type,
+ generate_span_name,
+ get_operation_type,
+ resolve_server_info,
+ extract_model_name,
+ extract_token_usage,
+ enrich_llm_span,
+ enrich_tool_span,
+ enrich_merged_tool_span,
+ _PassthroughTracer,
+ _resolve_model_string,
+ _extract_from_event,
+ _is_adk_event,
+ record_google_adk_metrics,
+)
+
+from openlit.semcov import SemanticConvention
+
+
+class TestOperationMap:
+ """Tests for OPERATION_MAP and SPAN_KIND_MAP completeness."""
+
+ def test_operation_map_has_required_endpoints(self):
+ required = [
+ "agent_init",
+ "runner_run_async",
+ "runner_run",
+ "runner_run_live",
+ "agent_run_async",
+ ]
+ for key in required:
+ assert key in OPERATION_MAP, f"Missing endpoint: {key}"
+
+ def test_span_kind_map_has_required_operations(self):
+ required = [
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ ]
+ for key in required:
+ assert key in SPAN_KIND_MAP, f"Missing span kind: {key}"
+
+ def test_get_operation_type_defaults(self):
+ assert get_operation_type("agent_init") == SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT
+ assert get_operation_type("unknown_key") == SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT
+
+ def test_runner_endpoints_map_to_invoke_agent(self):
+ for key in ("runner_run_async", "runner_run", "runner_run_live"):
+ assert OPERATION_MAP[key] == SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT
+
+
+class TestSpanNameGeneration:
+ """Tests for generate_span_name."""
+
+ def test_agent_init_span_name(self):
+ instance = MagicMock()
+ instance.name = "my_agent"
+ assert generate_span_name("agent_init", instance) == "create_agent my_agent"
+
+ def test_runner_run_async_span_name(self):
+ instance = MagicMock()
+ instance.app_name = "my_app"
+ assert generate_span_name("runner_run_async", instance) == "invoke_agent my_app"
+
+ def test_runner_run_span_name(self):
+ instance = MagicMock()
+ instance.app_name = "sync_app"
+ assert generate_span_name("runner_run", instance) == "invoke_agent sync_app"
+
+ def test_agent_run_async_span_name(self):
+ instance = MagicMock()
+ instance.name = "sub_agent"
+ assert generate_span_name("agent_run_async", instance) == "invoke_agent sub_agent"
+
+ def test_fallback_app_name(self):
+ instance = MagicMock(spec=[])
+ name = generate_span_name("runner_run_async", instance)
+ assert "invoke_agent" in name
+
+ def test_fallback_agent_name(self):
+ instance = MagicMock(spec=[])
+ name = generate_span_name("agent_run_async", instance)
+ assert "invoke_agent" in name
+
+
+class TestPassthroughTracer:
+ """Tests for _PassthroughTracer."""
+
+ def test_passthrough_yields_current_span(self):
+ mock_tracer = MagicMock()
+ passthrough = _PassthroughTracer(mock_tracer)
+
+ mock_span = MagicMock()
+ with patch("opentelemetry.trace.get_current_span", return_value=mock_span):
+ with passthrough.start_as_current_span("test") as span:
+ assert span is mock_span
+
+ def test_passthrough_does_not_call_original(self):
+ mock_tracer = MagicMock()
+ passthrough = _PassthroughTracer(mock_tracer)
+
+ with patch("opentelemetry.trace.get_current_span"):
+ with passthrough.start_as_current_span("test"):
+ pass
+
+ mock_tracer.start_as_current_span.assert_not_called()
+
+
+class TestServerAddressResolution:
+ """Tests for resolve_server_info."""
+
+ def test_default_gemini(self):
+ with patch.dict("os.environ", {}, clear=True):
+ addr, port, provider = resolve_server_info()
+ assert addr == "generativelanguage.googleapis.com"
+ assert port == 443
+ assert provider == "gcp.gemini"
+
+ def test_vertex_ai(self):
+ with patch.dict("os.environ", {"GOOGLE_GENAI_USE_VERTEXAI": "true"}):
+ addr, port, provider = resolve_server_info()
+ assert addr == "aiplatform.googleapis.com"
+ assert port == 443
+ assert provider == "gcp.vertex_ai"
+
+ def test_vertex_ai_numeric(self):
+ with patch.dict("os.environ", {"GOOGLE_GENAI_USE_VERTEXAI": "1"}):
+ _, _, provider = resolve_server_info()
+ assert provider == "gcp.vertex_ai"
+
+
+class TestResolveModelString:
+ """Tests for _resolve_model_string."""
+
+ def test_string_passthrough(self):
+ assert _resolve_model_string("gemini-2.0-flash") == "gemini-2.0-flash"
+
+ def test_model_name_attribute(self):
+ obj = MagicMock(spec=["model_name"])
+ obj.model_name = "gemini-pro"
+ assert _resolve_model_string(obj) == "gemini-pro"
+
+ def test_pydantic_style_model_field(self):
+ """LiteLlm inherits ``model: str`` from BaseLlm(BaseModel)."""
+ obj = MagicMock(spec=["model"])
+ obj.model = "anthropic/claude-sonnet-4-20250514"
+ assert _resolve_model_string(obj) == "anthropic/claude-sonnet-4-20250514"
+
+ def test_non_string_model_field_returns_none(self):
+ obj = MagicMock(spec=["model"])
+ obj.model = 12345
+ assert _resolve_model_string(obj) is None
+
+ def test_no_attributes_returns_none(self):
+ obj = MagicMock(spec=[])
+ assert _resolve_model_string(obj) is None
+
+
+class TestModelExtraction:
+ """Tests for extract_model_name."""
+
+ def test_string_model(self):
+ instance = MagicMock()
+ instance.model = "gemini-2.0-flash"
+ assert extract_model_name(instance) == "gemini-2.0-flash"
+
+ def test_object_model_with_model_name(self):
+ instance = MagicMock()
+ instance.model = MagicMock()
+ instance.model.model_name = "gemini-pro"
+ assert extract_model_name(instance) == "gemini-pro"
+
+ def test_pydantic_model_object(self):
+ """Simulates LiteLlm where .model is a str field on a non-string object."""
+ litellm_obj = MagicMock(spec=["model"])
+ litellm_obj.model = "anthropic/claude-sonnet-4-20250514"
+
+ instance = MagicMock()
+ instance.model = litellm_obj
+ del instance.model.model_name
+ assert extract_model_name(instance) == "anthropic/claude-sonnet-4-20250514"
+
+ def test_agent_attribute_fallback(self):
+ instance = MagicMock(spec=[])
+ instance.agent = MagicMock()
+ instance.agent.model = "gemini-1.5-pro"
+ assert extract_model_name(instance) == "gemini-1.5-pro"
+
+ def test_unknown_fallback(self):
+ instance = MagicMock(spec=[])
+ assert extract_model_name(instance) == "unknown"
+
+
+class TestTokenExtraction:
+ """Tests for extract_token_usage."""
+
+ def test_full_usage(self):
+ response = MagicMock()
+ response.usage_metadata.prompt_token_count = 100
+ response.usage_metadata.candidates_token_count = 50
+ response.usage_metadata.thoughts_token_count = 10
+ response.usage_metadata.cached_content_token_count = 5
+ response.usage_metadata.total_token_count = 165
+
+ inp, out, reasoning, cached, total = extract_token_usage(response)
+ assert inp == 100
+ assert out == 50
+ assert reasoning == 10
+ assert cached == 5
+ assert total == 165
+
+ def test_no_usage(self):
+ response = MagicMock()
+ response.usage_metadata = None
+ inp, out, reasoning, cached, total = extract_token_usage(response)
+ assert inp is None
+ assert out is None
+ assert reasoning is None
+ assert cached is None
+ assert total is None
+
+ def test_partial_usage(self):
+ response = MagicMock()
+ response.usage_metadata.prompt_token_count = 42
+ response.usage_metadata.candidates_token_count = None
+ response.usage_metadata.thoughts_token_count = None
+ response.usage_metadata.cached_content_token_count = None
+ response.usage_metadata.total_token_count = 42
+
+ inp, out, reasoning, cached, total = extract_token_usage(response)
+ assert inp == 42
+ assert out is None
+ assert reasoning is None
+ assert cached is None
+ assert total == 42
+
+ def test_reasoning_separate_from_output(self):
+ response = MagicMock()
+ response.usage_metadata.prompt_token_count = 100
+ response.usage_metadata.candidates_token_count = 50
+ response.usage_metadata.thoughts_token_count = 25
+ response.usage_metadata.cached_content_token_count = None
+ response.usage_metadata.total_token_count = 175
+
+ _, out, reasoning, _, _ = extract_token_usage(response)
+ assert out == 50
+ assert reasoning == 25
+
+
+class TestLLMSpanEnrichment:
+ """Tests for enrich_llm_span."""
+
+ def test_basic_enrichment(self):
+ span = MagicMock()
+ llm_request = MagicMock()
+ llm_request.model = "gemini-2.0-flash"
+ llm_request.config = MagicMock()
+ llm_request.config.temperature = 0.7
+ llm_request.config.top_p = 0.9
+ llm_request.config.max_output_tokens = 1024
+ llm_request.config.system_instruction = None
+ llm_request.contents = []
+
+ llm_response = MagicMock()
+ llm_response.usage_metadata.prompt_token_count = 100
+ llm_response.usage_metadata.candidates_token_count = 50
+ llm_response.usage_metadata.thoughts_token_count = None
+ llm_response.usage_metadata.cached_content_token_count = None
+ llm_response.usage_metadata.total_token_count = 150
+ llm_response.model_version = "gemini-2.0-flash-001"
+ llm_response.finish_reason = MagicMock()
+ llm_response.finish_reason.value = "STOP"
+ llm_response.error_code = None
+ llm_response.content = MagicMock()
+ llm_response.content.parts = []
+
+ enrich_llm_span(span, llm_request, llm_response, capture_message_content=False)
+
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_REQUEST_MODEL, "gemini-2.0-flash"
+ )
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, 100
+ )
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, 50
+ )
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_RESPONSE_MODEL, "gemini-2.0-flash-001"
+ )
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON, ["stop"]
+ )
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_USAGE_TOTAL_TOKENS, 150
+ )
+
+ def test_enrichment_with_none_request(self):
+ span = MagicMock()
+ enrich_llm_span(span, None, None, capture_message_content=False)
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_OPERATION,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ )
+
+
+def _make_adk_event(response_dict=None, tool_call_id=None):
+ """Build a mock ADK Event with function_response content."""
+ fn_resp = MagicMock()
+ fn_resp.response = response_dict
+ fn_resp.id = tool_call_id
+ fn_resp.name = "test_tool"
+
+ part = MagicMock()
+ part.function_response = fn_resp
+
+ content = MagicMock()
+ content.parts = [part]
+
+ event = MagicMock()
+ event.content = content
+ type(event).__qualname__ = "Event"
+ return event
+
+
+class TestADKEventExtraction:
+ """Tests for _is_adk_event and _extract_from_event."""
+
+ def test_is_adk_event_true(self):
+ event = _make_adk_event({"result": "ok"}, "call_123")
+ assert _is_adk_event(event) is True
+
+ def test_is_adk_event_false_for_dict(self):
+ assert _is_adk_event({"key": "val"}) is False
+
+ def test_extract_response_and_id(self):
+ event = _make_adk_event({"status": "success", "data": 42}, "call_xyz")
+ resp, call_id = _extract_from_event(event)
+ assert resp == {"status": "success", "data": 42}
+ assert call_id == "call_xyz"
+
+ def test_extract_from_none_event(self):
+ resp, call_id = _extract_from_event(None)
+ assert resp is None
+ assert call_id is None
+
+ def test_extract_from_event_without_content(self):
+ event = MagicMock(spec=[])
+ resp, call_id = _extract_from_event(event)
+ assert resp is None
+ assert call_id is None
+
+
+class TestToolSpanEnrichment:
+ """Tests for enrich_tool_span."""
+
+ def test_basic_tool_enrichment_with_dict(self):
+ span = MagicMock()
+ tool = MagicMock()
+ tool.name = "web_search"
+ tool.description = "Search the web"
+
+ enrich_tool_span(
+ span,
+ tool,
+ function_args={"query": "test"},
+ function_response_event={"results": []},
+ capture_message_content=True,
+ )
+
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_TOOL_NAME, "web_search"
+ )
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_TOOL_DESCRIPTION, "Search the web"
+ )
+
+ def test_enrichment_with_adk_event(self):
+ """The function_response_event is an ADK Event, not a plain dict."""
+ span = MagicMock()
+ tool = MagicMock()
+ tool.name = "get_weather"
+ tool.description = "Get weather"
+
+ event = _make_adk_event({"status": "success", "temp": 25}, "call_abc")
+
+ enrich_tool_span(
+ span,
+ tool,
+ function_args={"city": "NYC"},
+ function_response_event=event,
+ capture_message_content=True,
+ )
+
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_TOOL_NAME, "get_weather"
+ )
+ set_calls = {call[0][0]: call[0][1] for call in span.set_attribute.call_args_list}
+ assert SemanticConvention.GEN_AI_TOOL_CALL_ID in set_calls
+ assert set_calls[SemanticConvention.GEN_AI_TOOL_CALL_ID] == "call_abc"
+ assert SemanticConvention.GEN_AI_TOOL_CALL_RESULT in set_calls
+ result_json = json.loads(set_calls[SemanticConvention.GEN_AI_TOOL_CALL_RESULT])
+ assert result_json["status"] == "success"
+
+ def test_tool_without_capture(self):
+ span = MagicMock()
+ tool = MagicMock()
+ tool.name = "calculator"
+ tool.description = None
+
+ enrich_tool_span(
+ span,
+ tool,
+ function_args={"x": 1},
+ function_response_event={"result": 2},
+ capture_message_content=False,
+ )
+
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_TOOL_NAME, "calculator"
+ )
+ call_args_list = [call[0] for call in span.set_attribute.call_args_list]
+ for call_args in call_args_list:
+ assert call_args[0] != SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS
+ assert call_args[0] != SemanticConvention.GEN_AI_TOOL_CALL_RESULT
+
+ def test_enrichment_with_none_event(self):
+ span = MagicMock()
+ tool = MagicMock()
+ tool.name = "noop"
+ tool.description = None
+
+ enrich_tool_span(
+ span, tool,
+ function_args=None,
+ function_response_event=None,
+ capture_message_content=True,
+ )
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_TOOL_NAME, "noop"
+ )
+
+
+class TestMergedToolSpanEnrichment:
+ """Tests for enrich_merged_tool_span."""
+
+ def test_basic_merged_enrichment(self):
+ span = MagicMock()
+
+ fn_resp1 = MagicMock()
+ fn_resp1.response = {"result": "sunny"}
+ fn_resp1.name = "get_weather"
+ fn_resp2 = MagicMock()
+ fn_resp2.response = {"result": "42"}
+ fn_resp2.name = "calculate"
+
+ part1 = MagicMock()
+ part1.function_response = fn_resp1
+ part2 = MagicMock()
+ part2.function_response = fn_resp2
+
+ event = MagicMock()
+ event.content = MagicMock()
+ event.content.parts = [part1, part2]
+
+ enrich_merged_tool_span(span, "evt_123", event, capture_message_content=True)
+
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_OPERATION,
+ SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
+ )
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_TOOL_NAME, "(merged tools)"
+ )
+ span.set_attribute.assert_any_call(
+ SemanticConvention.GEN_AI_TOOL_CALL_ID, "evt_123"
+ )
+
+ set_calls = {call[0][0]: call[0][1] for call in span.set_attribute.call_args_list}
+ assert SemanticConvention.GEN_AI_TOOL_CALL_RESULT in set_calls
+ result = json.loads(set_calls[SemanticConvention.GEN_AI_TOOL_CALL_RESULT])
+ assert len(result) == 2
+ assert result[0]["name"] == "get_weather"
+ assert result[1]["name"] == "calculate"
+
+ def test_merged_without_capture(self):
+ span = MagicMock()
+ enrich_merged_tool_span(span, "evt_1", MagicMock(), capture_message_content=False)
+ set_calls = {call[0][0]: call[0][1] for call in span.set_attribute.call_args_list}
+ assert SemanticConvention.GEN_AI_TOOL_CALL_RESULT not in set_calls
+
+
+class TestAgentCreationRegistry:
+ """Tests for _AgentCreationRegistry."""
+
+ def test_register_and_get(self):
+ from openlit.instrumentation.google_adk import _AgentCreationRegistry
+
+ registry = _AgentCreationRegistry()
+ mock_ctx = MagicMock()
+
+ registry.register("test_agent", mock_ctx)
+ assert registry.get("test_agent") is mock_ctx
+ assert registry.get("unknown") is None
+
+ def test_get_all(self):
+ from openlit.instrumentation.google_adk import _AgentCreationRegistry
+
+ registry = _AgentCreationRegistry()
+ ctx1 = MagicMock()
+ ctx2 = MagicMock()
+
+ registry.register("agent1", ctx1)
+ registry.register("agent2", ctx2)
+
+ all_contexts = registry.get_all()
+ assert len(all_contexts) == 2
+ assert ctx1 in all_contexts
+ assert ctx2 in all_contexts
+
+
+class TestMetricsRecording:
+ """Tests for record_google_adk_metrics."""
+
+ def test_records_duration(self):
+ metrics = {
+ "genai_client_operation_duration": MagicMock()
+ }
+ record_google_adk_metrics(
+ metrics,
+ "invoke_workflow",
+ 1.5,
+ "test",
+ "my_app",
+ "gemini-2.0-flash",
+ "generativelanguage.googleapis.com",
+ 443,
+ )
+ metrics["genai_client_operation_duration"].record.assert_called_once()
+
+ def test_skips_missing_metric(self):
+ metrics = {}
+ record_google_adk_metrics(
+ metrics,
+ "invoke_workflow",
+ 1.0,
+ "test",
+ "app",
+ "unknown",
+ "",
+ 0,
+ )
+
+
+class TestToolNameExtraction:
+ """Tests for tool name extraction in _wrap_agent_init for raw callables."""
+
+ def test_callable_name_via_dunder(self):
+ """Raw Python functions have __name__, not .name."""
+ def get_weather(city: str) -> dict:
+ """Get weather for a city."""
+ return {}
+
+ t_name = getattr(get_weather, "name", None) or getattr(get_weather, "__name__", None) or type(get_weather).__name__
+ assert t_name == "get_weather"
+
+ def test_lambda_falls_back_to_lambda(self):
+ def _anon(x):
+ return x
+ _anon.__name__ = "<lambda>"
+ t_name = getattr(_anon, "name", None) or getattr(_anon, "__name__", None) or type(_anon).__name__
+ assert t_name == "<lambda>"
+
+ def test_basetool_style_name(self):
+ """BaseTool subclasses have .name."""
+ tool = MagicMock()
+ tool.name = "my_tool"
+ t_name = getattr(tool, "name", None) or getattr(tool, "__name__", None) or type(tool).__name__
+ assert t_name == "my_tool"
+
+ def test_docstring_as_description(self):
+ """Raw callables use __doc__ as description fallback."""
+ def calculate(expression: str) -> dict:
+ """Evaluate a math expression."""
+ return {}
+
+ t_desc = getattr(calculate, "description", None) or getattr(calculate, "__doc__", None)
+ assert "Evaluate a math expression" in t_desc
+
+
+class TestInstrumentorImport:
+ """Tests that the instrumentor module can be imported."""
+
+ def test_import_instrumentor(self):
+ from openlit.instrumentation.google_adk import GoogleADKInstrumentor
+ assert GoogleADKInstrumentor is not None
+
+ def test_import_utils(self):
+ from openlit.instrumentation.google_adk import utils
+ assert hasattr(utils, "OPERATION_MAP")
+ assert hasattr(utils, "_PassthroughTracer")
+ assert hasattr(utils, "enrich_llm_span")
+ assert hasattr(utils, "enrich_tool_span")
+
+ def test_import_async_wrappers(self):
+ from openlit.instrumentation.google_adk.async_google_adk import (
+ async_runner_wrap,
+ async_agent_wrap,
+ )
+ assert async_runner_wrap is not None
+ assert async_agent_wrap is not None
+
+ def test_import_sync_wrappers(self):
+ from openlit.instrumentation.google_adk.google_adk import sync_runner_wrap
+ assert sync_runner_wrap is not None
+
+
+class TestServerInfoNonGoogle:
+ """Tests for resolve_server_info with non-Google backends."""
+
+ def test_anthropic_model_detection(self):
+ addr, _, provider = resolve_server_info(model_name="anthropic/claude-sonnet-4-20250514")
+ assert addr == "api.anthropic.com"
+ assert provider == "anthropic"
+
+ def test_openai_model_detection(self):
+ addr, _, provider = resolve_server_info(model_name="openai/gpt-4o")
+ assert addr == "api.openai.com"
+ assert provider == "openai"
+
+ def test_gpt_prefix_detection(self):
+ _, _, provider = resolve_server_info(model_name="gpt-4o-mini")
+ assert provider == "openai"
+
+ def test_mistral_detection(self):
+ _, _, provider = resolve_server_info(model_name="mistral/mistral-large")
+ assert provider == "mistral"
+
+ def test_gemini_stays_default(self):
+ with patch.dict("os.environ", {}, clear=True):
+ addr, _, provider = resolve_server_info(model_name="gemini-2.0-flash")
+ assert addr == "generativelanguage.googleapis.com"
+ assert provider == "gcp.gemini"
+
+ def test_instance_model_object_detection(self):
+ instance = MagicMock()
+ model_obj = MagicMock(spec=["model"])
+ model_obj.model = "anthropic/claude-sonnet-4-20250514"
+ instance.model = model_obj
+ with patch.dict("os.environ", {}, clear=True):
+ _, _, provider = resolve_server_info(instance=instance)
+ assert provider == "anthropic"
+
+ def test_detect_provider_from_model_str(self):
+ assert _detect_provider_from_model_str("anthropic/claude-3") is not None
+ assert _detect_provider_from_model_str("gemini-2.0-flash") is None
+ assert _detect_provider_from_model_str(None) is None
+ assert _detect_provider_from_model_str("") is None
+
+
+class TestDetermineOutputType:
+ """Tests for _determine_output_type."""
+
+ def test_text_response(self):
+ response = MagicMock()
+ part = MagicMock()
+ part.function_call = None
+ response.content.parts = [part]
+ assert _determine_output_type(response) == "text"
+
+ def test_tool_call_response(self):
+ response = MagicMock()
+ part = MagicMock()
+ part.function_call = MagicMock()
+ response.content.parts = [part]
+ assert _determine_output_type(response) == "tool_calls"
+
+ def test_none_content(self):
+ response = MagicMock()
+ response.content = None
+ assert _determine_output_type(response) == "text"
+
+
+class TestWorkflowDedup:
+ """Tests for _ADK_WORKFLOW_ACTIVE contextvar deduplication."""
+
+ def test_default_is_false(self):
+ assert _ADK_WORKFLOW_ACTIVE.get() is False
+
+ def test_set_and_reset(self):
+ tok = _ADK_WORKFLOW_ACTIVE.set(True)
+ assert _ADK_WORKFLOW_ACTIVE.get() is True
+ _ADK_WORKFLOW_ACTIVE.reset(tok)
+ assert _ADK_WORKFLOW_ACTIVE.get() is False
+
+
+class TestSemconvConstant:
+ """Tests that the semantic convention constant exists."""
+
+ def test_google_adk_system_constant(self):
+ assert hasattr(SemanticConvention, "GEN_AI_SYSTEM_GOOGLE_ADK")
+ assert SemanticConvention.GEN_AI_SYSTEM_GOOGLE_ADK == "google_adk"
+
+
+class TestInputMessageSchema:
+ """Tests that capture_input_messages produces the OTel parts-based schema."""
+
+ def test_text_message(self):
+ from openlit.instrumentation.google_adk.utils import capture_input_messages
+
+ span = MagicMock()
+ llm_request = MagicMock()
+ content = MagicMock()
+ content.role = "user"
+ text_part = MagicMock()
+ text_part.text = "Hello world"
+ text_part.function_call = None
+ text_part.function_response = None
+ content.parts = [text_part]
+ llm_request.contents = [content]
+
+ capture_input_messages(span, llm_request, capture_message_content=True)
+
+ call_args = span.set_attribute.call_args_list
+ msg_call = [c for c in call_args if c[0][0] == SemanticConvention.GEN_AI_INPUT_MESSAGES]
+ assert len(msg_call) == 1
+ messages = json.loads(msg_call[0][0][1])
+ assert messages[0]["role"] == "user"
+ assert "parts" in messages[0]
+ assert messages[0]["parts"][0]["type"] == "text"
+ assert messages[0]["parts"][0]["content"] == "Hello world"
+ assert "content" not in messages[0]
+
+ def test_tool_call_message(self):
+ from openlit.instrumentation.google_adk.utils import capture_input_messages
+
+ span = MagicMock()
+ llm_request = MagicMock()
+ content = MagicMock()
+ content.role = "assistant"
+ fc = MagicMock()
+ fc.name = "get_weather"
+ fc.id = "call_1"
+ fc.args = {"city": "NYC"}
+ part = MagicMock()
+ part.text = None
+ part.function_call = fc
+ part.function_response = None
+ content.parts = [part]
+ llm_request.contents = [content]
+
+ capture_input_messages(span, llm_request, capture_message_content=True)
+
+ call_args = span.set_attribute.call_args_list
+ msg_call = [c for c in call_args if c[0][0] == SemanticConvention.GEN_AI_INPUT_MESSAGES]
+ messages = json.loads(msg_call[0][0][1])
+ tool_part = messages[0]["parts"][0]
+ assert tool_part["type"] == "tool_call"
+ assert tool_part["name"] == "get_weather"
+ assert tool_part["id"] == "call_1"
+
+ def test_tool_response_message(self):
+ from openlit.instrumentation.google_adk.utils import capture_input_messages
+
+ span = MagicMock()
+ llm_request = MagicMock()
+ content = MagicMock()
+ content.role = "tool"
+ fr = MagicMock()
+ fr.name = "get_weather"
+ fr.id = "call_1"
+ fr.response = {"temp": 72}
+ part = MagicMock()
+ part.text = None
+ part.function_call = None
+ part.function_response = fr
+ content.parts = [part]
+ llm_request.contents = [content]
+
+ capture_input_messages(span, llm_request, capture_message_content=True)
+
+ call_args = span.set_attribute.call_args_list
+ msg_call = [c for c in call_args if c[0][0] == SemanticConvention.GEN_AI_INPUT_MESSAGES]
+ messages = json.loads(msg_call[0][0][1])
+ resp_part = messages[0]["parts"][0]
+ assert resp_part["type"] == "tool_call_response"
+ assert resp_part["id"] == "call_1"
+
+
+class TestOutputMessageSchema:
+ """Tests that capture_output_messages produces the OTel parts-based schema."""
+
+ def test_text_output_with_finish_reason(self):
+ from openlit.instrumentation.google_adk.utils import capture_output_messages
+
+ span = MagicMock()
+ llm_response = MagicMock()
+ text_part = MagicMock()
+ text_part.text = "The weather is sunny."
+ text_part.function_call = None
+ text_part.function_response = None
+ llm_response.content.parts = [text_part]
+
+ capture_output_messages(span, llm_response, True, "stop")
+
+ call_args = span.set_attribute.call_args_list
+ msg_call = [c for c in call_args if c[0][0] == SemanticConvention.GEN_AI_OUTPUT_MESSAGES]
+ assert len(msg_call) == 1
+ messages = json.loads(msg_call[0][0][1])
+ assert messages[0]["role"] == "assistant"
+ assert messages[0]["finish_reason"] == "stop"
+ assert "parts" in messages[0]
+ assert messages[0]["parts"][0]["type"] == "text"
+ assert "content" not in messages[0]
+
+ def test_tool_call_output(self):
+ from openlit.instrumentation.google_adk.utils import capture_output_messages
+
+ span = MagicMock()
+ llm_response = MagicMock()
+ fc = MagicMock()
+ fc.name = "calculate"
+ fc.id = "call_2"
+ fc.args = {"expr": "1+1"}
+ part = MagicMock()
+ part.text = None
+ part.function_call = fc
+ part.function_response = None
+ llm_response.content.parts = [part]
+
+ capture_output_messages(span, llm_response, True, "tool_calls")
+
+ call_args = span.set_attribute.call_args_list
+ msg_call = [c for c in call_args if c[0][0] == SemanticConvention.GEN_AI_OUTPUT_MESSAGES]
+ messages = json.loads(msg_call[0][0][1])
+ assert messages[0]["finish_reason"] == "tool_calls"
+ assert messages[0]["parts"][0]["type"] == "tool_call"
+
+
+class TestSystemInstructionsFormat:
+ """Tests that gen_ai.system_instructions uses the JSON schema format."""
+
+ def test_llm_span_system_instructions_format(self):
+ span = MagicMock()
+ llm_request = MagicMock()
+ llm_request.model = "gemini-2.0-flash"
+ llm_request.config = MagicMock()
+ llm_request.config.temperature = None
+ llm_request.config.top_p = None
+ llm_request.config.max_output_tokens = None
+ llm_request.config.system_instruction = "You are a helpful assistant."
+ llm_request.contents = []
+
+ llm_response = MagicMock()
+ llm_response.usage_metadata = None
+ llm_response.finish_reason = None
+ llm_response.error_code = None
+ llm_response.content = MagicMock()
+ llm_response.content.parts = []
+ llm_response.model_version = None
+ llm_response.response_id = None
+ llm_response.id = None
+
+ enrich_llm_span(span, llm_request, llm_response, capture_message_content=True)
+
+ calls = {c[0][0]: c[0][1] for c in span.set_attribute.call_args_list}
+ sys_instr = calls.get(SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS)
+ assert sys_instr is not None
+ parsed = json.loads(sys_instr)
+ assert isinstance(parsed, list)
+ assert parsed[0]["type"] == "text"
+ assert parsed[0]["content"] == "You are a helpful assistant."
+
+
+class TestToolSpanErrorHandling:
+ """Tests that enrich_tool_span sets error.type when error is provided."""
+
+ def test_error_sets_error_type_and_status(self):
+ span = MagicMock()
+ tool = MagicMock()
+ tool.name = "failing_tool"
+ tool.description = None
+
+ error = ValueError("bad input")
+ enrich_tool_span(
+ span,
+ tool,
+ function_args={"x": 1},
+ function_response_event=None,
+ capture_message_content=False,
+ error=error,
+ )
+
+ calls = {c[0][0]: c[0][1] for c in span.set_attribute.call_args_list}
+ assert calls.get(SemanticConvention.ERROR_TYPE) == "ValueError"
+ span.set_status.assert_called_once()
+
+ def test_no_error_does_not_set_error_type(self):
+ span = MagicMock()
+ tool = MagicMock()
+ tool.name = "ok_tool"
+ tool.description = None
+
+ enrich_tool_span(
+ span,
+ tool,
+ function_args={},
+ function_response_event=None,
+ capture_message_content=False,
+ error=None,
+ )
+
+ calls = {c[0][0]: c[0][1] for c in span.set_attribute.call_args_list}
+ assert SemanticConvention.ERROR_TYPE not in calls
+ span.set_status.assert_not_called()
+
+
+class TestLLMSpanResponseId:
+ """Tests that enrich_llm_span extracts gen_ai.response.id when available."""
+
+ def test_response_id_extracted(self):
+ span = MagicMock()
+ llm_request = MagicMock()
+ llm_request.model = "gemini-2.0-flash"
+ llm_request.config = MagicMock()
+ llm_request.config.temperature = None
+ llm_request.config.top_p = None
+ llm_request.config.max_output_tokens = None
+ llm_request.config.system_instruction = None
+ llm_request.contents = []
+
+ llm_response = MagicMock()
+ llm_response.usage_metadata = None
+ llm_response.model_version = None
+ llm_response.finish_reason = None
+ llm_response.error_code = None
+ llm_response.content = MagicMock()
+ llm_response.content.parts = []
+ llm_response.response_id = "resp_abc123"
+
+ enrich_llm_span(span, llm_request, llm_response, capture_message_content=False)
+
+ calls = {c[0][0]: c[0][1] for c in span.set_attribute.call_args_list}
+ assert calls.get(SemanticConvention.GEN_AI_RESPONSE_ID) == "resp_abc123"
+
+
+if __name__ == "__main__":
+ pytest.main([__file__, "-v"])