microsoft-agents-a365-observability-extensions-langchain 0.1.0__py3-none-any.whl

microsoft_agents_a365/observability/extensions/langchain/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Wraps the Langchain Agents SDK tracer to integrate with our Telemetry Solution.
+"""
+
+from .tracer_instrumentor import CustomLangChainInstrumentor
+
+__all__ = ["CustomLangChainInstrumentor"]
+
+# This is a namespace package
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

microsoft_agents_a365/observability/extensions/langchain/tracer.py

@@ -0,0 +1,222 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+import re
+from collections.abc import Iterator
+from itertools import chain
+from threading import RLock
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    cast,
+)
+from uuid import UUID
+
+from langchain_core.tracers import BaseTracer, LangChainTracer
+from langchain_core.tracers.schemas import Run
+from microsoft_agents_a365.observability.core.inference_operation_type import InferenceOperationType
+from microsoft_agents_a365.observability.core.utils import (
+    DictWithLock,
+    as_utc_nano,
+    flatten,
+    record_exception,
+)
+from opentelemetry import context as context_api
+from opentelemetry import trace as trace_api
+from opentelemetry.context import (
+    _SUPPRESS_INSTRUMENTATION_KEY,
+    get_value,
+)
+from opentelemetry.trace import Span
+from opentelemetry.util.types import AttributeValue
+
+from microsoft_agents_a365.observability.extensions.langchain.utils import (
+    IGNORED_EXCEPTION_PATTERNS,
+    add_operation_type,
+    function_calls,
+    input_messages,
+    invocation_parameters,
+    llm_provider,
+    metadata,
+    model_name,
+    output_messages,
+    prompts,
+    token_counts,
+    tools,
+)
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+CONTEXT_ATTRIBUTES = (
+    "session.id",
+    "user.id",
+    "metadata",
+    "tag.tags",
+    "llm.prompt_template.template",
+    "llm.prompt_template.variables",
+    "llm.prompt_template.version",
+)
+
+
+class CustomLangChainTracer(BaseTracer):
+    __slots__ = (
+        "_tracer",
+        "_separate_trace_from_runtime_context",
+        "_spans_by_run",
+    )
+
+    def __init__(
+        self,
+        tracer: trace_api.Tracer,
+        separate_trace_from_runtime_context: bool,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the OpenInferenceTracer.
+
+        Args:
+            tracer (trace_api.Tracer): The OpenTelemetry tracer for creating spans.
+            separate_trace_from_runtime_context (bool): When True, always start a new trace for each
+                span without a parent, isolating it from any existing trace in the runtime context.
+            *args (Any): Positional arguments for BaseTracer.
+            **kwargs (Any): Keyword arguments for BaseTracer.
+        """
+        super().__init__(*args, **kwargs)
+        if TYPE_CHECKING:
+            # check that `run_map` still exists in parent class
+            assert self.run_map
+        self.run_map = DictWithLock[str, Run](self.run_map)
+        self._tracer = tracer
+        self._separate_trace_from_runtime_context = separate_trace_from_runtime_context
+        self._spans_by_run: dict[UUID, Span] = DictWithLock[UUID, Span]()
+        self._lock = RLock()  # handlers may be run in a thread by langchain
+
+    def get_span(self, run_id: UUID) -> Span | None:
+        return self._spans_by_run.get(run_id)
+
+    def _start_trace(self, run: Run) -> None:
+        self.run_map[str(run.id)] = run
+        if context_api.get_value(_SUPPRESS_INSTRUMENTATION_KEY):
+            return
+        with self._lock:
+            parent_context = (
+                trace_api.set_span_in_context(parent)
+                if (parent_run_id := run.parent_run_id)
+                and (parent := self._spans_by_run.get(parent_run_id))
+                else (context_api.Context() if self._separate_trace_from_runtime_context else None)
+            )
+        # We can't use real time because the handler may be
+        # called in a background thread.
+        start_time_utc_nano = as_utc_nano(run.start_time)
+        span = self._tracer.start_span(
+            name=run.name,
+            context=parent_context,
+            start_time=start_time_utc_nano,
+        )
+
+        # The following line of code is commented out to serve as a reminder that in a system
+        # of callbacks, attaching the context can be hazardous because there is no guarantee
+        # that the context will be detached. An error could happen between callbacks leaving
+        # the context attached forever, and all future spans will use it as parent. What's
+        # worse is that the error could have also prevented the span from being exported,
+        # leaving all future spans as orphans. That is a very bad scenario.
+        # token = context_api.attach(context)
+        with self._lock:
+            self._spans_by_run[run.id] = span
+
+    def _end_trace(self, run: Run) -> None:
+        self.run_map.pop(str(run.id), None)
+        if context_api.get_value(_SUPPRESS_INSTRUMENTATION_KEY):
+            return
+        span = self._spans_by_run.pop(run.id, None)
+        if span:
+            try:
+                _update_span(span, run)
+            except Exception:
+                logger.exception("Failed to update span with run data.")
+            # We can't use real time because the handler may be
+            # called in a background thread.
+            end_time_utc_nano = as_utc_nano(run.end_time) if run.end_time else None
+            span.end(end_time=end_time_utc_nano)
+
+    def _persist_run(self, run: Run) -> None:
+        pass
+
+    def on_llm_error(self, error: BaseException, *args: Any, run_id: UUID, **kwargs: Any) -> Run:
+        if span := self._spans_by_run.get(run_id):
+            record_exception(span, error)
+        return super().on_llm_error(error, *args, run_id=run_id, **kwargs)
+
+    def on_chain_error(self, error: BaseException, *args: Any, run_id: UUID, **kwargs: Any) -> Run:
+        if span := self._spans_by_run.get(run_id):
+            record_exception(span, error)
+        return super().on_chain_error(error, *args, run_id=run_id, **kwargs)
+
+    def on_retriever_error(
+        self, error: BaseException, *args: Any, run_id: UUID, **kwargs: Any
+    ) -> Run:
+        if span := self._spans_by_run.get(run_id):
+            record_exception(span, error)
+        return super().on_retriever_error(error, *args, run_id=run_id, **kwargs)
+
+    def on_tool_error(self, error: BaseException, *args: Any, run_id: UUID, **kwargs: Any) -> Run:
+        if span := self._spans_by_run.get(run_id):
+            record_exception(span, error)
+        return super().on_tool_error(error, *args, run_id=run_id, **kwargs)
+
+    def on_chat_model_start(self, *args: Any, **kwargs: Any) -> Run:
+        """
+        This emulates the behavior of the LangChainTracer.
+        https://github.com/langchain-ai/langchain/blob/c01467b1f4f9beae8f1edb105b17aa4f36bf6573/libs/core/langchain_core/tracers/langchain.py#L115
+
+        Although this method exists on the parent class, i.e. `BaseTracer`,
+        it requires setting `self._schema_format = "original+chat"`.
+        https://github.com/langchain-ai/langchain/blob/c01467b1f4f9beae8f1edb105b17aa4f36bf6573/libs/core/langchain_core/tracers/base.py#L170
+
+        But currently self._schema_format is marked for internal use.
+        https://github.com/langchain-ai/langchain/blob/c01467b1f4f9beae8f1edb105b17aa4f36bf6573/libs/core/langchain_core/tracers/base.py#L60
+        """  # noqa: E501
+        return LangChainTracer.on_chat_model_start(self, *args, **kwargs)  # type: ignore
+
+
+def get_attributes_from_context() -> Iterator[tuple[str, AttributeValue]]:
+    for ctx_attr in CONTEXT_ATTRIBUTES:
+        if (val := get_value(ctx_attr)) is not None:
+            yield ctx_attr, cast(AttributeValue, val)
+
+
+def _update_span(span: Span, run: Run) -> None:
+    # If there  is no error or if there is an agent control exception, set the span to OK
+    if run.error is None or any(
+        re.match(pattern, run.error) for pattern in IGNORED_EXCEPTION_PATTERNS
+    ):
+        span.set_status(trace_api.StatusCode.OK)
+    else:
+        span.set_status(trace_api.Status(trace_api.StatusCode.ERROR, run.error))
+
+    if run.run_type == "llm" and run.outputs.get("llm_output").get("id").startswith("chat"):
+        span.update_name(f"{InferenceOperationType.CHAT.value.lower()} {span.name}")
+    elif run.run_type.lower() == "tool":
+        span.update_name(f"execute_tool {span.name}")
+    span.set_attributes(dict(get_attributes_from_context()))
+    span.set_attributes(
+        dict(
+            flatten(
+                chain(
+                    add_operation_type(run),
+                    prompts(run.inputs),
+                    input_messages(run.inputs),
+                    output_messages(run.outputs),
+                    invocation_parameters(run),
+                    llm_provider(run.extra),
+                    model_name(run.outputs, run.extra),
+                    token_counts(run.outputs),
+                    function_calls(run.outputs),
+                    tools(run),
+                    metadata(run),
+                )
+            )
+        )
+    )

microsoft_agents_a365/observability/extensions/langchain/tracer_instrumentor.py

@@ -0,0 +1,170 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+from collections.abc import Callable, Collection
+from typing import Any
+from uuid import UUID
+
+import langchain_core
+import opentelemetry.trace as optel_trace
+from langchain_core.callbacks import BaseCallbackManager
+from microsoft_agents_a365.observability.core.config import (
+    get_tracer,
+    get_tracer_provider,
+    is_configured,
+)
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from opentelemetry.trace import Span
+from wrapt import wrap_function_wrapper
+
+from microsoft_agents_a365.observability.extensions.langchain.tracer import CustomLangChainTracer
+
+_INSTRUMENTS: str = "langchain_core >= 0.1.0"
+
+
+class CustomLangChainInstrumentor(BaseInstrumentor):
+    """
+    Minimal instrumentor that attaches a TraceForLangChain to every new
+    LangChain BaseCallbackManager so runs produce OpenTelemetry spans.
+    """
+
+    def __init__(self) -> None:
+        if not is_configured():
+            raise RuntimeError(
+                "Tracing SDK is not configured. Configure it before using this instrumentor."
+            )
+        super().__init__()
+        self._tracer: CustomLangChainTracer | None = None
+        self._original_cb_init: Callable[..., None] | None = None
+        self.instrument()
+
+    # ---- BaseInstrumentor API -------------------------------------------------
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return (_INSTRUMENTS,)
+
+    def _instrument(self, **kwargs: Any) -> None:
+        tracer_name: str | None = kwargs.get("tracer_name")
+        tracer_version: str | None = kwargs.get("tracer_version")
+
+        # Prefer the Agent 365 tracer; fall back to OpenTelemetry’s default if needed.
+        try:
+            tracer = get_tracer(tracer_name, tracer_version)
+        except Exception:
+            tracer = optel_trace.get_tracer(tracer_name, tracer_version)
+
+        # Ensure tracer provider exists (ignore returned value; side-effect is enough).
+        try:
+            get_tracer_provider()
+        except Exception:
+            optel_trace.get_tracer_provider()
+
+        self._tracer = CustomLangChainTracer(
+            tracer,
+            bool(kwargs.get("separate_trace_from_runtime_context")),
+        )
+
+        # Save and wrap BaseCallbackManager.__init__ to attach the processor once per instance.
+        self._original_cb_init = langchain_core.callbacks.BaseCallbackManager.__init__
+        wrap_function_wrapper(
+            module="langchain_core.callbacks",
+            name="BaseCallbackManager.__init__",
+            wrapper=_BaseCallbackManagerInit(self._tracer),
+        )
+
+    def _uninstrument(self, **kwargs: Any) -> None:
+        # Restore original constructor if we wrapped it.
+        if self._original_cb_init is not None:
+            langchain_core.callbacks.BaseCallbackManager.__init__ = self._original_cb_init  # type: ignore[assignment]
+        self._original_cb_init = None
+        self._tracer = None
+
+    # ---- Helpers used by module-level functions -------------------------------
+
+    def get_span(self, run_id: UUID) -> Span | None:
+        """Return the span for a specific LangChain run_id, if available."""
+        if not self._tracer:
+            print("Missing tracer; call InstrumentorForLangChain().instrument() first.")
+            return None
+        # TraceForLangChain is expected to expose get_span(run_id).
+        get_span_fn = getattr(self._tracer, "get_span", None)
+        return get_span_fn(run_id) if callable(get_span_fn) else None
+
+    def get_ancestors(self, run_id: UUID) -> list[Span]:
+        """Return ancestor spans from the run’s parent up to the root (nearest first)."""
+        if not self._tracer:
+            print("Missing tracer; call InstrumentorForLangChain().instrument() first.")
+            return []
+
+        # Expect the processor to keep a run_map with parent linkage (string keys).
+        run_map = getattr(self._tracer, "run_map", {}) or {}
+        ancestors: list[Span] = []
+
+        run = run_map.get(str(run_id))
+        if not run:
+            return ancestors
+
+        ancestor_id = getattr(run, "parent_run_id", None)
+        while ancestor_id:
+            span = self.get_span(ancestor_id)
+            if span:
+                ancestors.append(span)
+            run = run_map.get(str(ancestor_id))
+            ancestor_id = getattr(run, "parent_run_id", None) if run else None
+
+        return ancestors
+
+
+class _BaseCallbackManagerInit:
+    """Post-constructor hook that adds the TraceProcessor once (inheritable)."""
+
+    __slots__ = ("_processor",)
+
+    def __init__(self, processor: CustomLangChainTracer):
+        self._processor = processor
+
+    def __call__(
+        self,
+        wrapped: Callable[..., None],
+        instance: BaseCallbackManager,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+    ) -> None:
+        wrapped(*args, **kwargs)  # run original __init__
+        # Avoid duplicates: only add if a handler of the same type isn’t present.
+        if not any(isinstance(h, type(self._processor)) for h in instance.inheritable_handlers):
+            instance.add_handler(self._processor, inherit=True)
+
+
+# ------------------------------ Convenience APIs ------------------------------
+
+
+def _current_parent_run_id() -> UUID | None:
+    """Best-effort: fetch current parent run_id from langchain runtime context."""
+    config = langchain_core.runnables.config.var_child_runnable_config.get()
+    if not isinstance(config, dict):
+        return None
+    for v in config.values():
+        if isinstance(v, langchain_core.callbacks.BaseCallbackManager):
+            if v.parent_run_id:
+                return v.parent_run_id
+    return None
+
+
+def get_current_span() -> Span | None:
+    """Return the current context’s parent span, if any."""
+    run_id = _current_parent_run_id()
+    if not run_id:
+        return None
+    return CustomLangChainInstrumentor().get_span(run_id)
+
+
+def get_ancestor_spans() -> list[Span]:
+    """
+    Return ancestor spans for the current context (immediate parent → root).
+    """
+    run_id = _current_parent_run_id()
+    if not run_id:
+        return []
+    return CustomLangChainInstrumentor().get_ancestors(run_id)

microsoft_agents_a365/observability/extensions/langchain/utils.py

@@ -0,0 +1,516 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import json
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from copy import deepcopy
+from typing import Any
+
+from langchain_core.messages import BaseMessage
+from langchain_core.tracers.schemas import Run
+from microsoft_agents_a365.observability.core.constants import (
+    GEN_AI_INPUT_MESSAGES_KEY,
+    GEN_AI_OPERATION_NAME_KEY,
+    GEN_AI_OUTPUT_MESSAGES_KEY,
+    GEN_AI_PROVIDER_NAME_KEY,
+    GEN_AI_REQUEST_MODEL_KEY,
+    GEN_AI_RESPONSE_FINISH_REASONS_KEY,
+    GEN_AI_RESPONSE_ID_KEY,
+    GEN_AI_SYSTEM_INSTRUCTIONS_KEY,
+    GEN_AI_TOOL_ARGS_KEY,
+    GEN_AI_TOOL_CALL_ID_KEY,
+    GEN_AI_TOOL_CALL_RESULT_KEY,
+    GEN_AI_TOOL_DESCRIPTION_KEY,
+    GEN_AI_TOOL_NAME_KEY,
+    GEN_AI_TOOL_TYPE_KEY,
+    GEN_AI_USAGE_INPUT_TOKENS_KEY,
+    GEN_AI_USAGE_OUTPUT_TOKENS_KEY,
+    SESSION_ID_KEY,
+)
+from microsoft_agents_a365.observability.core.inference_operation_type import InferenceOperationType
+from microsoft_agents_a365.observability.core.utils import (
+    get_first_value,
+    safe_json_dumps,
+    stop_on_exception,
+)
+
+IGNORED_EXCEPTION_PATTERNS = [
+    r"^Command\(",
+    r"^ParentCommand\(",
+]
+
+LANGCHAIN_SESSION_ID = "session_id"
+LANGCHAIN_CONVERSATION_ID = "conversation_id"
+LANGCHAIN_THREAD_ID = "thread_id"
+
+
+@stop_on_exception
+def prompts(inputs: Mapping[str, Any] | None) -> Iterator[tuple[str, list[str]]]:
+    """Yields prompts if present."""
+    if not inputs:
+        return
+    assert hasattr(inputs, "get"), f"expected Mapping, found {type(inputs)}"
+    if prompts := inputs.get("prompts"):
+        yield GEN_AI_SYSTEM_INSTRUCTIONS_KEY, prompts
+
+
+@stop_on_exception
+def _extract_message_kwargs(message_data: Mapping[str, Any] | None) -> Iterator[[str, Any]]:
+    if not message_data:
+        return
+    assert hasattr(message_data, "get"), f"expected Mapping, found {type(message_data)}"
+    if kwargs := message_data.get("kwargs"):
+        assert hasattr(kwargs, "get"), f"expected Mapping, found {type(kwargs)}"
+        if content := kwargs.get("content"):
+            # Just yield as-is (string or list)
+            yield "message.content", content
+        if tool_call_id := kwargs.get("tool_call_id"):
+            assert isinstance(tool_call_id, str), f"expected str, found {type(tool_call_id)}"
+            yield GEN_AI_TOOL_CALL_ID_KEY, tool_call_id
+        if name := kwargs.get("name"):
+            assert isinstance(name, str), f"expected str, found {type(name)}"
+            yield "message.name", name
+
+
+@stop_on_exception
+def _extract_message_additional_kwargs(
+    message_data: Mapping[str, Any] | None,
+) -> Iterator[tuple[str, Any]]:
+    if not message_data:
+        return
+    assert hasattr(message_data, "get"), f"expected Mapping, found {type(message_data)}"
+    if kwargs := message_data.get("kwargs"):
+        assert hasattr(kwargs, "get"), f"expected Mapping, found {type(kwargs)}"
+        if additional_kwargs := kwargs.get("additional_kwargs"):
+            assert hasattr(additional_kwargs, "get"), (
+                f"expected Mapping, found {type(additional_kwargs)}"
+            )
+            if function_call := additional_kwargs.get("function_call"):
+                assert hasattr(function_call, "get"), (
+                    f"expected Mapping, found {type(function_call)}"
+                )
+                if name := function_call.get("name"):
+                    assert isinstance(name, str), f"expected str, found {type(name)}"
+                    yield GEN_AI_TOOL_NAME_KEY, name
+                if arguments := function_call.get("arguments"):
+                    if isinstance(arguments, str):
+                        yield GEN_AI_TOOL_ARGS_KEY, arguments
+                    else:
+                        yield GEN_AI_TOOL_ARGS_KEY, safe_json_dumps(arguments)
+
+
+@stop_on_exception
+def _get_tool_call(tool_call: Mapping[str, Any] | None) -> Iterator[tuple[str, Any]]:
+    if not tool_call:
+        return
+    assert hasattr(tool_call, "get"), f"expected Mapping, found {type(tool_call)}"
+
+    # id
+    id_ = tool_call.get("id")
+    if id_ is not None:
+        yield GEN_AI_TOOL_CALL_ID_KEY, id_
+
+    fn = tool_call.get("function")
+    name = None
+    arguments = None
+
+    if hasattr(fn, "get"):
+        name = fn.get("name")
+        arguments = fn.get("arguments")
+    else:
+        name = tool_call.get("name")
+        arguments = tool_call.get("args")
+
+    # name
+    if name is not None:
+        assert isinstance(name, str), f"expected str, found {type(name)}"
+        yield GEN_AI_TOOL_NAME_KEY, name
+
+    # arguments -> always emit a JSON string
+    if arguments is not None:
+        if isinstance(arguments, str):
+            args_json = arguments
+        else:
+            args_json = safe_json_dumps(arguments)
+        yield GEN_AI_TOOL_ARGS_KEY, args_json
+
+
+def _process_tool_calls(tool_calls: Any) -> str:
+    """Return all tool calls as a single compact string (JSON-joined), or '' if none."""
+    if not tool_calls:
+        return ""
+    assert isinstance(tool_calls, Iterable), f"expected Iterable, found {type(tool_calls)}"
+
+    parts: list[str] = []
+    for tool_call in tool_calls:
+        data = dict(_get_tool_call(tool_call))
+        if data:
+            # Compact, stable representation
+            parts.append(safe_json_dumps(data, separators=(",", ":"), sort_keys=True))
+
+    return "; ".join(parts)
+
+
+@stop_on_exception
+def _extract_message_tool_calls(
+    message_data: Mapping[str, Any] | None,
+) -> Iterator[tuple[str, str]]:
+    if not message_data:
+        return
+    assert hasattr(message_data, "get"), f"expected Mapping, found {type(message_data)}"
+
+    # Collect tool_calls from multiple possible locations
+    all_tool_calls: list[str] = []
+
+    def collect(calls: Any) -> None:
+        if calls:
+            processed = _process_tool_calls(calls)
+            if processed:
+                if isinstance(processed, list):
+                    all_tool_calls.extend(map(str, processed))
+                else:
+                    all_tool_calls.append(str(processed))
+
+    collect(message_data.get("tool_calls"))
+
+    if kwargs := message_data.get("kwargs"):
+        assert hasattr(kwargs, "get"), f"expected Mapping, found {type(kwargs)}"
+        collect(kwargs.get("tool_calls"))
+
+        if additional_kwargs := kwargs.get("additional_kwargs"):
+            assert hasattr(additional_kwargs, "get"), (
+                f"expected Mapping, found {type(additional_kwargs)}"
+            )
+            collect(additional_kwargs.get("tool_calls"))
+
+    if all_tool_calls:
+        # Return all as a single string (comma-separated)
+        yield "message.tool_calls", ", ".join(all_tool_calls)
+
+
+@stop_on_exception
+def _parse_message_data(message_data: Mapping[str, Any] | None) -> Iterator[tuple[str, Any]]:
+    """Parses message data to grab message role, content, etc."""
+    yield from _extract_message_kwargs(message_data)
+    yield from _extract_message_additional_kwargs(message_data)
+    yield from _extract_message_tool_calls(message_data)
+
+
+@stop_on_exception
+def input_messages(
+    inputs: Mapping[str, Any] | None,
+) -> Iterator[tuple[str, list[dict[str, Any]]]]:
+    """Yields chat messages if present."""
+    if not inputs:
+        return
+    assert hasattr(inputs, "get"), f"expected Mapping, found {type(inputs)}"
+    # There may be more than one set of messages. We'll use just the first set.
+    if not (multiple_messages := inputs.get("messages")):
+        return
+    assert isinstance(multiple_messages, Iterable), (
+        f"expected Iterable, found {type(multiple_messages)}"
+    )
+    # This will only get the first set of messages.
+    if not (first_messages := next(iter(multiple_messages), None)):
+        return
+    parsed_messages = []
+    if isinstance(first_messages, list):
+        for message_data in first_messages:
+            if isinstance(message_data, BaseMessage):
+                parsed_messages.append(dict(_parse_message_data(message_data.to_json())))
+            elif hasattr(message_data, "get"):
+                parsed_messages.append(dict(_parse_message_data(message_data)))
+            else:
+                raise ValueError(f"failed to parse message of type {type(message_data)}")
+    elif isinstance(first_messages, BaseMessage):
+        parsed_messages.append(dict(_parse_message_data(first_messages.to_json())))
+    elif hasattr(first_messages, "get"):
+        parsed_messages.append(dict(_parse_message_data(first_messages)))
+    elif isinstance(first_messages, Sequence) and len(first_messages) == 2:
+        # See e.g. https://github.com/langchain-ai/langchain/blob/18cf457eec106d99e0098b42712299f5d0daa798/libs/core/langchain_core/messages/utils.py#L317  # noqa: E501
+        role, content = first_messages
+        parsed_messages.append({"MESSAGE_ROLE": role, "MESSAGE_CONTENT": content})
+    else:
+        raise ValueError(f"failed to parse messages of type {type(first_messages)}")
+    if parsed_messages:
+        yield GEN_AI_INPUT_MESSAGES_KEY, parsed_messages
+
+
+@stop_on_exception
+def metadata(run: Run) -> Iterator[tuple[str, str]]:
+    """
+    Takes the LangChain chain metadata and adds it to the trace
+    """
+    if not run.extra or not (metadata := run.extra.get("metadata")):
+        return
+    assert isinstance(metadata, Mapping), f"expected Mapping, found {type(metadata)}"
+    if session_id := (
+        metadata.get(LANGCHAIN_SESSION_ID)
+        or metadata.get(LANGCHAIN_CONVERSATION_ID)
+        or metadata.get(LANGCHAIN_THREAD_ID)
+    ):
+        yield SESSION_ID_KEY, session_id
+
+
+@stop_on_exception
+def output_messages(
+    outputs: Mapping[str, Any] | None,
+) -> Iterator[tuple[str, list[dict[str, Any]]]]:
+    """Yields chat messages if present."""
+    if not outputs:
+        return
+    assert hasattr(outputs, "get"), f"expected Mapping, found {type(outputs)}"
+    output_type = outputs.get("type")
+    if output_type and output_type.lower() == "llmresult":
+        llm_output = outputs.get("llm_output")
+        if llm_output and hasattr(llm_output, "get"):
+            response_id = llm_output.get("id")
+            if response_id:
+                yield GEN_AI_RESPONSE_ID_KEY, response_id
+    # There may be more than one set of generations. We'll use just the first set.
+    if not (multiple_generations := outputs.get("generations")):
+        return
+    assert isinstance(multiple_generations, Iterable), (
+        f"expected Iterable, found {type(multiple_generations)}"
+    )
+    # This will only get the first set of generations.
+    if not (first_generations := next(iter(multiple_generations), None)):
+        return
+    assert isinstance(first_generations, Iterable), (
+        f"expected Iterable, found {type(first_generations)}"
+    )
+    parsed_messages = []
+    for generation in first_generations:
+        assert hasattr(generation, "get"), f"expected Mapping, found {type(generation)}"
+        if message_data := generation.get("message"):
+            if isinstance(message_data, BaseMessage):
+                parsed_messages.append(dict(_parse_message_data(message_data.to_json())))
+            elif hasattr(message_data, "get"):
+                parsed_messages.append(dict(_parse_message_data(message_data)))
+            else:
+                raise ValueError(f"fail to parse message of type {type(message_data)}")
+    if parsed_messages:
+        yield GEN_AI_OUTPUT_MESSAGES_KEY, parsed_messages
+
+
+@stop_on_exception
+def invocation_parameters(run: Run) -> Iterator[tuple[str, str]]:
+    """Yields invocation parameters if present."""
+    if run.run_type.lower() != "llm":
+        return
+    if not (extra := run.extra):
+        return
+    assert hasattr(extra, "get"), f"expected Mapping, found {type(extra)}"
+    if invocation_parameters := extra.get("invocation_params"):
+        assert isinstance(invocation_parameters, Mapping), (
+            f"expected Mapping, found {type(invocation_parameters)}"
+        )
+        yield GEN_AI_INPUT_MESSAGES_KEY, safe_json_dumps(invocation_parameters)
+        tools = invocation_parameters.get("tools", [])
+        for idx, tool in enumerate(tools):
+            yield f"{GEN_AI_TOOL_ARGS_KEY}.{idx}", safe_json_dumps(tool)
+
+
+@stop_on_exception
+def llm_provider(extra: Mapping[str, Any] | None) -> Iterator[tuple[str, str]]:
+    if not extra:
+        return
+    if (meta := extra.get("metadata")) and (ls_provider := meta.get("ls_provider")):
+        ls_provider_lower = ls_provider.lower()
+        yield GEN_AI_PROVIDER_NAME_KEY, ls_provider_lower
+
+
+@stop_on_exception
+def model_name(
+    outputs: Mapping[str, Any] | None,
+    extra: Mapping[str, Any] | None,
+) -> Iterator[tuple[str, str]]:
+    """Yields model name if present."""
+    if (
+        outputs
+        and hasattr(outputs, "get")
+        and (llm_output := outputs.get("llm_output"))
+        and hasattr(llm_output, "get")
+    ):
+        for key in "model_name", "model":
+            if name := str(llm_output.get(key) or "").strip():
+                yield GEN_AI_REQUEST_MODEL_KEY, name
+                return
+    if not extra:
+        return
+    assert hasattr(extra, "get"), f"expected Mapping, found {type(extra)}"
+    if (
+        (metadata := extra.get("metadata"))
+        and hasattr(metadata, "get")
+        and (ls_model_name := str(metadata.get("ls_model_name") or "").strip())
+    ):
+        yield GEN_AI_REQUEST_MODEL_KEY, ls_model_name
+        return
+    if not (invocation_params := extra.get("invocation_params")):
+        return
+    for key in ["model_name", "model"]:
+        if name := invocation_params.get(key):
+            yield GEN_AI_REQUEST_MODEL_KEY, name
+            return
+
+
+@stop_on_exception
+def token_counts(outputs: Mapping[str, Any] | None) -> Iterator[tuple[str, int]]:
+    """Yields token count information if present."""
+    if not (token_usage := (parse_token_usage_for_non_streaming_outputs(outputs))):
+        return
+    for attribute_name, keys in [
+        (
+            GEN_AI_USAGE_INPUT_TOKENS_KEY,
+            (
+                "prompt_tokens",
+                "input_tokens",  # Anthropic-specific key
+                "prompt_token_count",  # Gemini-specific key - https://ai.google.dev/gemini-api/docs/tokens?lang=python
+            ),
+        ),
+        (
+            GEN_AI_USAGE_OUTPUT_TOKENS_KEY,
+            (
+                "completion_tokens",
+                "output_tokens",  # Anthropic-specific key
+                "candidates_token_count",  # Gemini-specific key
+            ),
+        ),
+    ]:
+        if (token_count := get_first_value(token_usage, keys)) is not None:
+            yield attribute_name, token_count
+
+    # OpenAI
+    for attribute_name, details_key, keys in [
+        (
+            GEN_AI_RESPONSE_FINISH_REASONS_KEY,
+            "completion_tokens_details",
+            ("reasoning_tokens",),
+        ),
+    ]:
+        if (details := token_usage.get(details_key)) is not None:
+            if (token_count := get_first_value(details, keys)) is not None:
+                yield attribute_name, token_count
+
+    # maps langchain_core.messages.ai.UsageMetadata object
+    for attribute_name, details_key_or_none, keys in [
+        (GEN_AI_USAGE_INPUT_TOKENS_KEY, None, ("input_tokens",)),
+        (GEN_AI_USAGE_OUTPUT_TOKENS_KEY, None, ("output_tokens",)),
+        (
+            GEN_AI_RESPONSE_FINISH_REASONS_KEY,
+            "output_token_details",
+            ("reasoning",),
+        ),
+    ]:
+        details = token_usage.get(details_key_or_none) if details_key_or_none else token_usage
+        if details is not None:
+            if (token_count := get_first_value(details, keys)) is not None:
+                yield attribute_name, token_count
+
+
+def parse_token_usage_for_non_streaming_outputs(
+    outputs: Mapping[str, Any] | None,
+) -> Any:
+    """
+    Parses output to get token usage information for non-streaming LLMs, i.e.,
+    when `stream_usage` is set to false.
+    """
+    if (
+        outputs
+        and hasattr(outputs, "get")
+        and (llm_output := outputs.get("llm_output"))
+        and hasattr(llm_output, "get")
+        and (
+            token_usage := get_first_value(
+                llm_output,
+                (
+                    "token_usage",
+                    "usage",  # Anthropic-specific key
+                ),
+            )
+        )
+    ):
+        return token_usage
+    return None
+
+
+@stop_on_exception
+def function_calls(outputs: Mapping[str, Any] | None) -> Iterator[tuple[str, str]]:
+    """
+    Extract a single OpenAI-style function call from model outputs and emit
+    GenAI tool attributes as (key, value) pairs. Arguments/result are JSON strings.
+
+    """
+    if not outputs:
+        return
+    assert hasattr(outputs, "get"), f"expected Mapping, found {type(outputs)}"
+
+    try:
+        # Typical OpenAI LangChain shape:
+        # outputs["generations"][0][0]["message"]["kwargs"]["additional_kwargs"]["function_call"]
+        fc = deepcopy(
+            outputs["generations"][0][0]["message"]["kwargs"]["additional_kwargs"]["function_call"]
+        )
+    except Exception:
+        return
+
+    if not isinstance(fc, dict):
+        return
+
+    # Tool type (explicit)
+    yield GEN_AI_OPERATION_NAME_KEY, "execute_tool"
+    yield GEN_AI_TOOL_TYPE_KEY, "function"
+
+    name = fc.get("name")
+    if isinstance(name, str):
+        yield GEN_AI_TOOL_NAME_KEY, name
+
+    desc = fc.get("description")
+    if isinstance(desc, str):
+        yield GEN_AI_TOOL_DESCRIPTION_KEY, desc
+
+    call_id = fc.get("id")
+    if isinstance(call_id, str):
+        yield GEN_AI_TOOL_CALL_ID_KEY, call_id
+
+    args = fc.get("arguments")
+    if args is not None:
+        if isinstance(args, str):
+            # If it's a JSON string, try to parse then re-dump for normalization
+            try:
+                args_json = safe_json_dumps(json.loads(args))
+            except Exception:
+                # Not valid JSON; store raw string
+                args_json = safe_json_dumps(args)
+        else:
+            args_json = safe_json_dumps(args)
+        yield GEN_AI_TOOL_ARGS_KEY, args_json
+
+    result = fc.get("result")
+    if result is not None:
+        yield GEN_AI_TOOL_CALL_RESULT_KEY, safe_json_dumps(result)
+
+
+@stop_on_exception
+def tools(run: Run) -> Iterator[tuple[str, str]]:
+    """Yields tool attributes if present."""
+    if run.run_type.lower() != "tool":
+        return
+    if not (serialized := run.serialized):
+        return
+    assert hasattr(serialized, "get"), f"expected Mapping, found {type(serialized)}"
+    yield GEN_AI_TOOL_TYPE_KEY, "extension"
+    if name := serialized.get("name"):
+        yield GEN_AI_TOOL_NAME_KEY, name
+    if description := serialized.get("description"):
+        yield GEN_AI_TOOL_DESCRIPTION_KEY, description
+
+
+def add_operation_type(run: Run) -> Iterator[tuple[str, str]]:
+    """Yields operation type based on run type."""
+    run_type = run.run_type.lower()
+    if run_type == "llm":
+        yield GEN_AI_OPERATION_NAME_KEY, InferenceOperationType.CHAT.value.lower()
+    elif run_type == "chat_model":
+        yield GEN_AI_OPERATION_NAME_KEY, "chat"
+    elif run_type == "tool":
+        yield GEN_AI_OPERATION_NAME_KEY, "execute_tool"

microsoft_agents_a365_observability_extensions_langchain-0.1.0.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: microsoft-agents-a365-observability-extensions-langchain
+Version: 0.1.0
+Summary: LangChain observability and tracing extensions for Microsoft Agent 365
+Author-email: Microsoft <support@microsoft.com>
+License: MIT
+Project-URL: Homepage, https://github.com/microsoft/Agent365-python
+Project-URL: Repository, https://github.com/microsoft/Agent365-python
+Project-URL: Issues, https://github.com/microsoft/Agent365-python/issues
+Project-URL: Documentation, https://github.com/microsoft/Agent365-python/tree/main/libraries/microsoft-agents-a365-observability-extensions-langchain
+Keywords: observability,telemetry,tracing,opentelemetry,langchain,agents,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: microsoft-agents-a365-observability-core>=0.0.0
+Requires-Dist: langchain>=0.1.0
+Requires-Dist: langchain-core>=0.1.0
+Requires-Dist: opentelemetry-api>=1.36.0
+Requires-Dist: opentelemetry-sdk>=1.36.0
+Requires-Dist: opentelemetry-instrumentation>=0.47b0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+
+# microsoft-agents-a365-observability-extensions-langchain
+
+[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-observability-extensions-langchain?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-observability-extensions-langchain)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-observability-extensions-langchain?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-observability-extensions-langchain)
+
+Observability extensions for LangChain framework. This package provides OpenTelemetry tracing integration for LangChain-based AI applications with automatic instrumentation for chains, agents, and tools.
+
+## Installation
+
+```bash
+pip install microsoft-agents-a365-observability-extensions-langchain
+```
+
+## Usage
+
+For usage examples and detailed documentation, see the [Observability documentation](https://learn.microsoft.com/microsoft-agent-365/developer/observability?tabs=python) on Microsoft Learn.
+
+## Support
+
+For issues, questions, or feedback:
+
+- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section
+- See the [main documentation](../../../README.md) for more information
+ 
+## Trademarks
+ 
+*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.*
+
+## License
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details.

microsoft_agents_a365_observability_extensions_langchain-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+microsoft_agents_a365/observability/extensions/langchain/__init__.py,sha256=blbo-Zwz2GZ3n6hrnrTfxpLpnN32OJkotwHSgUnrEn8,338
+microsoft_agents_a365/observability/extensions/langchain/tracer.py,sha256=ksXN4cUXYwSWgimkiL44VTmeKqi9ZoeqA4jBsadzx30,8655
+microsoft_agents_a365/observability/extensions/langchain/tracer_instrumentor.py,sha256=RDjGp8Jc2jZuBO3UDgZen071roWEiKFX1-bnbXbIOdw,6255
+microsoft_agents_a365/observability/extensions/langchain/utils.py,sha256=BZv08hJ64s9mI1L980FOKAtDlKiWCDctqR4sZ9kOyL4,19056
+microsoft_agents_a365_observability_extensions_langchain-0.1.0.dist-info/METADATA,sha256=wVhQLSs0dr2zdyuxPPlp8p-FjN2h9HBHe00dZCpH3nw,3669
+microsoft_agents_a365_observability_extensions_langchain-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+microsoft_agents_a365_observability_extensions_langchain-0.1.0.dist-info/top_level.txt,sha256=G3c2_4sy5_EM_BWO67SbK2tKj4G8XFn-QXRbh8g9Lgk,22
+microsoft_agents_a365_observability_extensions_langchain-0.1.0.dist-info/RECORD,,

microsoft_agents_a365_observability_extensions_langchain-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

microsoft_agents_a365_observability_extensions_langchain-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+microsoft_agents_a365