monocle-apptrace 0.5.3__py3-none-any.whl → 0.6.0__py3-none-any.whl

monocle_apptrace/exporters/file_exporter.py

@@ -55,6 +55,9 @@ class FileSpanExporter(SpanExporterBase):
         else:
             return self._process_spans(spans, is_root_span=is_root_span)
 
+    def set_service_name(self, service_name: str) -> None:
+        self.service_name = service_name
+
     def _cleanup_expired_handles(self) -> None:
         """Close and remove file handles that have exceeded the timeout."""
         current_time = datetime.now()
@@ -130,7 +133,10 @@ class FileSpanExporter(SpanExporterBase):
         
         # Process spans for each trace
         for trace_id, trace_spans in spans_by_trace.items():
-            service_name = trace_spans[0].resource.attributes.get(SERVICE_NAME, "unknown")
+            if self.service_name is not None:
+                service_name = self.service_name
+            else:
+                service_name = trace_spans[0].resource.attributes.get(SERVICE_NAME, "unknown")
             handle, file_path, is_first_span = self._get_or_create_handle(trace_id, service_name)
             
             if handle is None:

monocle_apptrace/instrumentation/common/instrumentor.py

@@ -165,7 +165,7 @@ def setup_monocle_telemetry(
         span_handlers: Dict[str,SpanHandler] = None,
         wrapper_methods: List[Union[dict,WrapperMethod]] = None,
         union_with_default_methods: bool = True,
-        monocle_exporters_list:str = None) -> None:
+        monocle_exporters_list:str = None) -> MonocleInstrumentor:
     """
     Set up Monocle telemetry for the application.
 

monocle_apptrace/instrumentation/common/span_handler.py

@@ -26,7 +26,8 @@ WORKFLOW_TYPE_MAP = {
     "anthropic": "workflow.anthropic",
     "gemini": "workflow.gemini",
     "litellm": "workflow.litellm",
-    "mistralai": "workflow.mistral"
+    "mistralai": "workflow.mistral",
+    "huggingface_hub": "workflow.huggingface"
 }
 
 FRAMEWORK_WORKFLOW_LIST = [

monocle_apptrace/instrumentation/common/wrapper_method.py

@@ -5,6 +5,7 @@ from monocle_apptrace.instrumentation.common.span_handler import SpanHandler, No
 from monocle_apptrace.instrumentation.metamodel.azureaiinference.methods import AZURE_AI_INFERENCE_METHODS
 from monocle_apptrace.instrumentation.metamodel.botocore.methods import BOTOCORE_METHODS
 from monocle_apptrace.instrumentation.metamodel.botocore.handlers.botocore_span_handler import BotoCoreSpanHandler
+from monocle_apptrace.instrumentation.metamodel.hugging_face.methods import HUGGING_FACE_METHODS
 from monocle_apptrace.instrumentation.metamodel.langchain.methods import (
     LANGCHAIN_METHODS,
 )
@@ -109,7 +110,8 @@ DEFAULT_METHODS_LIST = (
     A2A_CLIENT_METHODS +
     LITELLM_METHODS +
     ADK_METHODS +
-    MISTRAL_METHODS
+    MISTRAL_METHODS +
+    HUGGING_FACE_METHODS
 )
 
 MONOCLE_SPAN_HANDLERS: Dict[str, SpanHandler] = {

monocle_apptrace/instrumentation/metamodel/adk/_helper.py

@@ -82,7 +82,7 @@ def extract_agent_input(arguments: Dict[str, Any]) -> Any:
     Returns:
         Any: The extracted input data
     """
-    return arguments['args'][0].user_content.parts[0].text
+    return [arguments['args'][0].user_content.parts[0].text]
 
 def extract_agent_request_input(arguments: Dict[str, Any]) -> Any:
     """
@@ -94,7 +94,7 @@ def extract_agent_request_input(arguments: Dict[str, Any]) -> Any:
     Returns:
         Any: The extracted input data
     """
-    return arguments['kwargs']['new_message'].parts[0].text if 'new_message' in arguments['kwargs'] else None
+    return [arguments['kwargs']['new_message'].parts[0].text] if 'new_message' in arguments['kwargs'] else []
 
 def extract_agent_response(result: Any) -> Any:
     """
@@ -107,7 +107,9 @@ def extract_agent_response(result: Any) -> Any:
         Any: The extracted response data
     """
     if result:
-        return result.content.parts[0].text
+        return str(result.content.parts[0].text)
+    else:
+        return ""
 
 def get_tool_name(instance: Any) -> str:
     """
@@ -179,7 +181,7 @@ def extract_tool_input(arguments: Dict[str, Any]) -> Any:
     Returns:
         Any: The extracted input data
     """
-    return str(arguments['kwargs'].get('args'))
+    return [str(arguments['kwargs'].get('args'))]
 
 def extract_tool_response(result: Any) -> Any:
     """

monocle_apptrace/instrumentation/metamodel/adk/entities/agent.py

@@ -1,6 +1,7 @@
 from monocle_apptrace.instrumentation.common.constants import SPAN_SUBTYPES, SPAN_TYPES
 from monocle_apptrace.instrumentation.common.utils import get_error_message
 from monocle_apptrace.instrumentation.metamodel.adk import _helper
+from monocle_apptrace.instrumentation.common.utils import get_error_message
 AGENT = {
       "type": SPAN_TYPES.AGENTIC_INVOCATION,
       "subtype": SPAN_SUBTYPES.ROUTING,
@@ -34,7 +35,7 @@ AGENT = {
           "attributes": [
             {
                 "_comment": "this is Agent input",
-                "attribute": "query",
+                "attribute": "input",
                 "accessor": lambda arguments: _helper.extract_agent_input(arguments)
             }
           ]
@@ -42,6 +43,10 @@ AGENT = {
         {
           "name":"data.output",
           "attributes": [
+            {
+                    "attribute": "error_code",
+                    "accessor": lambda arguments: get_error_message(arguments)
+            },
             {
                 "_comment": "this is response from LLM",
                 "attribute": "response",

monocle_apptrace/instrumentation/metamodel/agents/_helper.py

@@ -50,21 +50,21 @@ def extract_agent_input(arguments):
         if len(arguments["args"]) > 1:
             input_data = arguments["args"][1]
             if isinstance(input_data, str):
-                return input_data
+                return [input_data]
             elif isinstance(input_data, list):
                 # Handle list of input items
-                return get_json_dumps(input_data)
+                return input_data
 
         # Fallback to kwargs
         if "original_input" in arguments["kwargs"]:
             input_data = arguments["kwargs"]["original_input"]
             if isinstance(input_data, str):
-                return input_data
+                return [input_data]
             elif isinstance(input_data, list):
-                return get_json_dumps(input_data)
+                return input_data
     except Exception as e:
         logger.warning("Warning: Error occurred in extract_agent_input: %s", str(e))
-    return None
+    return []
 
 
 def get_agent_name(arguments) -> str:

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

@@ -1,6 +1,7 @@
 from monocle_apptrace.instrumentation.common.constants import AGENT_REQUEST_SPAN_NAME, SPAN_SUBTYPES, SPAN_TYPES
 from monocle_apptrace.instrumentation.common.utils import get_error_message
 from monocle_apptrace.instrumentation.metamodel.agents import _helper
+from monocle_apptrace.instrumentation.common.utils import get_error_message
 
 AGENT = {
     "type": SPAN_TYPES.AGENTIC_INVOCATION,
@@ -35,7 +36,7 @@ AGENT = {
             "attributes": [
                 {
                     "_comment": "this is Agent input",
-                    "attribute": "query",
+                    "attribute": "input",
                     "accessor": lambda arguments: _helper.extract_agent_input(
                         arguments
                     ),
@@ -45,6 +46,10 @@ AGENT = {
         {
             "name": "data.output",
             "attributes": [
+                {
+                    "attribute": "error_code",
+                    "accessor": lambda arguments: get_error_message(arguments)
+                },
                 {
                     "_comment": "this is response from Agent",
                     "attribute": "response",
@@ -73,7 +78,7 @@ AGENT = {
 }
 
 AGENT_REQUEST = {
-    "type": AGENT_REQUEST_SPAN_NAME,
+    "type": SPAN_TYPES.AGENTIC_REQUEST,
     "subtype": SPAN_SUBTYPES.PLANNING,
     "attributes": [
         [

monocle_apptrace/instrumentation/metamodel/finish_types.py

@@ -14,6 +14,7 @@ class FinishType(Enum):
     TOOL_CALL_ERROR = "tool_call_error"
     REFUSAL = "refusal"
     RATE_LIMITED = "rate_limited"
+    TOOL_CALL = "tool_call"
 
 # OpenAI finish reason mapping
 OPENAI_FINISH_REASON_MAPPING = {
@@ -274,6 +275,24 @@ HAYSTACK_FINISH_REASON_MAPPING = {
     "OTHER": FinishType.ERROR.value,
 }
 
+MISTRAL_FINISH_REASON_MAPPING = {
+    "stop": FinishType.SUCCESS.value,
+    "tool_calls": FinishType.TOOL_CALL.value,  # New category for tool calls
+    "length": FinishType.TRUNCATED.value,
+    # Mistral's API documentation does not explicitly mention other finish reasons like "content_filter" or "refusal".
+    # However, in case of an API-level error, the response itself would likely be an HTTP error rather than a
+    # successful response with a specific finish reason.
+}
+
+HUGGING_FACE_FINISH_REASON_MAPPING = {
+    "stop": FinishType.SUCCESS.value,
+    "tool_calls": FinishType.TOOL_CALL.value,  # New category for tool calls
+    "length": FinishType.TRUNCATED.value,
+    # Hugging Face's API documentation does not explicitly mention other finish reasons like "content_filter" or "refusal".
+    # However, in case of an API-level error, the response itself would likely be an HTTP error rather than a
+    # successful response with a specific finish reason.
+}
+
 ADK_FINISH_REASON_MAPPING = GEMINI_FINISH_REASON_MAPPING
 
 def map_openai_finish_reason_to_finish_type(finish_reason):
@@ -462,4 +481,16 @@ def map_adk_finish_reason_to_finish_type(finish_reason):
     """Map ADK finish_reason to standardized finish_type."""
     if not finish_reason:
         return None
-    return ADK_FINISH_REASON_MAPPING.get(finish_reason, None)
+    return ADK_FINISH_REASON_MAPPING.get(finish_reason, None)
+
+def map_mistral_finish_reason_to_finish_type(finish_reason):
+    """Map Mistral finish_reason to standardized finish_type."""
+    if not finish_reason:
+        return None
+    return MISTRAL_FINISH_REASON_MAPPING.get(finish_reason, None)
+
+def map_hf_finish_reason_to_finish_type(finish_reason):
+    """Map Hugging Face finish_reason to standardized finish_type."""
+    if not finish_reason:
+        return None
+    return HUGGING_FACE_FINISH_REASON_MAPPING.get(finish_reason, None)

monocle_apptrace/instrumentation/metamodel/hugging_face/_helper.py

@@ -0,0 +1,138 @@
+import os
+import json
+import logging
+from opentelemetry.context import get_value
+from monocle_apptrace.instrumentation.common.constants import (
+    AGENT_PREFIX_KEY,
+    INFERENCE_AGENT_DELEGATION,
+    INFERENCE_TURN_END,
+    INFERENCE_TOOL_CALL,
+)
+from monocle_apptrace.instrumentation.common.utils import (
+    Option,
+    get_json_dumps,
+    try_option,
+)
+
+from monocle_apptrace.instrumentation.metamodel.finish_types import map_hf_finish_reason_to_finish_type
+
+logger = logging.getLogger(__name__)
+
+def update_input_span_events(kwargs):
+    input_text = ""
+    print("DEBUG kwargs:", kwargs)
+    if "inputs" in kwargs:
+        if isinstance(kwargs["inputs"], list):
+            input_text = " | ".join(str(i) for i in kwargs["inputs"])
+        else:
+            input_text = str(kwargs["inputs"])
+    elif "messages" in kwargs:
+        input_text = json.dumps(kwargs["messages"])
+    return {"input": input_text}  # always a dict with 'input'
+
+
+
+def update_output_span_events(result):
+    try:
+        if hasattr(result, "choices") and result.choices:
+            output = [c.message for c in result.choices]
+            output_str = json.dumps(output)
+            return output_str[:200] + "..." if len(output_str) > 200 else output_str
+    except Exception as e:
+        logger.warning("Error in update_output_span_events: %s", str(e))
+    return ""
+
+def extract_messages(kwargs):
+    """Extract system and user messages"""
+    try:
+        messages = []
+        if "system" in kwargs and isinstance(kwargs["system"], str):
+            messages.append({"system": kwargs["system"]})
+        if 'messages' in kwargs and kwargs['messages']:
+            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):
+    """
+    Extract the assistant message from a Mistral response or stream chunks.
+    Returns a JSON string like {"assistant": "<text>"}.
+    """
+    try:
+        result = arguments.get("result") if isinstance(arguments, dict) else arguments
+        if result is None:
+            return ""
+
+        # Handle full response
+        if hasattr(result, "choices") and result.choices:
+            msg_obj = result.choices[0].message
+            return get_json_dumps({msg_obj.role: msg_obj.content})
+
+        # Handle streaming: result might be a list of CompletionEvent chunks
+        if isinstance(result, list):
+            content = []
+            for chunk in result:
+                if hasattr(chunk, "data") and hasattr(chunk.data, "choices") and chunk.data.choices:
+                    choice = chunk.data.choices[0]
+                    if hasattr(choice, "delta") and hasattr(choice.delta, "content"):
+                        content.append(choice.delta.content or "")
+            return get_json_dumps({"assistant": "".join(content)})
+
+        return ""
+
+    except Exception as e:
+        logger.warning("Warning in extract_assistant_message: %s", str(e))
+        return ""
+    
+def update_span_from_llm_response(result, include_token_counts=False):
+    tokens = {
+        "completion_tokens": getattr(result.usage, "completion_tokens", 0),
+        "prompt_tokens": getattr(result.usage, "prompt_tokens", 0),
+        "total_tokens": getattr(result.usage, "total_tokens", 0),
+    } if include_token_counts else {}
+    # Add other metadata fields like finish_reason, etc.
+    return {**tokens, "inference_sub_type": "turn_end"}
+
+
+def get_exception_status_code(exc):
+    if exc is None:
+        return "success"
+    code = getattr(exc, "status_code", None)
+    if code == 401:
+        return "unauthorized"
+    elif code == 403:
+        return "forbidden"
+    elif code == 404:
+        return "not_found"
+    return "error"
+
+def map_finish_reason_to_finish_type(finish_reason):
+    """Map Hugging Face finish_reason to finish_type, similar to OpenAI mapping."""
+    return map_hf_finish_reason_to_finish_type(finish_reason)
+
+
+def agent_inference_type(result):
+    """
+    Simple agent inference type logic: if message contains AGENT_PREFIX_KEY,
+    mark as delegation; otherwise it's a normal turn_end.
+    """
+    try:
+        assistant_msg = extract_assistant_message(result)
+        if assistant_msg and AGENT_PREFIX_KEY in assistant_msg:
+            return INFERENCE_AGENT_DELEGATION
+    except Exception as e:
+        logger.warning("Error in agent_inference_type: %s", str(e))
+    return INFERENCE_TURN_END
+
+
+def extract_finish_reason(result):
+    try:
+        return getattr(result, "finish_reason", None)
+    except Exception:
+        return None
+
+

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

@@ -0,0 +1,97 @@
+from monocle_apptrace.instrumentation.common.constants import SPAN_TYPES
+from monocle_apptrace.instrumentation.common.utils import get_error_message, resolve_from_alias
+from monocle_apptrace.instrumentation.metamodel.hugging_face import _helper
+
+
+INFERENCE = {
+    "type": SPAN_TYPES.INFERENCE,
+    "attributes": [
+        [
+            {
+                "_comment": "provider type, name, deployment, inference_endpoint",
+                "attribute": "type",
+                "accessor": lambda arguments: "inference.huggingface"
+            },
+            {
+                "attribute": "provider_name",
+                "accessor": lambda arguments: "huggingface"
+            },
+            {
+                "attribute": "inference_endpoint",
+                "accessor": lambda arguments: "https://api-inference.huggingface.co/v1/"
+            }
+        ],
+        [
+            {
+                "_comment": "LLM Model (repo ID on Hugging Face hub)",
+                "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": "result from Hugging Face inference",
+                    "attribute": "response",
+                    "accessor": lambda arguments: _helper.extract_assistant_message(arguments)
+                }
+            ]
+        },
+        {
+            "name": "metadata",
+            "attributes": [
+                {
+                    "_comment": "this is metadata usage from LLM, includes token counts",
+                    "accessor": lambda arguments: _helper.update_span_from_llm_response(
+                        arguments.get("result"),
+                        include_token_counts=True  # new flag for streaming handling
+                    )
+                },
+                {
+                    "_comment": "finish reason from Hugging Face response",
+                    "attribute": "finish_reason",
+                    "accessor": lambda arguments: _helper.extract_finish_reason(arguments)
+                },
+                {
+                    "_comment": "finish type mapped from finish reason",
+                    "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/hugging_face/methods.py

@@ -0,0 +1,23 @@
+from monocle_apptrace.instrumentation.common.wrapper import atask_wrapper, task_wrapper
+from monocle_apptrace.instrumentation.metamodel.hugging_face.entities.inference import (
+    INFERENCE,
+)
+
+HUGGING_FACE_METHODS = [
+    {
+        "package": "huggingface_hub",
+        "object": "InferenceClient",
+        "method": "chat_completion",  # sync
+        "wrapper_method": task_wrapper,
+        "span_handler": "non_framework_handler",
+        "output_processor": INFERENCE,
+    },
+    {
+        "package": "huggingface_hub",
+        "object": "AsyncInferenceClient",
+        "method": "chat_completion",  # async
+        "wrapper_method": atask_wrapper,
+        "span_handler": "non_framework_handler",
+        "output_processor": INFERENCE,
+    },
+]

monocle_apptrace/instrumentation/metamodel/langgraph/_helper.py

@@ -25,10 +25,12 @@ def agent_instructions(arguments):
 def extract_agent_input(arguments):
     if arguments['result'] is not None and 'messages' in arguments['result']:
         history = arguments['result']['messages']
+        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
+                messages.append(message.content)
+        return messages
+    return []
 
 def get_inference_endpoint(arguments):
     inference_endpoint = resolve_from_alias(arguments['instance'].client.__dict__, ['azure_endpoint', 'api_base', '_base_url'])

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

@@ -2,6 +2,7 @@ from monocle_apptrace.instrumentation.common.constants import AGENT_REQUEST_SPAN
 from monocle_apptrace.instrumentation.metamodel.langgraph import (
     _helper
 )
+from monocle_apptrace.instrumentation.common.utils import get_error_message
 
 AGENT = {
       "type": SPAN_TYPES.AGENTIC_INVOCATION,
@@ -31,7 +32,7 @@ AGENT = {
           "attributes": [
             {
                 "_comment": "this is Agent input",
-                "attribute": "query",
+                "attribute": "input",
                 "accessor": lambda arguments: _helper.extract_agent_input(arguments)
             }
           ]
@@ -39,6 +40,10 @@ AGENT = {
         {
           "name":"data.output",
           "attributes": [
+            {
+                    "attribute": "error_code",
+                    "accessor": lambda arguments: get_error_message(arguments)
+            },
             {
                 "_comment": "this is response from LLM",
                 "attribute": "response",
@@ -50,7 +55,7 @@ AGENT = {
     }
 
 AGENT_REQUEST = {
-      "type": AGENT_REQUEST_SPAN_NAME,
+      "type": SPAN_TYPES.AGENTIC_REQUEST,
       "subtype": SPAN_SUBTYPES.PLANNING,
       "attributes": [
         [

monocle_apptrace/instrumentation/metamodel/mcp/_helper.py

@@ -22,7 +22,7 @@ def get_output_text(arguments):
         for tool in arguments["result"].tools:
             if hasattr(tool, "name"):
                 tools.append(tool.name)
-        return tools
+        return ", ".join(tools)  
     if (
         "result" in arguments
         and hasattr(arguments["result"], "content")
@@ -32,7 +32,7 @@ def get_output_text(arguments):
         for content in arguments["result"].content:
             if hasattr(content, "text"):
                 ret_val.append(content.text)
-        return ret_val
+        return " ".join(ret_val)
 
 
 def get_name(arguments):
@@ -63,17 +63,18 @@ def get_params_arguments(arguments):
 
     args = arguments["args"]
     if (
-        args
+       args
         and hasattr(args[0], "root")
         and hasattr(args[0].root, "params")
         and hasattr(args[0].root.params, "arguments")
     ):
         # If the first argument has a root with params and arguments, return those arguments
         try:
-            return json.dumps(args[0].root.params.arguments)
+            return [json.dumps(args[0].root.params.arguments)]
         except (TypeError, ValueError) as e:
             logger.error(f"Error serializing arguments: {e}")
-            return str(args[0].root.params.arguments)
+            return [str(args[0].root.params.arguments)]
+    return []
 
 
 def get_url(arguments):