monocle-apptrace 0.3.0b7__tar.gz → 0.3.1__tar.gz

monocle_apptrace-0.3.1/CHANGELOG.md

@@ -0,0 +1,86 @@
+## Version 0.3.1 (2024-04-18)
+
+- Add MetaModel for Anthropic SDK ([#159](https://github.com/monocle2ai/monocle/pull/159))
+- Add openAI response for openAI and AzureOpenAI ([#158](https://github.com/monocle2ai/monocle/pull/158))
+- Update retrieval span for Boto Client ([#157](https://github.com/monocle2ai/monocle/pull/157))
+- Resolve token threshold error ([#156](https://github.com/monocle2ai/monocle/pull/156))
+- Update Inference Span ([#155](https://github.com/monocle2ai/monocle/pull/155))
+- Refactor workflow and spans ([#160](https://github.com/monocle2ai/monocle/pull/160))
+- Support monocle exporter list as parameter to `setup_monocle_telemetry()` ([#161](https://github.com/monocle2ai/monocle/pull/161))
+- Add langchain anthropic sample ([#165](https://github.com/monocle2ai/monocle/pull/165))
+
+## Version 0.3.0 (2024-12-10)
+
+- Fixed issue with passing context in async case ([#150](https://github.com/monocle2ai/monocle/pull/150))
+- Added lambda processor ([#148](https://github.com/monocle2ai/monocle/pull/148))
+- Setup package level init scripts to make the monocle import simpler ([#147](https://github.com/monocle2ai/monocle/pull/147))
+- Boto attributes and test cleanup ([#146](https://github.com/monocle2ai/monocle/pull/146))
+- Openai workflow ([#142](https://github.com/monocle2ai/monocle/pull/142))
+- Add input/output for openai embedding ([#141](https://github.com/monocle2ai/monocle/pull/141))
+- Async method and scope fix ([#140](https://github.com/monocle2ai/monocle/pull/140))
+- Bug fix for helper langchain and langgraph ([#137](https://github.com/monocle2ai/monocle/pull/137))
+- Package main script to run any app with monocle instrumentation ([#132](https://github.com/monocle2ai/monocle/pull/132))
+- Add openai api metamodel ([#131](https://github.com/monocle2ai/monocle/pull/131))
+- Support notion of scopes to group traces/snaps into logical constructs ([#130](https://github.com/monocle2ai/monocle/pull/130))
+- Add Llamaindex ReAct agent ([#127](https://github.com/monocle2ai/monocle/pull/127))
+- Langhcain input fix and s3 exporter prefix support ([#126](https://github.com/monocle2ai/monocle/pull/126))
+- Use standard AWS credential envs ([#123](https://github.com/monocle2ai/monocle/pull/123))
+- Check additional attributes for Azure OpenAI model and consolidate common method in utils ([#122](https://github.com/monocle2ai/monocle/pull/122))
+- Bug fix for accessor ([#121](https://github.com/monocle2ai/monocle/pull/121))
+- Bug fix for empty response ([#120](https://github.com/monocle2ai/monocle/pull/120))
+- Bug fix for inference endpoint ([#119](https://github.com/monocle2ai/monocle/pull/119))
+- Opendal exporter for S3 and Blob ([#117](https://github.com/monocle2ai/monocle/pull/117))
+- Handle specific ModuleNotFoundError exceptions gracefully ([#115](https://github.com/monocle2ai/monocle/pull/115))
+- Adding support for console and memory exporter to list of monocle exporters ([#113](https://github.com/monocle2ai/monocle/pull/113))
+- Add trace id propogation for constant trace id and from request ([#111](https://github.com/monocle2ai/monocle/pull/111))
+- Restructure of monoocle code for easy extensibility ([#109](https://github.com/monocle2ai/monocle/pull/109))
+- S3 update filename prefix ([#98](https://github.com/monocle2ai/monocle/pull/98))
+- Update inference span for botocore sagemaker ([#93](https://github.com/monocle2ai/monocle/pull/93))
+- Capturing inference output and token metadata for bedrock ([#82](https://github.com/monocle2ai/monocle/pull/82))
+- Add dev dependency for Mistral AI integration ([#81](https://github.com/monocle2ai/monocle/pull/81))
+- Add VectorStore deployment URL capture support ([#80](https://github.com/monocle2ai/monocle/pull/80))  
+- Clean up cloud exporter implementation ([#79](https://github.com/monocle2ai/monocle/pull/79))
+- Capture inference span input/output events attributes ([#77](https://github.com/monocle2ai/monocle/pull/77))
+- Add release automation workflows ([#76](https://github.com/monocle2ai/monocle/pull/76))
+- Fix gaps in Monocle SDK implementation ([#72](https://github.com/monocle2ai/monocle/pull/72))  
+- Add kwargs and return value handling in Accessor ([#71](https://github.com/monocle2ai/monocle/pull/71))
+- Update workflow name formatting ([#69](https://github.com/monocle2ai/monocle/pull/69))
+- Implement Haystack metamodel support ([#68](https://github.com/monocle2ai/monocle/pull/68))
+
+## Version 0.2.0 (2024-12-05)
+
+## 0.2.0 (Oct 22, 2024)
+
+- Ndjson format for S3 and Blob exporters ([#61](https://github.com/monocle2ai/monocle/pull/61))
+- Set monocle exporter from env setting ([#60](https://github.com/monocle2ai/monocle/pull/60))
+- Update workflow name and type with new format ([#59](https://github.com/monocle2ai/monocle/pull/59))
+- Updated async and custom output processor testcase for metamodel([#58](https://github.com/monocle2ai/monocle/pull/58))
+- Build okahu exporter and added test cases for okahu exporte ([#56](https://github.com/monocle2ai/monocle/pull/56))
+- Handle exception in span wrappers([#52](https://github.com/monocle2ai/monocle/pull/52))
+- Metamodel entity changes ([#51](https://github.com/monocle2ai/monocle/pull/51)), ([#54](https://github.com/monocle2ai/monocle/pull/54))
+- Error handling for llm_endpoint and tags ([#50](https://github.com/monocle2ai/monocle/pull/50))
+- Context_output for vector store retriever ([#48](https://github.com/monocle2ai/monocle/pull/48))
+- Direct exporter - AWS S3 ([#42](https://github.com/monocle2ai/monocle/pull/42))
+- Direct Exporter - Blob store ([#41](https://github.com/monocle2ai/monocle/pull/41))
+- Initial metamodel definition ([#39](https://github.com/monocle2ai/monocle/pull/39))
+- Improvement in vectorstore traces ([#38](https://github.com/monocle2ai/monocle/pull/38))
+- Update key for session context field in attributes ([#34](https://github.com/monocle2ai/monocle/pull/34))
+
+
+## 0.1.0 (Aug 27, 2024)
+
+- Fixed LlamaIndex tracing bugs ([#32](https://github.com/monocle2ai/monocle/pull/32))
+- Added support to add AWS cloud infra attributes ([#29](https://github.com/monocle2ai/monocle/pull/29))
+- Added support to add Azure cloud infra attributes ([#23](https://github.com/monocle2ai/monocle/pull/23))
+- Added support for adding provider name in LLM span in traces ([#22](https://github.com/monocle2ai/monocle/pull/22))
+- Added a default file span exporter ([#21](https://github.com/monocle2ai/monocle/pull/21))
+- Moved input and output context and prompts from attributes to events ([#15](https://github.com/monocle2ai/monocle/pull/15))
+
+
+
+
+
+
+## 0.0.1 (Jul 17, 2024)
+
+- First monocle release

{monocle_apptrace-0.3.0b7 → monocle_apptrace-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: monocle_apptrace
-Version: 0.3.0b7
+Version: 0.3.1
 Summary: package with monocle genAI tracing
 Project-URL: Homepage, https://github.com/monocle2ai/monocle
 Project-URL: Issues, https://github.com/monocle2ai/monocle/issues
@@ -20,6 +20,7 @@ Requires-Dist: boto3==1.35.19; extra == 'aws'
 Provides-Extra: azure
 Requires-Dist: azure-storage-blob==12.22.0; extra == 'azure'
 Provides-Extra: dev
+Requires-Dist: anthropic==0.49.0; extra == 'dev'
 Requires-Dist: azure-storage-blob==12.22.0; extra == 'dev'
 Requires-Dist: boto3==1.34.131; extra == 'dev'
 Requires-Dist: chromadb==0.4.22; extra == 'dev'

{monocle_apptrace-0.3.0b7 → monocle_apptrace-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "monocle_apptrace"
-version = "0.3.0b7"
+version = "0.3.1"
 authors = []
 description = "package with monocle genAI tracing"
 readme = "README.md"
@@ -72,7 +72,8 @@ dev = [
   'flask',
   'opentelemetry-instrumentation-flask',
   'langgraph==0.2.68',
-  'opendal==0.45.14'
+  'opendal==0.45.14',
+  'anthropic==0.49.0',
 ]
 
 azure = [

{monocle_apptrace-0.3.0b7 → monocle_apptrace-0.3.1}/src/monocle_apptrace/exporters/monocle_exporters.py

@@ -18,9 +18,12 @@ monocle_exporters: Dict[str, Any] = {
 }
 
 
-def get_monocle_exporter() -> List[SpanExporter]:
+def get_monocle_exporter(exporters_list:str=None) -> List[SpanExporter]:
     # Retrieve the MONOCLE_EXPORTER environment variable and split it into a list
-    exporter_names = os.environ.get("MONOCLE_EXPORTER", "file").split(",")
+    if exporters_list:
+        exporter_names = exporters_list.split(",")
+    else:
+        exporter_names = os.environ.get("MONOCLE_EXPORTER", "file").split(",")
     exporters = []
     
     # Create task processor for AWS Lambda environment

{monocle_apptrace-0.3.0b7 → monocle_apptrace-0.3.1}/src/monocle_apptrace/instrumentation/common/__init__.py

@@ -1,2 +1,2 @@
 from .instrumentor import setup_monocle_telemetry, start_trace, stop_trace, start_scope, stop_scope, http_route_handler, monocle_trace_scope, monocle_trace_scope_method, monocle_trace
-from .utils import MonocleSpanException
+from .utils import MonocleSpanException

{monocle_apptrace-0.3.0b7 → monocle_apptrace-0.3.1}/src/monocle_apptrace/instrumentation/common/constants.py

@@ -13,6 +13,7 @@ GITHUB_CODESPACE_IDENTIFIER_ENV_NAME = "GITHUB_REPOSITORY"
 
 # Azure naming reference can be found here
 # https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations
+# https://docs.aws.amazon.com/resource-explorer/latest/userguide/supported-resource-types.html#services-lookoutmetrics
 AZURE_FUNCTION_NAME = "azure.func"
 AZURE_APP_SERVICE_NAME = "azure.asp"
 AZURE_ML_SERVICE_NAME = "azure.mlw"
@@ -48,6 +49,9 @@ llm_type_map = {
     "sagemakerllm": "aws_sagemaker",
     "chatbedrock": "aws_bedrock",
     "openaigenerator": "openai",
+    "bedrockruntime":"aws_bedrock",
+    "sagemakerruntime":"aws_sagemaker",
+    "chatanthropic":"anthropic",
 }
 
 MONOCLE_INSTRUMENTOR = "monocle_apptrace"
@@ -67,5 +71,7 @@ SCOPE_METHOD_FILE = 'monocle_scopes.json'
 SCOPE_CONFIG_PATH = 'MONOCLE_SCOPE_CONFIG_PATH'
 TRACE_PROPOGATION_URLS = "MONOCLE_TRACE_PROPAGATATION_URLS"
 WORKFLOW_TYPE_KEY = "monocle.workflow_type"
+ADD_NEW_WORKFLOW = "monocle.add_new_workflow"
 WORKFLOW_TYPE_GENERIC = "workflow.generic"
-MONOCLE_SDK_VERSION = "monocle_apptrace.version"
+MONOCLE_SDK_VERSION = "monocle_apptrace.version"
+MONOCLE_SDK_LANGUAGE = "monocle_apptrace.language"

{monocle_apptrace-0.3.0b7 → monocle_apptrace-0.3.1}/src/monocle_apptrace/instrumentation/common/instrumentor.py

@@ -3,6 +3,7 @@ import inspect
 from typing import Collection, Dict, List, Union
 import random
 import uuid
+import inspect
 from opentelemetry import trace
 from contextlib import contextmanager
 from opentelemetry.context import attach, get_value, set_value, get_current, detach
@@ -13,6 +14,7 @@ from opentelemetry.sdk.trace import TracerProvider, Span, id_generator
 from opentelemetry.sdk.resources import SERVICE_NAME, Resource
 from opentelemetry.sdk.trace import Span, TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanProcessor
+from opentelemetry.sdk.trace.export import SpanExporter
 from opentelemetry.trace import get_tracer
 from wrapt import wrap_function_wrapper
 from opentelemetry.trace.propagation import set_span_in_context, _SPAN_KEY
@@ -27,7 +29,7 @@ from monocle_apptrace.instrumentation.common.wrapper import scope_wrapper, ascop
 from monocle_apptrace.instrumentation.common.utils import (
     set_scope, remove_scope, http_route_handler, load_scopes, async_wrapper, http_async_route_handler
 )
-from monocle_apptrace.instrumentation.common.constants import MONOCLE_INSTRUMENTOR, WORKFLOW_TYPE_KEY
+from monocle_apptrace.instrumentation.common.constants import MONOCLE_INSTRUMENTOR, WORKFLOW_TYPE_GENERIC
 from functools import wraps
 logger = logging.getLogger(__name__)
 
@@ -39,19 +41,22 @@ monocle_tracer_provider: TracerProvider = None
 
 class MonocleInstrumentor(BaseInstrumentor):
     workflow_name: str = ""
-    user_wrapper_methods: list[Union[dict,WrapperMethod]] = []
+    user_wrapper_methods: list[Union[dict,WrapperMethod]] = [],
+    exporters: list[SpanExporter] = [],
     instrumented_method_list: list[object] = []
-    handlers:Dict[str,SpanHandler] = {} # dict of handlers
+    handlers:Dict[str,SpanHandler] = None # dict of handlers
     union_with_default_methods: bool = False
 
     def __init__(
             self,
             handlers,
             user_wrapper_methods: list[Union[dict,WrapperMethod]] = None,
+            exporters: list[SpanExporter] = None,
             union_with_default_methods: bool = True
             ) -> None:
         self.user_wrapper_methods = user_wrapper_methods or []
         self.handlers = handlers
+        self.exporters = exporters
         if self.handlers is not None:
             for key, val in MONOCLE_SPAN_HANDLERS.items():
                 if key not in self.handlers:
@@ -155,7 +160,8 @@ def setup_monocle_telemetry(
         span_processors: List[SpanProcessor] = None,
         span_handlers: Dict[str,SpanHandler] = None,
         wrapper_methods: List[Union[dict,WrapperMethod]] = None,
-        union_with_default_methods: bool = True) -> None:
+        union_with_default_methods: bool = True,
+        monocle_exporters_list:str = None) -> None:
     """
     Set up Monocle telemetry for the application.
 
@@ -165,7 +171,7 @@ def setup_monocle_telemetry(
         The name of the workflow to be used as the service name in telemetry.
     span_processors : List[SpanProcessor], optional
         Custom span processors to use instead of the default ones. If None, 
-        BatchSpanProcessors with Monocle exporters will be used.
+        BatchSpanProcessors with Monocle exporters will be used. This can't be combined with `monocle_exporters_list`.
     span_handlers : Dict[str, SpanHandler], optional
         Dictionary of span handlers to be used by the instrumentor, mapping handler names to handler objects.
     wrapper_methods : List[Union[dict, WrapperMethod]], optional
@@ -173,11 +179,16 @@ def setup_monocle_telemetry(
     union_with_default_methods : bool, default=True
         If True, combine the provided wrapper_methods with the default methods.
         If False, only use the provided wrapper_methods.
+    monocle_exporters_list : str, optional
+        Comma-separated list of exporters to use. This will override the env setting MONOCLE_EXPORTERS.
+        Supported exporters are: s3, blob, okahu, file, memory, console. This can't be combined with `span_processors`.
     """
     resource = Resource(attributes={
         SERVICE_NAME: workflow_name
     })
-    exporters = get_monocle_exporter()
+    if span_processors and monocle_exporters_list:
+        raise ValueError("span_processors and monocle_exporters_list can't be used together")
+    exporters:List[SpanExporter] = get_monocle_exporter(monocle_exporters_list)
     span_processors = span_processors or [BatchSpanProcessor(exporter) for exporter in exporters]
     set_tracer_provider(TracerProvider(resource=resource))
     attach(set_value("workflow_name", workflow_name))
@@ -192,7 +203,7 @@ def setup_monocle_telemetry(
             get_tracer_provider().add_span_processor(processor)
     if is_proxy_provider:
         trace.set_tracer_provider(get_tracer_provider())
-    instrumentor = MonocleInstrumentor(user_wrapper_methods=wrapper_methods or [], 
+    instrumentor = MonocleInstrumentor(user_wrapper_methods=wrapper_methods or [], exporters=exporters,
                                        handlers=span_handlers, union_with_default_methods = union_with_default_methods)
     # instrumentor.app_name = workflow_name
     if not instrumentor.is_instrumented_by_opentelemetry:
@@ -228,7 +239,7 @@ def start_trace():
         updated_span_context = set_span_in_context(span=span)
         SpanHandler.set_default_monocle_attributes(span)
         SpanHandler.set_workflow_properties(span)
-        token = SpanHandler.attach_workflow_type(context=updated_span_context)
+        token = attach(updated_span_context)
         return token
     except:
         logger.warning("Failed to start trace")
@@ -250,7 +261,7 @@ def stop_trace(token) -> None:
             if parent_span is not None:
                 parent_span.end()
         if token is not None:
-            SpanHandler.detach_workflow_type(token)
+            detach(token)
     except:
         logger.warning("Failed to stop trace")
 

{monocle_apptrace-0.3.0b7 → monocle_apptrace-0.3.1}/src/monocle_apptrace/instrumentation/common/span_handler.py

@@ -1,6 +1,6 @@
 import logging
 import os
-from importlib.metadata import version
+from contextlib import contextmanager
 from opentelemetry.context import get_value, set_value, attach, detach
 from opentelemetry.sdk.trace import Span
 from opentelemetry.trace.status import Status, StatusCode
@@ -8,9 +8,9 @@ from monocle_apptrace.instrumentation.common.constants import (
     QUERY,
     service_name_map,
     service_type_map,
-    MONOCLE_SDK_VERSION
+    MONOCLE_SDK_VERSION, MONOCLE_SDK_LANGUAGE
 )
-from monocle_apptrace.instrumentation.common.utils import set_attribute, get_scopes, MonocleSpanException
+from monocle_apptrace.instrumentation.common.utils import set_attribute, get_scopes, MonocleSpanException, get_monocle_version
 from monocle_apptrace.instrumentation.common.constants import WORKFLOW_TYPE_KEY, WORKFLOW_TYPE_GENERIC
 
 logger = logging.getLogger(__name__)
@@ -39,9 +39,9 @@ class SpanHandler:
         pass
 
     def skip_span(self, to_wrap, wrapped, instance, args, kwargs) -> bool:
-        # If this is a workflow span type and a workflow span is already generated, then skip generating this span
-        if to_wrap.get('span_type') == "workflow" and self.is_workflow_span_active():
-            return True
+        return False
+
+    def skip_processor(self, to_wrap, wrapped, instance, args, kwargs) -> bool:
         return False
 
     def pre_task_processing(self, to_wrap, wrapped, instance, args,kwargs, span):
@@ -51,11 +51,8 @@ class SpanHandler:
     @staticmethod
     def set_default_monocle_attributes(span: Span):
         """ Set default monocle attributes for all spans """
-        try:
-            sdk_version = version("monocle_apptrace")
-            span.set_attribute(MONOCLE_SDK_VERSION, sdk_version)
-        except Exception as e:
-            logger.warning("Exception finding monocle-apptrace version.")
+        span.set_attribute(MONOCLE_SDK_VERSION, get_monocle_version())
+        span.set_attribute(MONOCLE_SDK_LANGUAGE, "python")
         for scope_key, scope_value in get_scopes().items():
             span.set_attribute(f"scope.{scope_key}", scope_value)
 
@@ -64,8 +61,14 @@ class SpanHandler:
         """ Set attributes of workflow if this is a root span"""
         SpanHandler.set_workflow_attributes(to_wrap, span)
         SpanHandler.set_app_hosting_identifier_attribute(span)
+
         span.set_status(StatusCode.OK)
 
+    @staticmethod
+    def set_non_workflow_properties(span: Span, to_wrap = None):
+        workflow_name = SpanHandler.get_workflow_name(span=span)
+        if workflow_name:
+            span.set_attribute("workflow.name", workflow_name)
 
     def post_task_processing(self, to_wrap, wrapped, instance, args, kwargs, result, span:Span):
         if span.status.status_code == StatusCode.UNSET:
@@ -79,7 +82,8 @@ class SpanHandler:
         span_index = 0
         if SpanHandler.is_root_span(span):
             span_index = 2 # root span will have workflow and hosting entities pre-populated
-        if 'output_processor' in to_wrap and to_wrap["output_processor"] is not None:    
+        if not self.skip_processor(to_wrap, wrapped, instance, args, kwargs) and (
+                'output_processor' in to_wrap and to_wrap["output_processor"] is not None):
             output_processor=to_wrap['output_processor']
             if 'type' in output_processor:
                         span.set_attribute("span.type", output_processor['type'])
@@ -107,6 +111,8 @@ class SpanHandler:
                     span_index += 1
             else:
                 logger.debug("attributes not found or incorrect written in entity json")
+        else:
+            span.set_attribute("span.type", "generic")
 
         # set scopes as attributes by calling get_scopes()
         # scopes is a Mapping[str:object], iterate directly with .items()
@@ -118,7 +124,8 @@ class SpanHandler:
 
 
     def hydrate_events(self, to_wrap, wrapped, instance, args, kwargs, result, span):
-        if 'output_processor' in to_wrap and to_wrap["output_processor"] is not None:
+        if not self.skip_processor(to_wrap, wrapped, instance, args, kwargs) and (
+                'output_processor' in to_wrap and to_wrap["output_processor"] is not None):
             output_processor=to_wrap['output_processor']
             arguments = {"instance": instance, "args": args, "kwargs": kwargs, "result": result}
             if 'events' in output_processor:
@@ -147,6 +154,7 @@ class SpanHandler:
         span_index = 1
         workflow_name = SpanHandler.get_workflow_name(span=span)
         if workflow_name:
+            span.update_name("workflow")
             span.set_attribute("span.type", "workflow")
             span.set_attribute(f"entity.{span_index}.name", workflow_name)
         workflow_type = SpanHandler.get_workflow_type(to_wrap)
@@ -186,26 +194,19 @@ class SpanHandler:
     @staticmethod
     def is_root_span(curr_span: Span) -> bool:
         try:
-            if curr_span is not None and hasattr(curr_span, "parent"):
+            if curr_span is not None and hasattr(curr_span, "parent") or  curr_span.context.trace_state:
                 return curr_span.parent is None
         except Exception as e:
             logger.warning(f"Error finding root span: {e}")
 
-    def is_non_workflow_root_span(self, curr_span: Span, to_wrap) -> bool:
-        return SpanHandler.is_root_span(curr_span) and to_wrap.get("span_type") != "workflow"
-    
-    def is_workflow_span_active(self):
-        return get_value(WORKFLOW_TYPE_KEY) is not None
-
     @staticmethod
     def attach_workflow_type(to_wrap=None, context=None): 
         token = None
         if to_wrap:
-            if to_wrap.get('span_type') == "workflow":
+            workflow_type = SpanHandler.get_workflow_type(to_wrap)
+            if workflow_type != WORKFLOW_TYPE_GENERIC:
                 token = attach(set_value(WORKFLOW_TYPE_KEY,
                                         SpanHandler.get_workflow_type(to_wrap), context))
-        else:
-            token = attach(set_value(WORKFLOW_TYPE_KEY, WORKFLOW_TYPE_GENERIC, context))
         return token
 
     @staticmethod
@@ -213,8 +214,18 @@ class SpanHandler:
         if token:
             return detach(token)
 
+    @staticmethod
+    @contextmanager
+    def workflow_type(to_wrap=None):
+        token = SpanHandler.attach_workflow_type(to_wrap)
+        try:
+            yield
+        finally:
+            SpanHandler.detach_workflow_type(token)
+
+
 class NonFrameworkSpanHandler(SpanHandler):
 
-    # If the language framework is being executed, then skip generating direct openAI spans
-    def skip_span(self, to_wrap, wrapped, instance, args, kwargs) -> bool:
+    # If the language framework is being executed, then skip generating direct openAI attributes and events
+    def skip_processor(self, to_wrap, wrapped, instance, args, kwargs) -> bool:
         return get_value(WORKFLOW_TYPE_KEY) in WORKFLOW_TYPE_MAP.values()

monocle_apptrace-0.3.1/src/monocle_apptrace/instrumentation/common/tracing.md

@@ -0,0 +1,68 @@
+# Monocle tracing: concepts and principles
+
+## Span
+Span is an observation of a code/method executed. Each span has a unique ID. It records the start time and end time of the code's execution along with additional information relevant to that operation. Before the code execution starts, a span object is created in the memory of the host process executing this code. It'll capture the current time as start of time of span. At this stage the span is considered active. It'll stay active till the code execution ends. Once the code execution is complete, it'll record the current time as end time, capture any additional relevant information (eg argument, return value, environment setttings etc.). Now the span is marked as closed and it will be queued to be saved to some configured storage. 
+Note that the code that generated this span could in turn call other methods that are also instrumented. Those will generate spans of their own. These will be "child" spans which will refer to the span ID of the calling code as "parent" span. An initial span which has no parent is referred as "root" span.
+
+## Trace
+A trace is a collection of spans with a common ID called traceID. When the first active span gets created, a new unique traceID is generated and assigned to that span. All the child spans generated by execution of other instrumented code/methods will share the same traceID. Once this top span ends, this trace ends. This way all the code executed as part of the top level instrumented code will have a common traceID to group them together. For example, consider following sequence where `f1()` is the first instrumented method is executed, it calls other instrumented methods `f2(),f3(),f4() and f5()`
+```
+f1()--> f2() --> f3()
+    --> f4() --> f5()
+```
+In the above sequence, all method execution will generate a span each and they all will have a common traceID. Now if a new instrumented methods is executed after f1() finishes, it will be the first active span in the process's execution context and a will get a new traceID.
+
+### Trace ID propogation
+Each child span inherits the parent's trace ID. When spans running in same process, it captures it from process memory/context etc. But consider the above example again, where the `f4()-->f5()` code is not part of the process that executing f1(). It's a remote call, say over REST. From the overall application's point of view, the work done if `f4()` and `f5()` is part of `f1()` and you want same traceID associated with all spans. You want the instrumentation to seamlessly pass the tracedID over such remote calls and continue that instead of generating a new one. It's the responsibility of Monocle to provide such mechanism to make thsi trace ID propogation transparent to the application logic and architecture.
+
+## Propogation
+When the execution logic spans mulitple processes using remote calling mechanisms like REST, you want the trace ID also to propogate from process that originated it to the one that's continueing the remote execution. Monocle supports seamlessly propogating traceID over REST if both the sides for the trace execution are instrumented.
+
+## Types of spans in Monocle
+Monocle extends these generic span types by enriching additional attributes/data for genAI specific operations.
+### GenAI spans
+There are the core spans that capture details of genAI component operations like call to an LLM or vectore store. The purpose of these spans is to capture the details the applications interaction with core genAI comoponents. These spans are triggered by pre-instrumented methods that handle such operations. 
+- Inference span
+Represents interaction with LLMs, captures details like model, prompts, response and other metadata (eg tokens)
+- Retrieval span
+Represents interactions with vector stores like embedding creating, vector retrieval etc. Captures the model, search query, response, vector embedding etc.
+
+### anchor spans
+These are the spans that are created by a top level method that anchors a higher level of abstraction for underlying core genAI APIs. For example a langchain.invoke() which under the cover calls langchain.llm_invoke() or langchain.vector_retrieval(). Consider following psuedo code of a langchain rag pattern API,
+```
+response = rag_chain.invoke(prompt)
+            --> cleaned_prompt = llm1.chat(prompt)
+            --> context = vector_store.retrieve(cleaned_prompt)
+            --> response = llm2.chat(system_prompt+context+cleaned_prompt)
+            --> return response
+```
+If we only instrument the top level invoke call, then we'll trace the top level prompt and response interaction between application and langchain. But we'll miss the details like how a system prompt was added and send to mulitple LLMs and what context was extracted from a vector store etc. On the other hand, if we only instrument the low level calls to LLM and vector, then we'll miss the fact that those are part of same RAG. Hence we instrument all of them. This exaple would genearte an anchor spna for `invoke()` method, a retrieval span for `retrieve()` method and two inference spans for each `chat()` method. All of these will have common traceID.
+The anchor spans also provides an observation window of your application interaction with an high level SDK or service. It will illustrate facts such as how much time take by the genAI service invocation compared to other local logic.
+
+### Workflow spans
+Workflow spans are synthetic spans that are created to trace the full trace. It captures the summary of the full trace including the time window, the process running this code (set as `workflow_name` in the API to enab le Monocle instrumentation) and runtime environment details such as hosting service (Azure function, Lambda function etc). 
+The workflow spans is generated when a new trace starts or when a trace is propogated. They provide the base line observation window for the entire trace or a fragment of trace executed in a process.
+Consider following example,
+```
+setup_monocle_telemetry(workflow='bot')
+rag_chain.invoke()
+                --> context = retrieval() 
+                --> new_prompt = REST --> azure.func.chat(prompt) --> 
+                                                                setup_monocle_telemetry(workflow='moderator')
+                                                                return llm(moderator_system_prompt+prompt)
+                --> response = llm(new_prompt)
+```
+This will generate following spans:
+```
+Span{name='workflow.bot', type= workflow, traceID = xx1, spanID = yy0, parentID=None} ==> Workflow for new trace start
+Span{name='chain.invoke', type=anchor, traceID = xx1, spanID = yy1, parentID=yy0} ==> anchor span for chain invoke
+Span{name='chain.retrieval', type=retrieval, traceID = xx1, spanID = yy2, parentID = yy1} ==> Retrieval API span
+Span{name='workflow.moderator', type=workflow, traceID = xx1, spanID = zz1, parentID=yy1} ==> Workflow for propogated trace fragement
+Span{name='az.func.chat', type=anchor, traceID = xx1, spanID = zz2, parentID=zz1} ==> anchor span for az function invoke
+Span{name='chain.infer', type=inference, traceID = xx1, spanID = zz2, parentID=zz2} ==> inference
+Span{name='chain.infer',type=inference, traceID = xx1, spanID = yy3, parentID=yy1} ==> inference
+```
+
+## Scopes
+Scope is an way of grouping across traces. It's a tag with a value that can either be specified or auto generated (GUID) by Monocle. There can be any number of scopes active in an application code at a given point in time. All the active scopes are recorded in every span that's emmitted.
+

{monocle_apptrace-0.3.0b7 → monocle_apptrace-0.3.1}/src/monocle_apptrace/instrumentation/common/utils.py

@@ -9,7 +9,8 @@ from opentelemetry.trace.propagation import _SPAN_KEY
 from opentelemetry.sdk.trace import id_generator, TracerProvider
 from opentelemetry.propagate import inject, extract
 from opentelemetry import baggage
-from monocle_apptrace.instrumentation.common.constants import MONOCLE_SCOPE_NAME_PREFIX, SCOPE_METHOD_FILE, SCOPE_CONFIG_PATH, llm_type_map
+from monocle_apptrace.instrumentation.common.constants import MONOCLE_SCOPE_NAME_PREFIX, SCOPE_METHOD_FILE, SCOPE_CONFIG_PATH, llm_type_map, MONOCLE_SDK_VERSION, ADD_NEW_WORKFLOW
+from importlib.metadata import version
 
 T = TypeVar('T')
 U = TypeVar('U')
@@ -21,6 +22,12 @@ embedding_model_context = {}
 scope_id_generator = id_generator.RandomIdGenerator()
 http_scopes:dict[str:str] = {}
 
+try:
+    monocle_sdk_version = version("monocle_apptrace")
+except Exception as e:
+    monocle_sdk_version = "unknown"
+    logger.warning("Exception finding monocle-apptrace version.")
+
 class MonocleSpanException(Exception):
     def __init__(self, err_message:str):
         """
@@ -96,8 +103,8 @@ def with_tracer_wrapper(func):
 def resolve_from_alias(my_map, alias):
     """Find a alias that is not none from list of aliases"""
 
-    for i in alias and my_map[i] is not None:
-        if i in my_map.keys():
+    for i in alias:
+        if i in my_map.keys() and my_map[i] is not None:
             return my_map[i]
     return None
 
@@ -236,6 +243,7 @@ def set_scopes_from_baggage(baggage_context:Context):
 def extract_http_headers(headers) -> object:
     global http_scopes
     trace_context:Context = extract(headers, context=get_current())
+    trace_context = set_value(ADD_NEW_WORKFLOW, True, trace_context)
     imported_scope:dict[str, object] = {}
     for http_header, http_scope in http_scopes.items():
         if http_header in headers:
@@ -311,6 +319,19 @@ def async_wrapper(method, scope_name=None, scope_value=None, headers=None, *args
         if token:
             remove_scope(token)
 
+def get_monocle_version() -> str:
+    global monocle_sdk_version
+    return monocle_sdk_version
+
+def add_monocle_trace_state(headers:dict[str:str]) -> None:
+    if headers is None:
+        return
+    monocle_trace_state = f"{MONOCLE_SDK_VERSION}={get_monocle_version()}"
+    if 'tracestate' in headers:
+        headers['tracestate'] = f"{headers['tracestate']},{monocle_trace_state}"
+    else:
+        headers['tracestate'] = monocle_trace_state
+
 class Option(Generic[T]):
     def __init__(self, value: Optional[T]):
         self.value = value
@@ -343,14 +364,8 @@ def try_option(func: Callable[..., T], *args, **kwargs) -> Option[T]:
 
 def get_llm_type(instance):
     try:
+        t_name = type(instance).__name__.lower()
         llm_type = llm_type_map.get(type(instance).__name__.lower())
         return llm_type
     except:
         pass
-
-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