monocle-apptrace 0.4.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

monocle_apptrace/instrumentation/metamodel/langchain/entities/inference.py

@@ -1,7 +1,7 @@
 from monocle_apptrace.instrumentation.metamodel.langchain import (
     _helper,
 )
-from monocle_apptrace.instrumentation.common.utils import resolve_from_alias, get_llm_type, get_status, get_status_code
+from monocle_apptrace.instrumentation.common.utils import get_error_message, resolve_from_alias, get_llm_type, get_status, get_status_code
 
 INFERENCE = {
     "type": "inference.framework",
@@ -30,11 +30,11 @@ INFERENCE = {
             {
                 "_comment": "LLM Model",
                 "attribute": "name",
-                "accessor": lambda arguments: resolve_from_alias(arguments['instance'].__dict__, ['model', 'model_name', 'endpoint_name', 'deployment_name'])
+                "accessor": lambda arguments: resolve_from_alias(arguments['instance'].__dict__, ['model', 'model_name', 'endpoint_name', 'deployment_name', 'model_id'])
             },
             {
                 "attribute": "type",
-                "accessor": lambda arguments: 'model.llm.' + resolve_from_alias(arguments['instance'].__dict__, ['model', 'model_name', 'endpoint_name', 'deployment_name'])
+                "accessor": lambda arguments: 'model.llm.' + resolve_from_alias(arguments['instance'].__dict__, ['model', 'model_name', 'endpoint_name', 'deployment_name', 'model_id'])
             }
         ]
     ],
@@ -53,13 +53,8 @@ INFERENCE = {
             "name": "data.output",
             "attributes": [
                 {
-                    "_comment": "this is result from LLM",
-                    "attribute": "status",
-                    "accessor": lambda arguments: get_status(arguments)
-                },
-                {
-                    "attribute": "status_code",
-                    "accessor": lambda arguments: get_status_code(arguments)
+                    "attribute": "error_code",
+                    "accessor": lambda arguments: get_error_message(arguments)
                 },
                 {
                     "attribute": "response",
@@ -73,6 +68,20 @@ INFERENCE = {
                 {
                     "_comment": "this is metadata usage from LLM",
                     "accessor": lambda arguments: _helper.update_span_from_llm_response(arguments['result'], arguments['instance'])
+                },
+                {
+                    "attribute": "finish_reason",
+                    "accessor": lambda arguments: _helper.extract_finish_reason(arguments)
+                },
+                {
+                    "attribute": "finish_type",
+                    "accessor": lambda arguments: _helper.map_finish_reason_to_finish_type(
+                        _helper.extract_finish_reason(arguments)
+                    )
+                },
+                {
+                    "attribute": "inference_sub_type",
+                    "accessor": lambda arguments: _helper.agent_inference_type(arguments)
                 }
             ]
         }

monocle_apptrace/instrumentation/metamodel/langgraph/_helper.py

@@ -1,15 +1,20 @@
+from opentelemetry.context import get_value
 from monocle_apptrace.instrumentation.common.utils import resolve_from_alias
 import logging
 logger = logging.getLogger(__name__)
 
-def handle_openai_response(response):
+DELEGATION_NAME_PREFIX = 'transfer_to_'
+ROOT_AGENT_NAME = 'LangGraph'
+LANGGRAPTH_AGENT_NAME_KEY = "agent.langgraph"
+
+def extract_agent_response(response):
     try:
-        if 'messages' in response:
+        if response is not None and 'messages' in response:
             output = response["messages"][-1]
             return str(output.content)
     except Exception as e:
-        logger.warning("Warning: Error occurred in handle_openai_response: %s", str(e))
-        return ""
+        logger.warning("Warning: Error occurred in handle_response: %s", str(e))
+    return ""
 
 def agent_instructions(arguments):
     if callable(arguments['kwargs']['agent'].instructions):
@@ -17,11 +22,13 @@ def agent_instructions(arguments):
     else:
         return arguments['kwargs']['agent'].instructions
 
-def extract_input(arguments):
-    history = arguments['result']['messages']
-    for message in history:
-        if hasattr(message, 'content') and hasattr(message, 'type') and message.type == "human":  # Check if the message is a HumanMessage
-            return message.content
+def extract_agent_input(arguments):
+    if arguments['result'] is not None and 'messages' in arguments['result']:
+        history = arguments['result']['messages']
+        for message in history:
+            if hasattr(message, 'content') and hasattr(message, 'type') and message.type == "human":  # Check if the message is a HumanMessage
+                return message.content
+    return None
 
 def get_inference_endpoint(arguments):
     inference_endpoint = resolve_from_alias(arguments['instance'].client.__dict__, ['azure_endpoint', 'api_base', '_base_url'])
@@ -33,7 +40,6 @@ def tools(instance):
         if hasattr(tools,'bound') and hasattr(tools.bound,'tools_by_name'):
             return list(tools.bound.tools_by_name.keys())
 
-
 def update_span_from_llm_response(response):
     meta_dict = {}
     token_usage = None
@@ -46,3 +52,54 @@ def update_span_from_llm_response(response):
             meta_dict.update({"prompt_tokens": token_usage.get('prompt_tokens')})
             meta_dict.update({"total_tokens": token_usage.get('total_tokens')})
     return meta_dict
+
+def extract_tool_response(result):
+    if result is not None and hasattr(result, 'content'):
+        return result.content
+    return None
+
+def get_status(result):
+    if result is not None and hasattr(result, 'status'):
+        return result.status
+    return None
+
+def extract_tool_input(arguments):
+    tool_input = arguments['args'][0]
+    if isinstance(tool_input, str):
+        return [tool_input]
+    else:
+        return list(tool_input.values())
+
+def get_name(instance):
+    return instance.name if hasattr(instance, 'name') else ""
+
+def get_agent_name(instance) -> str:
+    return get_name(instance)
+
+def get_tool_name(instance) -> str:
+    return get_name(instance)
+
+def is_delegation_tool(instance) -> bool:
+    return get_name(instance).startswith(DELEGATION_NAME_PREFIX)
+
+def get_target_agent(instance) -> str:
+    return get_name(instance).replace(DELEGATION_NAME_PREFIX, '', 1)
+
+def is_root_agent_name(instance) -> bool:
+    return get_name(instance) == ROOT_AGENT_NAME
+
+def get_source_agent() -> str:
+    """Get the name of the agent that initiated the request."""
+    from_agent = get_value(LANGGRAPTH_AGENT_NAME_KEY)
+    return from_agent if from_agent is not None else ""
+
+def get_description(instance) -> str:
+    return instance.description if hasattr(instance, 'description') else ""
+
+def get_agent_description(instance) -> str:
+    """Get the description of the agent."""
+    return get_description(instance)
+
+def get_tool_description(instance) -> str:
+    """Get the description of the tool."""
+    return get_description(instance)

monocle_apptrace/instrumentation/metamodel/langgraph/entities/inference.py

@@ -1,24 +1,25 @@
 from monocle_apptrace.instrumentation.metamodel.langgraph import (
     _helper
 )
-INFERENCE = {
-      "type": "agent",
+
+AGENT = {
+      "type": "agentic.invocation",
       "attributes": [
         [
               {
                 "_comment": "agent type",
                 "attribute": "type",
-                "accessor": lambda arguments:'agent.oai'
+                "accessor": lambda arguments:'agent.langgraph'
               },
               {
                 "_comment": "name of the agent",
                 "attribute": "name",
-                "accessor": lambda arguments:arguments['instance'].name
+                "accessor": lambda arguments: _helper.get_agent_name(arguments['instance'])
               },
               {
-                "_comment": "agent tools",
-                "attribute": "tools",
-                "accessor": lambda arguments: _helper.tools(arguments['instance'])
+                "_comment": "agent description",
+                "attribute": "description",
+                "accessor": lambda arguments: _helper.get_agent_description(arguments['instance'])
               }
         ]
       ],
@@ -27,9 +28,9 @@ INFERENCE = {
           "name":"data.input",
           "attributes": [
             {
-                "_comment": "this is LLM input",
+                "_comment": "this is Agent input",
                 "attribute": "query",
-                "accessor": lambda arguments: _helper.extract_input(arguments)
+                "accessor": lambda arguments: _helper.extract_agent_input(arguments)
             }
           ]
         },
@@ -39,18 +40,124 @@ INFERENCE = {
             {
                 "_comment": "this is response from LLM",
                 "attribute": "response",
-                "accessor": lambda arguments: _helper.handle_openai_response(arguments['result'])
+                "accessor": lambda arguments: _helper.extract_agent_response(arguments['result'])
             }
           ]
-       },
-       {
-            "name": "metadata",
-            "attributes": [
-                {
-                    "_comment": "this is metadata usage from LLM",
-                    "accessor": lambda arguments: _helper.update_span_from_llm_response(arguments['result'])
-                }
-            ]
         }
       ]
-    }
+    }
+
+AGENT_REQUEST = {
+      "type": "agentic.request",
+      "attributes": [
+        [
+              {
+                "_comment": "agent type",
+                "attribute": "type",
+                "accessor": lambda arguments:'agent.langgraph'
+              }
+        ],
+      ],
+      "events": [
+        {
+          "name":"data.input",
+          "attributes": [
+            {
+                "_comment": "this is Agent input",
+                "attribute": "input",
+                "accessor": lambda arguments: _helper.extract_agent_input(arguments)
+            }
+          ]
+        },
+        {
+          "name":"data.output",
+          "attributes": [
+            {
+                "_comment": "this is response from LLM",
+                "attribute": "response",
+                "accessor": lambda arguments: _helper.extract_agent_response(arguments['result'])
+            }
+          ]
+        }
+      ]
+}
+
+TOOLS = {
+      "type": "agentic.tool.invocation",
+      "attributes": [
+        [
+              {
+                "_comment": "tool type",
+                "attribute": "type",
+                "accessor": lambda arguments:'tool.langgraph'
+              },
+              {
+                "_comment": "name of the tool",
+                "attribute": "name",
+                "accessor": lambda arguments: _helper.get_tool_name(arguments['instance'])
+              },
+              {
+                  "_comment": "tool description",
+                  "attribute": "description",
+                  "accessor": lambda arguments: _helper.get_tool_description(arguments['instance'])
+              }
+        ],
+        [             
+              {
+                "_comment": "name of the agent",
+                "attribute": "name",
+                "accessor": lambda arguments: _helper.get_source_agent()
+              },          
+              {
+                "_comment": "agent type",
+                "attribute": "type",
+                "accessor": lambda arguments:'agent.langgraph'
+              }
+        ]
+      ],
+      "events": [
+        {
+          "name":"data.input",
+          "attributes": [
+            {
+                "_comment": "this is Tool input",
+                "attribute": "Inputs",
+                "accessor": lambda arguments: _helper.extract_tool_input(arguments) 
+            },
+          ]
+        },
+        {
+          "name":"data.output",
+          "attributes": [
+            {
+                "_comment": "this is response from Tool",
+                "attribute": "response",
+                "accessor": lambda arguments: _helper.extract_tool_response(arguments['result'])
+            }
+          ]
+        }
+      ]
+}
+
+AGENT_DELEGATION = {
+      "type": "agentic.delegation",
+      "attributes": [
+        [
+              {
+                "_comment": "agent type",
+                "attribute": "type",
+                "accessor": lambda arguments:'agent.langgraph'
+              },
+              {
+                "_comment": "name of the agent",
+                "attribute": "from_agent",
+                "accessor": lambda arguments: _helper.get_source_agent()
+              },
+              {
+                "_comment": "name of the agent called",
+                "attribute": "to_agent",
+                "accessor": lambda arguments: _helper.get_target_agent(arguments['instance'])
+              }
+        ]
+      ]
+}

monocle_apptrace/instrumentation/metamodel/langgraph/langgraph_processor.py

@@ -0,0 +1,46 @@
+from opentelemetry.context import set_value, attach, detach
+from monocle_apptrace.instrumentation.common.constants import AGENT_PREFIX_KEY
+from monocle_apptrace.instrumentation.common.span_handler import SpanHandler
+from monocle_apptrace.instrumentation.metamodel.langgraph._helper import (
+   DELEGATION_NAME_PREFIX, get_name, is_root_agent_name, is_delegation_tool, LANGGRAPTH_AGENT_NAME_KEY
+
+)
+from monocle_apptrace.instrumentation.metamodel.langgraph.entities.inference import (
+    AGENT_DELEGATION, AGENT_REQUEST
+)
+
+class LanggraphAgentHandler(SpanHandler):
+    def pre_tracing(self, to_wrap, wrapped, instance, args, kwargs):
+        context = set_value(LANGGRAPTH_AGENT_NAME_KEY, get_name(instance))
+        context = set_value(AGENT_PREFIX_KEY, DELEGATION_NAME_PREFIX, context)
+        return attach(context)
+
+    def post_tracing(self, to_wrap, wrapped, instance, args, kwargs, result, token):
+        if token is not None:
+            detach(token)
+
+    # In multi agent scenarios, the root agent is the one that orchestrates the other agents. LangGraph generates an extra root level invoke()
+    # call on top of the supervisor agent invoke().
+    # This span handler resets the parent invoke call as generic type to avoid duplicate attributes/events in supervisor span and this root span.
+    def hydrate_span(self, to_wrap, wrapped, instance, args, kwargs, result, span, parent_span = None, ex:Exception = None) -> bool:
+        if is_root_agent_name(instance) and "parent.agent.span" in span.attributes:
+            agent_request_wrapper = to_wrap.copy()
+            agent_request_wrapper["output_processor"] = AGENT_REQUEST
+        else:
+            agent_request_wrapper = to_wrap
+            if hasattr(instance, 'name') and parent_span is not None and not SpanHandler.is_root_span(parent_span):
+                parent_span.set_attribute("parent.agent.span", True)
+        return super().hydrate_span(agent_request_wrapper, wrapped, instance, args, kwargs, result, span, parent_span, ex)
+
+class LanggraphToolHandler(SpanHandler):
+    # LangGraph uses an internal tool to initate delegation to other agents. The method is tool invoke() with tool name as `transfer_to_<agent_name>`.
+    # Hence we usea different output processor for tool invoke() to format the span as agentic.delegation.
+    def hydrate_span(self, to_wrap, wrapped, instance, args, kwargs, result, span, parent_span = None, ex:Exception = None) -> bool:
+        if is_delegation_tool(instance):
+            agent_request_wrapper = to_wrap.copy()
+            agent_request_wrapper["output_processor"] = AGENT_DELEGATION
+        else:
+            agent_request_wrapper = to_wrap
+
+        return super().hydrate_span(agent_request_wrapper, wrapped, instance, args, kwargs, result, span, parent_span, ex)
+    

monocle_apptrace/instrumentation/metamodel/langgraph/methods.py

@@ -1,14 +1,40 @@
-from monocle_apptrace.instrumentation.common.wrapper import task_wrapper
+from monocle_apptrace.instrumentation.common.wrapper import task_wrapper, atask_wrapper
 from monocle_apptrace.instrumentation.metamodel.langgraph.entities.inference import (
-    INFERENCE,
+    AGENT,
+    TOOLS,
 )
+
 LANGGRAPH_METHODS = [
     {
         "package": "langgraph.graph.state",
-         "object": "CompiledStateGraph",
-         "method": "invoke",
-         "span_name": "langgraph.graph.invoke",
-         "wrapper_method": task_wrapper,
-         "output_processor": INFERENCE
-    }
-]
+        "object": "CompiledStateGraph",
+        "method": "invoke",
+        "wrapper_method": task_wrapper,
+        "span_handler": "langgraph_agent_handler",
+        "output_processor": AGENT,
+    },
+    {
+        "package": "langgraph.graph.state",
+        "object": "CompiledStateGraph",
+        "method": "ainvoke",
+        "wrapper_method": atask_wrapper,
+        "span_handler": "langgraph_agent_handler",
+        "output_processor": AGENT,
+    },
+    {
+        "package": "langchain_core.tools.base",
+        "object": "BaseTool",
+        "method": "run",
+        "wrapper_method": task_wrapper,
+        "span_handler": "langgraph_tool_handler",
+        "output_processor": TOOLS,
+    },
+    {
+        "package": "langchain_core.tools.base",
+        "object": "BaseTool",
+        "method": "arun",
+        "wrapper_method": atask_wrapper,
+        "span_handler": "langgraph_tool_handler",
+        "output_processor": TOOLS,
+    },
+]

monocle_apptrace/instrumentation/metamodel/litellm/_helper.py

@@ -0,0 +1,89 @@
+"""
+This module provides utility functions for extracting system, user,
+and assistant messages from various input formats.
+"""
+import json
+import logging
+from monocle_apptrace.instrumentation.common.utils import (
+    Option,
+    get_json_dumps,
+    try_option,
+    get_exception_message,
+    get_status_code,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def extract_messages(kwargs):
+    """Extract system and user messages"""
+    try:
+        messages = []
+        if 'messages' in kwargs and len(kwargs['messages']) > 0:
+            for msg in kwargs['messages']:
+                if msg.get('content') and msg.get('role'):
+                    messages.append({msg['role']: msg['content']})
+
+        return [get_json_dumps(message) for message in messages]
+    except Exception as e:
+        logger.warning("Warning: Error occurred in extract_messages: %s", str(e))
+        return []
+
+
+def extract_assistant_message(arguments):
+    try:
+        messages = []
+        status = get_status_code(arguments)
+        if status == 'success' or status == 'completed':
+            response = arguments["result"]
+            if (response is not None and hasattr(response, "choices") and len(response.choices) > 0):
+                if hasattr(response.choices[0], "message"):
+                    role = (
+                        response.choices[0].message.role
+                        if hasattr(response.choices[0].message, "role")
+                        else "assistant"
+                    )
+                    messages.append({role: response.choices[0].message.content})
+            return get_json_dumps(messages[0]) if messages else ""
+        else:
+            if arguments["exception"] is not None:
+                return get_exception_message(arguments)
+            elif hasattr(arguments["result"], "error"):
+                return arguments["result"].error
+
+    except (IndexError, AttributeError) as e:
+        logger.warning(
+            "Warning: Error occurred in extract_assistant_message: %s", str(e)
+        )
+        return None
+
+def extract_provider_name(url):
+    """Extract host from a URL string (e.g., https://api.openai.com/v1/ -> api.openai.com)"""
+    if not url:
+        return None
+    return url.split("//")[-1].split("/")[0]
+
+def resolve_from_alias(my_map, alias):
+    """Find a alias that is not none from list of aliases"""
+
+    for i in alias:
+        if i in my_map.keys():
+            return my_map[i]
+    return None
+
+
+def update_span_from_llm_response(response):
+    meta_dict = {}
+    token_usage = None
+    if response is not None:
+        if token_usage is None and hasattr(response, "usage") and response.usage is not None:
+            token_usage = response.usage
+        elif token_usage is None and hasattr(response, "response_metadata"):
+            token_usage = getattr(response.response_metadata, "token_usage", None) \
+                if hasattr(response.response_metadata, "token_usage") \
+                else response.response_metadata.get("token_usage", None)
+        if token_usage is not None:
+            meta_dict.update({"completion_tokens": getattr(token_usage, "completion_tokens", None) or getattr(token_usage, "output_tokens", None)})
+            meta_dict.update({"prompt_tokens": getattr(token_usage, "prompt_tokens", None) or getattr(token_usage, "input_tokens", None)})
+            meta_dict.update({"total_tokens": getattr(token_usage, "total_tokens")})
+    return meta_dict

monocle_apptrace/instrumentation/metamodel/litellm/entities/inference.py

@@ -0,0 +1,108 @@
+from monocle_apptrace.instrumentation.metamodel.litellm import (
+    _helper,
+)
+from monocle_apptrace.instrumentation.common.utils import (
+    get_error_message,
+    resolve_from_alias,
+    get_llm_type,
+)
+INFERENCE = {
+    "type": "inference",
+    "attributes": [
+        [
+            {
+                "_comment": "provider type ,name , deployment , inference_endpoint",
+                "attribute": "type",
+                "accessor": lambda arguments: "inference."
+                + (get_llm_type(arguments['instance']) or 'generic')
+            },
+            {
+                "attribute": "provider_name",
+                "accessor": lambda arguments: _helper.extract_provider_name(
+                    resolve_from_alias(
+                        arguments["kwargs"],
+                        ["azure_endpoint", "api_base", "endpoint"],
+                    )
+                ),
+            },
+            {
+                "attribute": "deployment",
+                "accessor": lambda arguments: resolve_from_alias(
+                    arguments["kwargs"].__dict__,
+                    [
+                        "engine",
+                        "azure_deployment",
+                        "deployment_name",
+                        "deployment_id",
+                        "deployment",
+                    ],
+                ),
+            },
+            {
+                "attribute": "inference_endpoint",
+                "accessor": lambda arguments: resolve_from_alias(
+                    arguments["kwargs"],
+                    ["azure_endpoint", "api_base", "endpoint"],
+                )
+            },
+        ],
+        [
+            {
+                "_comment": "LLM Model",
+                "attribute": "name",
+                "accessor": lambda arguments: resolve_from_alias(
+                    arguments["kwargs"],
+                    ["model", "model_name", "endpoint_name", "deployment_name"],
+                ),
+            },
+            {
+                "attribute": "type",
+                "accessor": lambda arguments: "model.llm."
+                + resolve_from_alias(
+                    arguments["kwargs"],
+                    ["model", "model_name", "endpoint_name", "deployment_name"],
+                ),
+            },
+        ],
+    ],
+    "events": [
+        {
+            "name": "data.input",
+            "attributes": [
+                {
+                    "_comment": "this is instruction and user query to LLM",
+                    "attribute": "input",
+                    "accessor": lambda arguments: _helper.extract_messages(
+                        arguments["kwargs"]
+                    ),
+                }
+            ],
+        },
+        {
+            "name": "data.output",
+            "attributes": [
+
+                {
+                    "attribute": "error_code",
+                    "accessor": lambda arguments: get_error_message(arguments)
+                },
+                {
+                    "_comment": "this is result from LLM",
+                    "attribute": "response",
+                    "accessor": lambda arguments: _helper.extract_assistant_message(arguments),
+                }
+            ],
+        },
+        {
+            "name": "metadata",
+            "attributes": [
+                {
+                    "_comment": "this is metadata usage from LLM",
+                    "accessor": lambda arguments: _helper.update_span_from_llm_response(
+                        arguments["result"]
+                    ),
+                }
+            ],
+        },
+    ],
+}

monocle_apptrace/instrumentation/metamodel/litellm/methods.py

@@ -0,0 +1,19 @@
+from monocle_apptrace.instrumentation.common.wrapper import atask_wrapper, task_wrapper
+from monocle_apptrace.instrumentation.metamodel.litellm.entities.inference import INFERENCE
+
+LITELLM_METHODS = [
+    {
+        "package": "litellm.llms.openai.openai",
+        "object": "OpenAIChatCompletion",
+        "method": "completion",
+        "wrapper_method": task_wrapper,
+        "output_processor": INFERENCE
+    },
+    {
+        "package": "litellm.llms.azure.azure",
+        "object": "AzureChatCompletion",
+        "method": "completion",
+        "wrapper_method": task_wrapper,
+        "output_processor": INFERENCE
+    }
+]