Add patch_abc utility

Author: pmcollins

docs/examples/abcwrap/langchain_example.py

@@ -0,0 +1,120 @@
+"""
+LangChain ABC Patching Example
+
+This module demonstrates how to use `patch_abc` to instrument multiple LangChain language model implementations without
+needing to patch each provider individually.
+
+Overview:
+- Uses `patch_abc` to instrument LangChain's BaseLLM and BaseChatModel abstract base classes
+- Automatically applies instrumentation to all concrete implementations (OpenAI, Ollama, HuggingFace)
+- Provides a CLI interface to switch between different model providers at runtime
+- Demonstrates runtime polymorphism with a `chat_with_model` function
+
+Supported Providers:
+- OpenAI (ChatOpenAI) - inherits from BaseChatModel
+- Ollama (OllamaLLM) - inherits from BaseLLM
+- HuggingFace (HuggingFaceEndpoint) - inherits from BaseLLM
+
+Important Notes:
+- Model imports must happen BEFORE patching for the instrumentation to work
+- OpenAI models call _generate twice, hence the dual patching approach
+- The wrapper captures and logs all arguments/kwargs passed to the _generate method
+
+Usage:
+    python langchain_example.py --provider ollama
+    python langchain_example.py --provider openai --model gpt-4
+    python langchain_example.py --provider huggingface --prompt "Custom question"
+"""
+import argparse
+
+from langchain_core.language_models import BaseLLM, BaseChatModel
+from langchain_core.language_models.base import BaseLanguageModel
+
+# important note: if you import these after patching, the patch won't apply!
+# mitigation will be added to patch_abc in a future release
+from langchain_huggingface import HuggingFaceEndpoint
+from langchain_ollama import OllamaLLM
+from langchain_openai import ChatOpenAI
+
+from opentelemetry.util._wrap import patch_abc
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="LangChain model comparison")
+    parser.add_argument("--provider", choices=["ollama", "openai", "huggingface"], default="ollama",
+                        help="Choose model provider (default: ollama)")
+    parser.add_argument("--model", type=str, help="Specify model name")
+    parser.add_argument("--prompt", type=str, default="What is the capital of France?",
+                        help="Input prompt")
+
+    return parser.parse_args()
+
+
+def chat_with_model(model: BaseLanguageModel, prompt: str) -> str:
+    try:
+        response = model.invoke(prompt)
+        if hasattr(response, 'content'):
+            return response.content
+        else:
+            return str(response)
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+
+def create_huggingface_model(model: str = "google/flan-t5-small"):
+    return HuggingFaceEndpoint(
+        repo_id=model,
+        temperature=0.7
+    )
+
+
+def create_openai_model(model: str = "gpt-3.5-turbo"):
+    return ChatOpenAI(
+        model=model,
+        temperature=0.7
+    )
+
+
+def create_ollama_model(model: str = "llama2"):
+    return OllamaLLM(
+        model=model,
+        temperature=0.7
+    )
+
+
+def patch_llm():
+    def my_wrapper(orig_fcn):
+        def wrapped_fcn(self, *args, **kwargs):
+            print("wrapper starting")
+            print(f"Arguments: {args}")
+            print(f"Keyword arguments: {kwargs}")
+            return orig_fcn(self, *args, **kwargs)
+
+        return wrapped_fcn
+
+    patch_abc(BaseLLM, "_generate", my_wrapper)
+
+    # this is for OpenAI, which is a weird case. The _generate method is in a differnt base class and gets called twice.
+    patch_abc(BaseChatModel, "_generate", my_wrapper)
+
+
+def main():
+    args = parse_args()
+
+    patch_llm()
+
+    if args.provider == "ollama":
+        model = create_ollama_model(args.model or "llama2")
+    elif args.provider == "openai":
+        model = create_openai_model(args.model or "gpt-3.5-turbo")
+    elif args.provider == "huggingface":
+        model = create_huggingface_model(args.model or "google/flan-t5-small")
+    else:
+        raise ValueError(f"Unsupported provider: {args.provider}")
+
+    response = chat_with_model(model, args.prompt)
+    print(f"{args.provider.title()} Response: {response}")
+
+
+if __name__ == "__main__":
+    main()

docs/examples/abcwrap/requirements.txt

@@ -0,0 +1,6 @@
+langchain-core
+langchain-openai
+langchain-ollama
+langchain-huggingface
+huggingface-hub
+opentelemetry-api

docs/examples/abcwrap/simple_example.py

@@ -0,0 +1,58 @@
+"""
+Simple example demonstrating the abstract base class patching utility.
+
+This module shows how to use the `patch_abc` function to instrument all implementations
+of an abstract base class without needing to patch each concrete class individually.
+
+Key Concepts:
+- Defines an abstract `Greeter` class with an abstract `greet` method
+- Creates two concrete implementations: `EngishGreeter` and `SpanishGreeter`
+- Uses `patch_abc` to wrap the abstract `greet` method with instrumentation
+- The wrapper automatically applies to all subclasses that implement the abstract method
+
+When run, this example demonstrates that:
+1. A single call to `patch_abc` on the base class instruments all subclasses
+2. The wrapper executes before and after each concrete implementation
+3. This provides a powerful way to add telemetry/logging to entire class hierarchies
+
+Output:
+    wrapper running
+    hello
+    wrapper running
+    hola
+"""
+from abc import ABC, abstractmethod
+
+from opentelemetry.util._wrap import patch_abc
+
+
+class Greeter(ABC):
+    @abstractmethod
+    def greet(self):
+        pass
+
+
+class EngishGreeter(Greeter):
+    def greet(self):
+        print("hello")
+
+
+class SpanishGreeter(Greeter):
+    def greet(self):
+        print("hola")
+
+
+if __name__ == '__main__':
+    def my_wrapper(orig_fcn):
+        def wrapped_fcn(self, *args, **kwargs):
+            print("wrapper running")
+            result = orig_fcn(self, *args, **kwargs)
+            return result
+
+        return wrapped_fcn
+
+
+    patch_abc(Greeter, "greet", my_wrapper)
+
+    EngishGreeter().greet()
+    SpanishGreeter().greet()

opentelemetry-api/src/opentelemetry/util/_wrap.py

@@ -0,0 +1,41 @@
+def patch_abc(abstract_base_class, method_name, w):
+    """
+    Monkey patches a method across all subclasses of an abstract base class.
+
+    This function finds all concrete subclasses of the given abstract base class
+    and applies the provided wrapper function to the specified method in each subclass.
+
+    This approach is necessary because you can't directly monkey patch an abstract
+    method in a base class -- concrete implementations in subclasses won't inherit
+    the patched behavior since they override the abstract method. Instead, we
+    individually patch each implementation in each concrete subclass.
+
+    Args:
+        abstract_base_class: The abstract base class whose subclasses will be patched
+        method_name: Name of the method to patch
+        w: A wrapper function that takes the original method as an argument
+           and returns a new function to replace it
+
+    Example:
+        patch_abc(Greeter, "greet", my_wrapper)
+    """
+    subclasses = recursively_get_all_subclasses(abstract_base_class)
+    for subclass in subclasses:
+        old_method = getattr(subclass, method_name)
+        setattr(subclass, method_name, w(old_method))
+
+    # This implementation does not work if the instrumented class is imported after the instrumentor runs.
+    # However, that case can be handled by querying the gc module for all existing classes; this capability can be added
+    # in a follow-up release.
+
+
+def recursively_get_all_subclasses(cls):
+    out = set()
+    for subclass in cls.__subclasses__():
+        out.add(subclass)
+        out.update(recursively_get_all_subclasses(subclass))
+    return out
+
+
+if __name__ == "__main__":
+    pass