monocle-apptrace 0.0.1__py3-none-any.whl

monocle_apptrace/README.md

@@ -0,0 +1,77 @@
+#Monocle User Guide
+
+## Monocle Concepts
+### Traces
+Traces are the full view of a single end-to-end application KPI eg Chatbot application to provide a response to end user’s question. Traces consists of various metadata about the application run including status, start time, duration, input/outputs etc. It also includes a list of individual steps aka “spans with details about that step.
+It’s typically the workflow code components of an application that generate the traces for application runs. 
+### Spans
+Spans are the individual steps executed by the application to perform a GenAI related task” eg app retrieving vectors from DB, app querying LLM for inference etc. The span includes the type of operation, start time, duration and metadata relevant to that step eg Model name, parameters and model endpoint/server for an inference request.
+It’s typically the workflow code components of an application that generate the traces for application runs.
+
+## Setup Monocle
+- You can download Monocle library releases from Pypi
+``` 
+    > python3 -m pip install pipenv
+    > pip install monocle-observability
+```
+- You can locally build and install Monocle library from source
+```
+> pip install .
+> pip install -e ".[dev]"
+
+> python3 -m pip install pipenv
+> pipenv install build
+```
+
+## Examples 
+### Enable Monocle tracing in your application
+```python
+from monocle_apptrace.instrumentor import setup_monocle_telemetry
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+from langchain.chains import LLMChain
+from langchain_openai import OpenAI
+from langchain.prompts import PromptTemplate
+
+# Call the setup Monocle telemetry method
+setup_monocle_telemetry(workflow_name = "simple_math_app",
+        span_processors=[BatchSpanProcessor(ConsoleSpanExporter())])
+
+llm = OpenAI()
+prompt = PromptTemplate.from_template("1 + {number} = ")
+
+chain = LLMChain(llm=llm, prompt=prompt)
+chain.invoke({"number":2})
+
+# Request callbacks: Finally, let's use the request `callbacks` to achieve the same result
+chain = LLMChain(llm=llm, prompt=prompt)
+chain.invoke({"number":2}, {"callbacks":[handler]})
+    
+```
+
+### Monitoring custom methods with Monocle
+
+```python
+from monocle_apptrace.wrapper import WrapperMethod,task_wrapper,atask_wrapper
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+
+# extend the default wrapped methods list as follows
+app_name = "simple_math_app"
+setup_monocle_telemetry(
+        workflow_name=app_name,
+        span_processors=[BatchSpanProcessor(ConsoleSpanExporter())],
+        wrapper_methods=[
+            WrapperMethod(
+                package="langchain.schema.runnable",
+                object="RunnableParallel",
+                method="invoke",
+                span_name="langchain.workflow",
+                wrapper=task_wrapper),
+            WrapperMethod(
+                package="langchain.schema.runnable",
+                object="RunnableParallel",
+                method="ainvoke",
+                span_name="langchain.workflow",
+                wrapper=atask_wrapper)
+        ])
+
+```

monocle_apptrace/__init__.py

@@ -0,0 +1,2 @@
+
+

monocle_apptrace/haystack/__init__.py

@@ -0,0 +1,28 @@
+
+
+import logging
+from monocle_apptrace.haystack.wrap_openai import wrap_openai
+from monocle_apptrace.haystack.wrap_pipeline import wrap as wrap_pipeline
+
+logger = logging.getLogger(__name__)
+
+HAYSTACK_METHODS = [
+    {
+        "package": "haystack.components.generators.openai",
+        "object": "OpenAIGenerator",
+        "method": "run",
+        "wrapper": wrap_openai,
+    },
+    {
+        "package": "haystack.components.generators.chat.openai",
+        "object": "OpenAIChatGenerator",
+        "method": "run",
+        "wrapper": wrap_openai,
+    },
+    {
+        "package": "haystack.core.pipeline.pipeline",
+        "object": "Pipeline",
+        "method": "run",
+        "wrapper": wrap_pipeline,
+    },
+]

monocle_apptrace/haystack/wrap_node.py

@@ -0,0 +1,27 @@
+
+
+import logging
+from opentelemetry import context as context_api
+from opentelemetry.context import attach, set_value
+from opentelemetry.instrumentation.utils import (
+    _SUPPRESS_INSTRUMENTATION_KEY,
+)
+from monocle_apptrace.wrap_common import WORKFLOW_TYPE_MAP, with_tracer_wrapper
+
+logger = logging.getLogger(__name__)
+
+
+@with_tracer_wrapper
+def wrap(tracer, to_wrap, wrapped, instance, args, kwargs):
+    if context_api.get_value(_SUPPRESS_INSTRUMENTATION_KEY):
+        return wrapped(*args, **kwargs)
+    name = instance.name
+    attach(set_value("workflow_name", name))
+    with tracer.start_as_current_span(f"{name}.task") as span:
+        workflow_name = span.resource.attributes.get("service.name")
+        span.set_attribute("workflow_name",workflow_name)
+        span.set_attribute("workflow_type", WORKFLOW_TYPE_MAP["haystack"])
+        
+        response = wrapped(*args, **kwargs)
+
+    return response

monocle_apptrace/haystack/wrap_openai.py

@@ -0,0 +1,52 @@
+
+
+import logging
+from opentelemetry import context as context_api
+from opentelemetry.instrumentation.utils import _SUPPRESS_INSTRUMENTATION_KEY
+from monocle_apptrace.wrap_common import with_tracer_wrapper
+from monocle_apptrace.utils import (
+    dont_throw,
+    set_span_attribute
+)
+
+logger = logging.getLogger(__name__)
+
+@dont_throw
+def _set_input_attributes(span, kwargs, instance, args):
+    set_span_attribute(span, "llm_input", kwargs.get("prompt"))
+
+    if 'model' in instance.__dict__:
+        model_name = instance.__dict__.get("model")
+        set_span_attribute(span, "openai_model_name", model_name)
+
+    return
+
+@dont_throw
+def _set_response_attributes(span, response):
+
+    if "meta" in response:
+        token_usage = response["meta"][0]["usage"]
+        set_span_attribute(span, "completion_tokens", token_usage.get("completion_tokens"))
+        set_span_attribute(span, "prompt_tokens", token_usage.get("prompt_tokens"))
+        set_span_attribute(span, "total_tokens", token_usage.get("total_tokens"))
+
+
+@with_tracer_wrapper
+def wrap_openai(tracer, to_wrap, wrapped, instance, args, kwargs):
+    if context_api.get_value(_SUPPRESS_INSTRUMENTATION_KEY):
+        return wrapped(*args, **kwargs)
+
+    with tracer.start_as_current_span("haystack.openai") as span:
+        if span.is_recording():
+            _set_input_attributes(span, kwargs, instance, args)
+
+
+        
+        response = wrapped(*args, **kwargs)
+
+        if response:
+            if span.is_recording():
+                _set_response_attributes(span, response)
+                
+
+        return response

monocle_apptrace/haystack/wrap_pipeline.py

@@ -0,0 +1,49 @@
+
+
+import logging
+from opentelemetry import context as context_api
+from opentelemetry.context import attach, set_value
+from opentelemetry.instrumentation.utils import (
+    _SUPPRESS_INSTRUMENTATION_KEY,
+)
+from monocle_apptrace.wrap_common import PROMPT_INPUT_KEY, PROMPT_OUTPUT_KEY, WORKFLOW_TYPE_MAP, with_tracer_wrapper
+
+logger = logging.getLogger(__name__)
+
+
+@with_tracer_wrapper
+def wrap(tracer, to_wrap, wrapped, instance, args, kwargs):
+    if context_api.get_value(_SUPPRESS_INSTRUMENTATION_KEY):
+        return wrapped(*args, **kwargs)
+    name = "haystack_pipeline"
+    attach(set_value("workflow_name", name))
+    inputs = set()
+    input = get_workflow_input(args, inputs)
+
+    with tracer.start_as_current_span(f"{name}.workflow") as span:
+        span.set_attribute(PROMPT_INPUT_KEY, input)
+        workflow_name = span.resource.attributes.get("service.name")
+        set_workflow_attributes(span, workflow_name)
+        
+        response = wrapped(*args, **kwargs)
+        set_workflow_output(span, response)
+    return response
+
+def set_workflow_output(span, response):
+    workflow_output: str = response["llm"]["replies"][0]
+    span.set_attribute(PROMPT_OUTPUT_KEY, workflow_output)
+
+def get_workflow_input(args, inputs):
+    for value in args[0].values():
+        for text in value.values():
+            inputs.add(text)
+    
+    input: str = ""
+
+    for input_str in inputs:
+        input = input + input_str
+    return input
+
+def set_workflow_attributes(span, workflow_name):
+    span.set_attribute("workflow_name",workflow_name)
+    span.set_attribute("workflow_type", WORKFLOW_TYPE_MAP["haystack"])

monocle_apptrace/instrumentor.py

@@ -0,0 +1,127 @@
+
+
+import logging
+from typing import Collection,List
+from wrapt import wrap_function_wrapper
+from opentelemetry.trace import get_tracer
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from opentelemetry.instrumentation.utils import unwrap
+from opentelemetry.sdk.trace import TracerProvider, Span
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanProcessor
+from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+from opentelemetry import trace
+from monocle_apptrace.wrap_common import CONTEXT_PROPERTIES_KEY
+from monocle_apptrace.wrapper import INBUILT_METHODS_LIST, WrapperMethod
+from opentelemetry.context import get_value, attach, set_value
+
+
+logger = logging.getLogger(__name__)
+
+_instruments = ("langchain >= 0.0.346",)
+
+class MonocleInstrumentor(BaseInstrumentor):
+    
+    workflow_name: str = ""
+    user_wrapper_methods: list[WrapperMethod] = []
+    instrumented_method_list: list[object] = []
+    
+    def __init__(
+            self,
+            user_wrapper_methods: list[WrapperMethod] = []) -> None:
+        self.user_wrapper_methods = user_wrapper_methods
+        super().__init__()
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return _instruments
+
+    def _instrument(self, **kwargs):
+        tracer_provider = kwargs.get("tracer_provider")
+        tracer = get_tracer(instrumenting_module_name= __name__, tracer_provider= tracer_provider)
+
+        user_method_list = [
+            {
+                "package": method.package,
+                "object": method.object,
+                "method": method.method,
+                "span_name": method.span_name,
+                "wrapper": method.wrapper,
+            } for method in self.user_wrapper_methods]
+
+        final_method_list = user_method_list + INBUILT_METHODS_LIST
+
+        for wrapped_method in final_method_list:
+            try:
+                wrap_package = wrapped_method.get("package")
+                wrap_object = wrapped_method.get("object")
+                wrap_method = wrapped_method.get("method")
+                wrapper = wrapped_method.get("wrapper")
+                wrap_function_wrapper(
+                    wrap_package,
+                    f"{wrap_object}.{wrap_method}" if wrap_object else wrap_method,
+                    wrapper(tracer, wrapped_method),
+                )
+                self.instrumented_method_list.append(wrapped_method)
+            except Exception as ex:
+                if wrapped_method in user_method_list:
+                    logger.error(f"""_instrument wrap Exception: {str(ex)} 
+                                for package: {wrap_package},
+                                object:{wrap_object},
+                                method:{wrap_method}""")
+            
+
+    def _uninstrument(self, **kwargs):
+        for wrapped_method in self.instrumented_method_list:
+            try:
+                wrap_package = wrapped_method.get("package")
+                wrap_object = wrapped_method.get("object")
+                wrap_method = wrapped_method.get("method")
+                unwrap(
+                    f"{wrap_package}.{wrap_object}" if wrap_object else wrap_package,
+                    wrap_method,
+                )
+            except Exception as ex:
+                logger.error(f"""_instrument unwrap Exception: {str(ex)} 
+                             for package: {wrap_package},
+                             object:{wrap_object},
+                             method:{wrap_method}""")
+           
+
+def setup_monocle_telemetry(
+        workflow_name: str,
+        span_processors: List[SpanProcessor] = [],
+        wrapper_methods: List[WrapperMethod] = []):
+    resource = Resource(attributes={
+        SERVICE_NAME: workflow_name
+    })
+    traceProvider = TracerProvider(resource=resource)
+    tracerProviderDefault = trace.get_tracer_provider()
+    providerType = type(tracerProviderDefault).__name__
+    isProxyProvider = "Proxy" in providerType
+    for processor in span_processors:
+        processor.on_start = on_processor_start
+        if not isProxyProvider:
+            tracerProviderDefault.add_span_processor(processor)
+        else :
+            traceProvider.add_span_processor(processor)
+    if isProxyProvider :
+        trace.set_tracer_provider(traceProvider)
+    instrumentor = MonocleInstrumentor(user_wrapper_methods=wrapper_methods)
+    instrumentor.app_name = workflow_name
+    if not instrumentor.is_instrumented_by_opentelemetry:
+        instrumentor.instrument()
+
+
+def on_processor_start(span: Span, parent_context):
+    context_properties = get_value(CONTEXT_PROPERTIES_KEY)
+    if context_properties is not None:
+        for key, value in context_properties.items():
+            span.set_attribute(
+                f"{CONTEXT_PROPERTIES_KEY}.{key}", value
+            )    
+
+def set_context_properties(properties: dict) -> None:
+    attach(set_value(CONTEXT_PROPERTIES_KEY, properties))
+
+
+
+

monocle_apptrace/langchain/__init__.py

@@ -0,0 +1,95 @@
+
+
+from monocle_apptrace.wrap_common import allm_wrapper, atask_wrapper, llm_wrapper, task_wrapper
+
+LANGCHAIN_METHODS = [
+    {
+        "package": "langchain.prompts.base",
+        "object": "BasePromptTemplate",
+        "method": "invoke",
+        "wrapper": task_wrapper,
+    },
+    {
+        "package": "langchain.prompts.base",
+        "object": "BasePromptTemplate",
+        "method": "ainvoke",
+        "wrapper": atask_wrapper,
+    },
+    {
+        "package": "langchain.chat_models.base",
+        "object": "BaseChatModel",
+        "method": "invoke",
+        "wrapper": llm_wrapper,
+    },
+    {
+        "package": "langchain.chat_models.base",
+        "object": "BaseChatModel",
+        "method": "ainvoke",
+        "wrapper": allm_wrapper,
+    },
+    {
+        "package": "langchain_core.language_models.llms",
+        "object": "LLM",
+        "method": "_generate",
+        "wrapper": llm_wrapper,
+    },
+    {
+        "package": "langchain_core.language_models.llms",
+        "object": "LLM",
+        "method": "_agenerate",
+        "wrapper": llm_wrapper,
+    },
+    {
+        "package": "langchain_core.retrievers",
+        "object": "BaseRetriever",
+        "method": "invoke",
+        "wrapper": task_wrapper,
+    },
+    {
+        "package": "langchain_core.retrievers",
+        "object": "BaseRetriever",
+        "method": "ainvoke",
+        "wrapper": atask_wrapper,
+    },
+    {
+        "package": "langchain.schema",
+        "object": "BaseOutputParser",
+        "method": "invoke",
+        "wrapper": task_wrapper,
+    },
+    {
+        "package": "langchain.schema",
+        "object": "BaseOutputParser",
+        "method": "ainvoke",
+        "wrapper": atask_wrapper,
+    },
+    {
+        "package": "langchain.schema.runnable",
+        "object": "RunnableSequence",
+        "method": "invoke",
+        "span_name": "langchain.workflow",
+        "wrapper": task_wrapper,
+    },
+    {
+        "package": "langchain.schema.runnable",
+        "object": "RunnableSequence",
+        "method": "ainvoke",
+        "span_name": "langchain.workflow",
+        "wrapper": atask_wrapper,
+    },
+    {
+        "package": "langchain.schema.runnable",
+        "object": "RunnableParallel",
+        "method": "invoke",
+        "span_name": "langchain.workflow",
+        "wrapper": task_wrapper,
+    },
+    {
+        "package": "langchain.schema.runnable",
+        "object": "RunnableParallel",
+        "method": "ainvoke",
+        "span_name": "langchain.workflow",
+        "wrapper": atask_wrapper,
+    },
+    
+]

monocle_apptrace/llamaindex/__init__.py

@@ -0,0 +1,71 @@
+
+
+from monocle_apptrace.wrap_common import allm_wrapper, atask_wrapper, llm_wrapper, task_wrapper
+
+def get_llm_span_name_for_openai(instance):
+    if (hasattr(instance, "_is_azure_client") 
+        and callable(getattr(instance, "_is_azure_client"))
+        and instance._is_azure_client()):
+        return "llamaindex.azure_openai"
+    return "llamaindex.openai"
+
+LLAMAINDEX_METHODS = [
+    {
+        "package": "llama_index.core.indices.base_retriever",
+        "object": "BaseRetriever",
+        "method": "retrieve",
+        "span_name": "llamaindex.retrieve",
+        "wrapper": task_wrapper
+    },
+    {
+        "package": "llama_index.core.indices.base_retriever",
+        "object": "BaseRetriever",
+        "method": "aretrieve",
+        "span_name": "llamaindex.retrieve",
+        "wrapper": atask_wrapper
+    },
+    {
+        "package": "llama_index.core.base.base_query_engine",
+        "object": "BaseQueryEngine",
+        "method": "query",
+        "span_name": "llamaindex.query",
+        "wrapper": task_wrapper,
+    },
+    {
+        "package": "llama_index.core.base.base_query_engine",
+        "object": "BaseQueryEngine",
+        "method": "aquery",
+        "span_name": "llamaindex.query",
+        "wrapper": atask_wrapper,
+    },
+    {
+        "package": "llama_index.core.llms.custom",
+        "object": "CustomLLM",
+        "method": "chat",
+        "span_name": "llamaindex.llmchat",
+        "wrapper": task_wrapper,
+    },
+    {
+        "package": "llama_index.core.llms.custom",
+        "object": "CustomLLM",
+        "method": "achat",
+        "span_name": "llamaindex.llmchat",
+        "wrapper": atask_wrapper,
+    },
+    {
+        "package": "llama_index.llms.openai.base",
+        "object": "OpenAI",
+        "method": "chat",
+        "span_name": "llamaindex.openai",
+        "span_name_getter" : get_llm_span_name_for_openai,
+        "wrapper": llm_wrapper,
+    },
+     {
+        "package": "llama_index.llms.openai.base",
+        "object": "OpenAI",
+        "method": "achat",
+        "span_name": "llamaindex.openai",
+        "wrapper": allm_wrapper,
+    }
+]
+

monocle_apptrace/utils.py

@@ -0,0 +1,53 @@
+
+
+import logging
+logger = logging.getLogger(__name__)
+
+class Config:
+    exception_logger = None
+
+def set_span_attribute(span, name, value):
+    if value is not None:
+        if value != "":
+            span.set_attribute(name, value)
+    return
+
+
+def dont_throw(func):
+    """
+    A decorator that wraps the passed in function and logs exceptions instead of throwing them.
+
+    @param func: The function to wrap
+    @return: The wrapper function
+    """
+    # Obtain a logger specific to the function's module
+    logger = logging.getLogger(func.__module__)
+
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            logger.warning("Failed to execute %s, error: %s", func.__name__, str(e))
+            if Config.exception_logger:
+                Config.exception_logger(e)
+
+    return wrapper
+
+def with_tracer_wrapper(func):
+    """Helper for providing tracer for wrapper functions."""
+
+    def _with_tracer(tracer, to_wrap):
+        def wrapper(wrapped, instance, args, kwargs):
+            return func(tracer, to_wrap, wrapped, instance, args, kwargs)
+
+        return wrapper
+
+    return _with_tracer
+
+def resolve_from_alias(map, alias):
+    """Find a alias that is not none from list of aliases"""
+
+    for i in alias:
+        if i in map.keys():
+            return map[i]
+    return None

monocle_apptrace/wrap_common.py

@@ -0,0 +1,214 @@
+import logging
+import os
+
+from opentelemetry.trace import Span, Tracer
+
+from monocle_apptrace.utils import resolve_from_alias, with_tracer_wrapper
+
+logger = logging.getLogger(__name__)
+WORKFLOW_TYPE_KEY = "workflow_type"
+CONTEXT_INPUT_KEY = "context_input"
+CONTEXT_OUTPUT_KEY = "context_output"
+PROMPT_INPUT_KEY = "input"
+PROMPT_OUTPUT_KEY = "output"
+QUERY = "question"
+RESPONSE = "response"
+TAGS = "tags"
+CONTEXT_PROPERTIES_KEY = "workflow_context_properties"
+
+
+WORKFLOW_TYPE_MAP = {
+    "llama_index": "workflow.llamaindex",
+    "langchain": "workflow.langchain",
+    "haystack": "workflow.haystack"
+}
+
+@with_tracer_wrapper
+def task_wrapper(tracer: Tracer, to_wrap, wrapped, instance, args, kwargs):
+    """Instruments and calls every function defined in TO_WRAP."""
+
+    # Some Langchain objects are wrapped elsewhere, so we ignore them here
+    if instance.__class__.__name__ in ("AgentExecutor"):
+        return wrapped(*args, **kwargs)
+
+    if hasattr(instance, "name") and instance.name:
+        name = f"{to_wrap.get('span_name')}.{instance.name.lower()}"
+    elif to_wrap.get("span_name"):
+        name = to_wrap.get("span_name")
+    else:
+        name = f"langchain.task.{instance.__class__.__name__}"
+    kind = to_wrap.get("kind")
+
+    with tracer.start_as_current_span(name) as span:
+        if is_root_span(span):
+            update_span_with_prompt_input(to_wrap=to_wrap, wrapped_args=args, span=span)
+
+        #capture the tags attribute of the instance if present, else ignore 
+        try:
+            span.set_attribute(TAGS, getattr(instance, TAGS))
+        except AttributeError:
+            pass    
+        update_span_with_context_input(to_wrap=to_wrap, wrapped_args=args, span=span)
+        return_value = wrapped(*args, **kwargs)
+        update_span_with_context_output(to_wrap=to_wrap, return_value=return_value, span=span)
+
+        if is_root_span(span):
+            workflow_name = span.resource.attributes.get("service.name")
+            span.set_attribute("workflow_name",workflow_name)
+            update_span_with_prompt_output(to_wrap=to_wrap, wrapped_args=return_value, span=span)
+            update_workflow_type(to_wrap, span)
+
+    return return_value
+
+@with_tracer_wrapper
+async def atask_wrapper(tracer, to_wrap, wrapped, instance, args, kwargs):
+    """Instruments and calls every function defined in TO_WRAP."""
+
+    # Some Langchain objects are wrapped elsewhere, so we ignore them here
+    if instance.__class__.__name__ in ("AgentExecutor"):
+        return wrapped(*args, **kwargs)
+
+    if hasattr(instance, "name") and instance.name:
+        name = f"{to_wrap.get('span_name')}.{instance.name.lower()}"
+    elif to_wrap.get("span_name"):
+        name = to_wrap.get("span_name")
+    else:
+        name = f"langchain.task.{instance.__class__.__name__}"
+    kind = to_wrap.get("kind")
+    with tracer.start_as_current_span(name) as span:
+        return_value = await wrapped(*args, **kwargs)
+
+    return return_value
+
+@with_tracer_wrapper
+async def allm_wrapper(tracer, to_wrap, wrapped, instance, args, kwargs):
+    # Some Langchain objects are wrapped elsewhere, so we ignore them here
+    if instance.__class__.__name__ in ("AgentExecutor"):
+        return wrapped(*args, **kwargs)
+
+    if to_wrap.get("span_name_getter"):
+        name = to_wrap.get("span_name_getter")(instance)
+
+    elif hasattr(instance, "name") and instance.name:
+        name = f"{to_wrap.get('span_name')}.{instance.name.lower()}"
+    elif to_wrap.get("span_name"):
+        name = to_wrap.get("span_name")
+    else:
+        name = f"langchain.task.{instance.__class__.__name__}"
+    kind = to_wrap.get("kind")
+    with tracer.start_as_current_span(name) as span:
+        update_llm_endpoint(curr_span= span, instance=instance)
+
+        return_value = await wrapped(*args, **kwargs)
+
+    return return_value
+
+@with_tracer_wrapper
+def llm_wrapper(tracer: Tracer, to_wrap, wrapped, instance, args, kwargs):
+
+    # Some Langchain objects are wrapped elsewhere, so we ignore them here
+    if instance.__class__.__name__ in ("AgentExecutor"):
+        return wrapped(*args, **kwargs)
+
+    if callable(to_wrap.get("span_name_getter")):
+        name = to_wrap.get("span_name_getter")(instance)
+
+    elif hasattr(instance, "name") and instance.name:
+        name = f"{to_wrap.get('span_name')}.{instance.name.lower()}"
+    elif to_wrap.get("span_name"):
+        name = to_wrap.get("span_name")
+    else:
+        name = f"langchain.task.{instance.__class__.__name__}"
+    kind = to_wrap.get("kind")
+    with tracer.start_as_current_span(name) as span:
+        update_llm_endpoint(curr_span= span, instance=instance)
+
+        return_value = wrapped(*args, **kwargs)
+        update_span_from_llm_response(response = return_value, span = span)
+
+    return return_value
+
+def update_llm_endpoint(curr_span: Span, instance):
+    triton_llm_endpoint = os.environ.get("TRITON_LLM_ENDPOINT")
+    if triton_llm_endpoint is not None and len(triton_llm_endpoint) > 0:
+        curr_span.set_attribute("server_url", triton_llm_endpoint)
+    else:
+        if 'temperature' in instance.__dict__:
+            temp_val = instance.__dict__.get("temperature")
+            curr_span.set_attribute("temperature", temp_val)
+        # handling for model name
+        model_name =  resolve_from_alias(instance.__dict__ , ["model","model_name"])
+        curr_span.set_attribute("openai_model_name", model_name)
+        # handling AzureOpenAI deployment
+        deployment_name =  resolve_from_alias(instance.__dict__ , [ "engine", "azure_deployment", 
+                                                                   "deployment_name", "deployment_id", "deployment"])
+        curr_span.set_attribute("az_openai_deployment", deployment_name)
+        # handling the inference endpoint
+        inference_ep = resolve_from_alias(instance.__dict__,["azure_endpoint","api_base"])
+        curr_span.set_attribute("inference_endpoint",inference_ep)
+
+def is_root_span(curr_span: Span) -> bool:
+    return curr_span.parent == None
+
+def get_input_from_args(chain_args):
+    if len(chain_args) > 0 and type(chain_args[0]) == str:
+        return chain_args[0]
+    return ""
+
+def update_span_from_llm_response(response, span: Span):
+    # extract token uasge from langchain openai
+    if (response is not None and hasattr(response, "response_metadata")):
+        response_metadata = response.response_metadata
+        token_usage = response_metadata.get("token_usage")
+        if token_usage is not None:
+            span.set_attribute("completion_tokens", token_usage.get("completion_tokens"))
+            span.set_attribute("prompt_tokens", token_usage.get("prompt_tokens"))
+            span.set_attribute("total_tokens", token_usage.get("total_tokens"))
+    # extract token usage from llamaindex openai
+    if(response is not None and hasattr(response, "raw")):
+        if response.raw is not None:
+            token_usage = response.raw.get("usage")
+            if token_usage is not None:
+                if(hasattr(token_usage, "completion_tokens")):
+                    span.set_attribute("completion_tokens", token_usage.completion_tokens)
+                if(hasattr(token_usage, "prompt_tokens")):
+                    span.set_attribute("prompt_tokens", token_usage.prompt_tokens)
+                if(hasattr(token_usage, "total_tokens")):
+                    span.set_attribute("total_tokens", token_usage.total_tokens)
+
+def update_workflow_type(to_wrap, span: Span):
+    package_name = to_wrap.get('package')
+
+    for (package, workflow_type) in WORKFLOW_TYPE_MAP.items():
+        if(package_name is not None and package in package_name):
+            span.set_attribute(WORKFLOW_TYPE_KEY, workflow_type)
+
+def update_span_with_context_input(to_wrap, wrapped_args ,span: Span):
+    package_name: str = to_wrap.get('package')
+    if("langchain_core.retrievers" in package_name):
+        input_arg_text = wrapped_args[0]
+        span.add_event(CONTEXT_INPUT_KEY, {QUERY:input_arg_text})
+    if("llama_index.core.indices.base_retriever" in package_name):
+        input_arg_text = wrapped_args[0].query_str
+        span.add_event(CONTEXT_INPUT_KEY, {QUERY:input_arg_text})
+
+def update_span_with_context_output(to_wrap, return_value ,span: Span):
+    package_name: str = to_wrap.get('package')
+    if("llama_index.core.indices.base_retriever" in package_name):
+        output_arg_text = return_value[0].text
+        span.add_event(CONTEXT_OUTPUT_KEY, {RESPONSE:output_arg_text})
+
+def update_span_with_prompt_input(to_wrap, wrapped_args ,span: Span):
+    input_arg_text = wrapped_args[0]
+    
+    if isinstance(input_arg_text, dict):
+        span.add_event(PROMPT_INPUT_KEY,input_arg_text)
+    else:    
+        span.add_event(PROMPT_INPUT_KEY,{QUERY:input_arg_text})
+
+def update_span_with_prompt_output(to_wrap, wrapped_args ,span: Span):
+    package_name: str = to_wrap.get('package')
+    if(isinstance(wrapped_args, str)):
+        span.add_event(PROMPT_OUTPUT_KEY, {RESPONSE:wrapped_args})
+    if("llama_index.core.base.base_query_engine" in package_name):
+        span.add_event(PROMPT_OUTPUT_KEY, {RESPONSE:wrapped_args.response})

monocle_apptrace/wrapper.py

@@ -0,0 +1,24 @@
+
+
+from monocle_apptrace.haystack import HAYSTACK_METHODS
+from monocle_apptrace.langchain import LANGCHAIN_METHODS
+from monocle_apptrace.llamaindex import LLAMAINDEX_METHODS
+from monocle_apptrace.wrap_common import task_wrapper
+
+class WrapperMethod:
+    def __init__(
+            self,
+            package: str,
+            object: str,
+            method: str,
+            span_name: str = None,
+            wrapper = task_wrapper
+            ):
+        self.package = package
+        self.object = object
+        self.method = method
+        self.span_name = span_name
+        self.wrapper = wrapper
+
+INBUILT_METHODS_LIST = LANGCHAIN_METHODS + LLAMAINDEX_METHODS + HAYSTACK_METHODS
+

monocle_apptrace-0.0.1.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.3
+Name: monocle_apptrace
+Version: 0.0.1
+Summary: package with monocle genAI tracing
+Project-URL: Homepage, https://github.com/monocle2ai/monocle
+Project-URL: Issues, https://github.com/monocle2ai/monocle/issues
+License-File: LICENSE
+License-File: NOTICE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: opentelemetry-api>=1.21.0
+Requires-Dist: opentelemetry-instrumentation
+Requires-Dist: opentelemetry-sdk>=1.21.0
+Requires-Dist: requests
+Requires-Dist: wrapt>=1.14.0
+Provides-Extra: dev
+Requires-Dist: datasets==2.20.0; extra == 'dev'
+Requires-Dist: faiss-cpu==1.8.0; extra == 'dev'
+Requires-Dist: instructorembedding==1.0.1; extra == 'dev'
+Requires-Dist: langchain-chroma==0.1.1; extra == 'dev'
+Requires-Dist: langchain-community==0.2.5; extra == 'dev'
+Requires-Dist: langchain-openai==0.1.8; extra == 'dev'
+Requires-Dist: langchain==0.2.5; extra == 'dev'
+Requires-Dist: llama-index-embeddings-huggingface==0.2.0; extra == 'dev'
+Requires-Dist: llama-index-vector-stores-chroma==0.1.9; extra == 'dev'
+Requires-Dist: llama-index==0.10.30; extra == 'dev'
+Requires-Dist: numpy==1.26.4; extra == 'dev'
+Requires-Dist: pytest==8.0.0; extra == 'dev'
+Requires-Dist: sentence-transformers==2.6.1; extra == 'dev'
+Requires-Dist: types-requests==2.31.0.20240106; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# monocle genAI observability
+### Background
+Generative AI (GenAI) is the type of AI used to create content such as conversations, images, or video based on prior learning from existing content. GenAI relies on foundational models, which are exceptionally large ML models trained on vast amounts of generalized and unlabeled data to perform variety of general tasks such as understanding language and generating new text, audio or images from user provided prompts in a human language. Foundational models (FM) work by using learned patterns and relationships from the training data to predict the next item in a sequence given a prompt. It is cheaper and faster for data scientists to use foundational models as starting points rather than building models from scratch to build ML apps.  
+Large Language Models (LLMs) are a class of foundational models trained on text data used to perform a variety of tasks such as understanding language, reasoning over text, and generating new text based on user prompts in a human language. Examples of LLMs include ChatGPT, Llama, and Claude. 
+LLM-based AI apps leverage understanding language, reasoning & text generation to augment or automate complex tasks that typically require human intervention such as summarizing legal documents, triaging customer support tickets, or more.  
+Typically, AI developers build LLM-based AI apps that automate complex workflows by combining multiple LLMs and components such as prompts, vectors, or agents that each solve a discrete task that are connected by chains or pipelines in different ways using LLM (Large Language Model) orchestration frameworks.  
+When deployed to production, different parts of multi-component distributed LLM-based AI apps run on a combination of different kinds of AI infrastructure such as LLM-as-a-Service, GPU (graphics processing units) clouds, managed services from cloud, or custom-engineered AI stack. Typically, these systems are managed in production by IT DevOps engineers.  
+AI developers code, monitor, debug and optimize the resources in an LLM-based AI application. IT DevOps engineers monitor, troubleshoot, and optimize the services in the AI infra that the LLM-based AI application runs on. 
+
+## Introducing “Monocle – An eye for A.I.”
+The goal of project Monocle is to help GenAI developer to trace their applications. A typical GenAI application comprises of several technology components like application code/workflow, models, inferences services, vector databases etc. Understanding the dependencies and tracking application quickly becomes a difficult task. Monocle can be integrated into application code with very little to no code changes. Monocle supports tracing all GenAI technology components, application frameworks, LLM hosting services. We do all the hard work of finding what needs to be instrumented and how to instrument it. This enables the enlightened applications to generate detailed traces without any additional efforts from the developers.
+The traces are compatible with OpenTelemetry format. They are further enriched to contain lot more attribute relevant to GenAI applications like prompts. The project will have out of box support to store the traces locally and a extensibility for a third party store which can be implemented by end user or a supplied by third party vendors.    
+
+## Monocle integration
+### genAI Appliation frameworks
+- Langchain
+- LlamaIndex
+- Haystack
+### LLMs
+- OpenAI
+- Azure OpenAI
+- NVIDIA Triton
+
+## Getting started
+### Try Monocle with your python genAI application
+- Get latest Monocle python brary 
+```
+    pip install monocle_apptrace
+```
+- Enable Monocle tracing in your app by adding following
+```
+    setup_okahu_telemetry(workflow_name="your-app-name")
+```
+Please refer to [Monocle user guide](Monocle_User_Guide.md) for more details
+
+## Get involved
+### Provide feedback
+- Submit issues and enhancements requests via Github issues
+
+### Contribute
+- Monocle is community based open source project. We welcome your contributions. Please refer to the CONTRIBUTING and CODE_OF_CONDUCT for guidelines. The [contributor's guide](CONTRIBUTING.md) provides technical details of the project.
+

monocle_apptrace-0.0.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+monocle_apptrace/README.md,sha256=C0JfJtNC7LOlr_iHSxOwuZn89vuoZ2RbyeGB7ACu4iY,3094
+monocle_apptrace/__init__.py,sha256=daEdpEyAJIa8b2VkCqSKcw8PaExcB6Qro80XNes_sHA,2
+monocle_apptrace/instrumentor.py,sha256=T-g0OpR2VYm7lswyiFoBlBeRPKHX6a-mhH8q7rE-o2g,4927
+monocle_apptrace/utils.py,sha256=KZwwXK8NTbVjQo4BkFwPdccE6hzvBzawPp6an44Gmz8,1366
+monocle_apptrace/wrap_common.py,sha256=Qxwq2drHOovd0CMd7YiQbe_4FqGL07RLfu4Vek1Z-SU,9107
+monocle_apptrace/wrapper.py,sha256=95Yg_dwGv5T6qtNv-ozhXRGaDVI0P27exU2901Pw2ps,684
+monocle_apptrace/haystack/__init__.py,sha256=GspHWTmqMDxQhpTgl91xighNL8MHaWs6BF0YzzZayuE,714
+monocle_apptrace/haystack/wrap_node.py,sha256=96qUlDZtNOVIPrrDZzjJ7ZDCi70mYbd7bIEX41e-RH0,916
+monocle_apptrace/haystack/wrap_openai.py,sha256=9ecWsOUXNjTKrQjNZz1GCgkCAN9GChhasMRDmZMuANE,1585
+monocle_apptrace/haystack/wrap_pipeline.py,sha256=eVxJ4-yS4gFxInwaWy5oxNcNl44X2M7_dhBpKVFmI6Q,1622
+monocle_apptrace/langchain/__init__.py,sha256=PrZl6vxX5WsYfsPFVhumVmUGkwddAgPBFs1hpifbmZw,2519
+monocle_apptrace/llamaindex/__init__.py,sha256=iMaboVDeM5yGR01cEqCD8MotCj2FuY4QjSZmFBv4f2o,2094
+monocle_apptrace-0.0.1.dist-info/METADATA,sha256=uYd9O71FeKzrkLq6DmJYp9F62QxxZ7UfSAaGa5dPVm8,5645
+monocle_apptrace-0.0.1.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+monocle_apptrace-0.0.1.dist-info/licenses/LICENSE,sha256=ay9trLiP5I7ZsFXo6AqtkLYdRqe5S9r-DrPOvsNlZrg,9136
+monocle_apptrace-0.0.1.dist-info/licenses/NOTICE,sha256=9jn4xtwM_uUetJMx5WqGnhrR7MIhpoRlpokjSTlyt8c,112
+monocle_apptrace-0.0.1.dist-info/RECORD,,

monocle_apptrace-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

monocle_apptrace-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,51 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

monocle_apptrace-0.0.1.dist-info/licenses/NOTICE

@@ -0,0 +1,4 @@
+Monocle
+Copyright 2018-2021 Monocle Project Authors
+
+Licensed under Apache License 2.0.  See LICENSE for terms.