mseep-agentops 0.4.18__py3-none-any.whl → 0.4.23__py3-none-any.whl

agentops/client/http/http_client.py

@@ -1,4 +1,5 @@
 from typing import Dict, Optional
+import threading
 
 import requests
 
@@ -6,150 +7,118 @@ from agentops.client.http.http_adapter import BaseHTTPAdapter
 from agentops.logging import logger
 from agentops.helpers.version import get_agentops_version
 
+# Import aiohttp for async requests
+try:
+    import aiohttp
+
+    AIOHTTP_AVAILABLE = True
+except ImportError:
+    AIOHTTP_AVAILABLE = False
+    # Don't log warning here, only when actually trying to use async functionality
+
 
 class HttpClient:
-    """Base HTTP client with connection pooling and session management"""
+    """HTTP client with async-first design and optional sync fallback for log uploads"""
 
     _session: Optional[requests.Session] = None
+    _async_session: Optional[aiohttp.ClientSession] = None
     _project_id: Optional[str] = None
+    _session_lock = threading.Lock()
 
     @classmethod
     def get_project_id(cls) -> Optional[str]:
         """Get the stored project ID"""
         return cls._project_id
 
+    @classmethod
+    def set_project_id(cls, project_id: str) -> None:
+        """Set the project ID"""
+        cls._project_id = project_id
+
     @classmethod
     def get_session(cls) -> requests.Session:
-        """Get or create the global session with optimized connection pooling"""
+        """
+        Get or create the global session with optimized connection pooling.
+
+        Note: This method is deprecated. Use async_request() instead.
+        Only kept for log upload module compatibility.
+        """
         if cls._session is None:
-            cls._session = requests.Session()
-
-            # Configure connection pooling
-            adapter = BaseHTTPAdapter()
-
-            # Mount adapter for both HTTP and HTTPS
-            cls._session.mount("http://", adapter)
-            cls._session.mount("https://", adapter)
-
-            # Set default headers
-            cls._session.headers.update(
-                {
-                    "Connection": "keep-alive",
-                    "Keep-Alive": "timeout=10, max=1000",
-                    "Content-Type": "application/json",
-                    "User-Agent": f"agentops-python/{get_agentops_version() or 'unknown'}",
-                }
-            )
-            logger.debug(f"Agentops version: agentops-python/{get_agentops_version() or 'unknown'}")
+            with cls._session_lock:
+                if cls._session is None:  # Double-check locking
+                    cls._session = requests.Session()
+
+                    # Configure connection pooling
+                    adapter = BaseHTTPAdapter()
+
+                    # Mount adapter for both HTTP and HTTPS
+                    cls._session.mount("http://", adapter)
+                    cls._session.mount("https://", adapter)
+
+                    # Set default headers
+                    cls._session.headers.update(
+                        {
+                            "Connection": "keep-alive",
+                            "Keep-Alive": "timeout=10, max=1000",
+                            "Content-Type": "application/json",
+                            "User-Agent": f"agentops-python/{get_agentops_version() or 'unknown'}",
+                        }
+                    )
+                    logger.debug(f"Agentops version: agentops-python/{get_agentops_version() or 'unknown'}")
         return cls._session
 
-    # @classmethod
-    # def get_authenticated_session(
-    #     cls,
-    #     endpoint: str,
-    #     api_key: str,
-    #     token_fetcher: Optional[Callable[[str], str]] = None,
-    # ) -> requests.Session:
-    #     """
-    #     Create a new session with authentication handling.
-    #
-    #     Args:
-    #         endpoint: Base API endpoint (used to derive auth endpoint if needed)
-    #         api_key: The API key to use for authentication
-    #         token_fetcher: Optional custom token fetcher function
-    #
-    #     Returns:
-    #         A requests.Session with authentication handling
-    #     """
-    #     # Create auth manager with default token endpoint
-    #     auth_endpoint = f"{endpoint}/auth/token"
-    #     auth_manager = AuthManager(auth_endpoint)
-    #
-    #     # Use provided token fetcher or create a default one
-    #     if token_fetcher is None:
-    #         def default_token_fetcher(key: str) -> str:
-    #             # Simple token fetching implementation
-    #             try:
-    #                 response = requests.post(
-    #                     auth_manager.token_endpoint,
-    #                     json={"api_key": key},
-    #                     headers={"Content-Type": "application/json"},
-    #                     timeout=30
-    #                 )
-    #
-    #                 if response.status_code == 401 or response.status_code == 403:
-    #                     error_msg = "Invalid API key or unauthorized access"
-    #                     try:
-    #                         error_data = response.json()
-    #                         if "error" in error_data:
-    #                             error_msg = error_data["error"]
-    #                     except Exception:
-    #                         if response.text:
-    #                             error_msg = response.text
-    #
-    #                     logger.error(f"Authentication failed: {error_msg}")
-    #                     raise AgentOpsApiJwtExpiredException(f"Authentication failed: {error_msg}")
-    #
-    #                 if response.status_code >= 500:
-    #                     logger.error(f"Server error during authentication: {response.status_code}")
-    #                     raise ApiServerException(f"Server error during authentication: {response.status_code}")
-    #
-    #                 if response.status_code != 200:
-    #                     logger.error(f"Unexpected status code during authentication: {response.status_code}")
-    #                     raise AgentOpsApiJwtExpiredException(f"Failed to fetch token: {response.status_code}")
-    #
-    #                 token_data = response.json()
-    #                 if "token" not in token_data:
-    #                     logger.error("Token not found in response")
-    #                     raise AgentOpsApiJwtExpiredException("Token not found in response")
-    #
-    #                 # Store project_id if present in the response
-    #                 if "project_id" in token_data:
-    #                     HttpClient._project_id = token_data["project_id"]
-    #                     logger.debug(f"Project ID stored: {HttpClient._project_id} (will be set as {ResourceAttributes.PROJECT_ID})")
-    #
-    #                 return token_data["token"]
-    #             except requests.RequestException as e:
-    #                 logger.error(f"Network error during authentication: {e}")
-    #                 raise AgentOpsApiJwtExpiredException(f"Network error during authentication: {e}")
-    #
-    #         token_fetcher = default_token_fetcher
-    #
-    #     # Create a new session
-    #     session = requests.Session()
-    #
-    #     # Create an authenticated adapter
-    #     adapter = AuthenticatedHttpAdapter(
-    #         auth_manager=auth_manager,
-    #         api_key=api_key,
-    #         token_fetcher=token_fetcher
-    #     )
-    #
-    #     # Mount the adapter for both HTTP and HTTPS
-    #     session.mount("http://", adapter)
-    #     session.mount("https://", adapter)
-    #
-    #     # Set default headers
-    #     session.headers.update({
-    #         "Connection": "keep-alive",
-    #         "Keep-Alive": "timeout=10, max=1000",
-    #         "Content-Type": "application/json",
-    #     })
-    #
-    #     return session
+    @classmethod
+    async def get_async_session(cls) -> Optional[aiohttp.ClientSession]:
+        """Get or create the global async session with optimized connection pooling"""
+        if not AIOHTTP_AVAILABLE:
+            logger.warning("aiohttp not available, cannot create async session")
+            return None
+
+        # Always create a new session if the current one is None or closed
+        if cls._async_session is None or cls._async_session.closed:
+            # Close the old session if it exists but is closed
+            if cls._async_session is not None and cls._async_session.closed:
+                cls._async_session = None
+
+            # Create connector with connection pooling
+            connector = aiohttp.TCPConnector(
+                limit=100,  # Total connection pool size
+                limit_per_host=30,  # Per-host connection limit
+                ttl_dns_cache=300,  # DNS cache TTL
+                use_dns_cache=True,
+                enable_cleanup_closed=True,
+            )
+
+            # Create session with default headers
+            headers = {
+                "Content-Type": "application/json",
+                "User-Agent": f"agentops-python/{get_agentops_version() or 'unknown'}",
+            }
+
+            cls._async_session = aiohttp.ClientSession(
+                connector=connector, headers=headers, timeout=aiohttp.ClientTimeout(total=30)
+            )
+
+        return cls._async_session
+
+    @classmethod
+    async def close_async_session(cls):
+        """Close the async session"""
+        if cls._async_session and not cls._async_session.closed:
+            await cls._async_session.close()
+            cls._async_session = None
 
     @classmethod
-    def request(
+    async def async_request(
         cls,
         method: str,
         url: str,
         data: Optional[Dict] = None,
         headers: Optional[Dict] = None,
         timeout: int = 30,
-        max_redirects: int = 5,
-    ) -> requests.Response:
+    ) -> Optional[Dict]:
         """
-        Make a generic HTTP request
+        Make an async HTTP request and return JSON response
 
         Args:
             method: HTTP method (e.g., 'get', 'post', 'put', 'delete')
@@ -157,59 +126,44 @@ class HttpClient:
             data: Request payload (for POST, PUT methods)
             headers: Request headers
             timeout: Request timeout in seconds
-            max_redirects: Maximum number of redirects to follow (default: 5)
 
         Returns:
-            Response from the API
-
-        Raises:
-            requests.RequestException: If the request fails
-            ValueError: If the redirect limit is exceeded or an unsupported HTTP method is used
+            JSON response as dictionary, or None if request failed
         """
-        session = cls.get_session()
-        method = method.lower()
-        redirect_count = 0
-
-        while redirect_count <= max_redirects:
-            # Make the request with allow_redirects=False
-            if method == "get":
-                response = session.get(url, headers=headers, timeout=timeout, allow_redirects=False)
-            elif method == "post":
-                response = session.post(url, json=data, headers=headers, timeout=timeout, allow_redirects=False)
-            elif method == "put":
-                response = session.put(url, json=data, headers=headers, timeout=timeout, allow_redirects=False)
-            elif method == "delete":
-                response = session.delete(url, headers=headers, timeout=timeout, allow_redirects=False)
-            else:
-                raise ValueError(f"Unsupported HTTP method: {method}")
-
-            # Check if we got a redirect response
-            if response.status_code in (301, 302, 303, 307, 308):
-                redirect_count += 1
-
-                if redirect_count > max_redirects:
-                    raise ValueError(f"Exceeded maximum number of redirects ({max_redirects})")
-
-                # Get the new location
-                if "location" not in response.headers:
-                    # No location header, can't redirect
-                    return response
-
-                # Update URL to the redirect location
-                url = response.headers["location"]
-
-                # For 303 redirects, always use GET for the next request
-                if response.status_code == 303:
-                    method = "get"
-                    data = None
-
-                logger.debug(f"Following redirect ({redirect_count}/{max_redirects}) to: {url}")
-
-                # Continue the loop to make the next request
-                continue
-
-            # Not a redirect, return the response
-            return response
-
-        # This should never be reached due to the max_redirects check above
-        return response
+        if not AIOHTTP_AVAILABLE:
+            logger.warning("aiohttp not available, cannot make async request")
+            return None
+
+        try:
+            session = await cls.get_async_session()
+            if not session:
+                return None
+
+            logger.debug(f"Making async {method} request to {url}")
+
+            # Prepare request parameters
+            kwargs = {"timeout": aiohttp.ClientTimeout(total=timeout), "headers": headers or {}}
+
+            if data and method.lower() in ["post", "put", "patch"]:
+                kwargs["json"] = data
+
+            # Make the request
+            async with session.request(method.upper(), url, **kwargs) as response:
+                logger.debug(f"Async request response status: {response.status}")
+
+                # Check if response is successful
+                if response.status >= 400:
+                    return None
+
+                # Parse JSON response
+                try:
+                    response_data = await response.json()
+                    logger.debug(
+                        f"Async request successful, response keys: {list(response_data.keys()) if response_data else 'None'}"
+                    )
+                    return response_data
+                except Exception:
+                    return None
+
+        except Exception:
+            return None

agentops/config.py

@@ -9,7 +9,6 @@ from uuid import UUID
 from opentelemetry.sdk.trace import SpanProcessor
 from opentelemetry.sdk.trace.export import SpanExporter
 
-from agentops.exceptions import InvalidApiKeyException
 from agentops.helpers.env import get_env_bool, get_env_int, get_env_list
 from agentops.helpers.serialization import AgentOpsJSONEncoder
 
@@ -166,7 +165,14 @@ class Config:
                 try:
                     UUID(api_key)
                 except ValueError:
-                    raise InvalidApiKeyException(api_key, self.endpoint)
+                    # Log warning but don't throw exception - let async auth handle it
+                    from agentops.logging import logger
+
+                    logger.warning(
+                        f"API key format appears invalid: {api_key[:8]}... "
+                        f"Authentication may fail. Find your API key at {self.endpoint}/settings/projects"
+                    )
+                    # Continue with the invalid key - async auth will handle the failure gracefully
 
         if endpoint is not None:
             self.endpoint = endpoint

agentops/instrumentation/OpenTelemetry.md

@@ -0,0 +1,133 @@
+# OpenTelemetry Implementation Notes
+
+This document outlines best practices and implementation details for OpenTelemetry in AgentOps instrumentations.
+
+## Key Concepts
+
+### Context Propagation
+
+OpenTelemetry relies on proper context propagation to maintain parent-child relationships between spans. This is essential for:
+
+- Creating accurate trace waterfalls in visualizations
+- Ensuring all spans from the same logical operation share a trace ID
+- Allowing proper querying and filtering of related operations
+
+### Core Patterns
+
+When implementing instrumentations that need to maintain context across different execution contexts:
+
+1. **Store span contexts in dictionaries:**
+   ```python
+   # Use weakref dictionaries to avoid memory leaks
+   self._span_contexts = weakref.WeakKeyDictionary()
+   self._trace_root_contexts = weakref.WeakKeyDictionary()
+   ```
+
+2. **Create spans with explicit parent contexts:**
+   ```python
+   parent_context = self._get_parent_context(trace_obj)
+   with trace.start_as_current_span(
+       name=span_name,
+       context=parent_context,
+       kind=trace.SpanKind.CLIENT,
+       attributes=attributes,
+   ) as span:
+       # Span operations here
+       # Store the span's context for future reference
+       context = trace.set_span_in_context(span)
+       self._span_contexts[span_obj] = context
+   ```
+
+3. **Implement helper methods to retrieve appropriate parent contexts:**
+   ```python
+   def _get_parent_context(self, trace_obj):
+       # Try to get the trace's root context if it exists
+       if trace_obj in self._trace_root_contexts:
+           return self._trace_root_contexts[trace_obj]
+       
+       # Otherwise, use the current context
+       return context_api.context.get_current()
+   ```
+
+4. **Debug trace continuity:**
+   ```python
+   current_span = trace.get_current_span()
+   span_context = current_span.get_span_context()
+   trace_id = format_trace_id(span_context.trace_id)
+   logging.debug(f"Current span trace ID: {trace_id}")
+   ```
+
+## Common Pitfalls
+
+1. **Naming conflicts:** Avoid using `trace` as a parameter name when you're also importing the OpenTelemetry `trace` module
+   ```python
+   # Bad
+   def on_trace_start(self, trace):
+       # This will cause conflicts with the imported trace module
+   
+   # Good
+   def on_trace_start(self, trace_obj):
+       # No conflicts with OpenTelemetry's trace module
+   ```
+
+2. **Missing parent contexts:** Always explicitly provide parent contexts when available, don't rely on current context alone
+
+3. **Memory leaks:** Use `weakref.WeakKeyDictionary()` for storing spans to allow garbage collection
+
+4. **Lost context:** When calling async or callback functions, be sure to preserve and pass the context
+
+## Testing Context Propagation
+
+To verify proper context propagation:
+
+1. Enable debug logging for trace IDs
+2. Run a simple end-to-end test that generates multiple spans
+3. Verify all spans share the same trace ID
+4. Check that parent-child relationships are correctly established
+
+```python
+# Example debug logging
+logging.debug(f"Span {span.name} has trace ID: {format_trace_id(span.get_span_context().trace_id)}")
+```
+
+## Timestamp Handling in OpenTelemetry
+
+When working with OpenTelemetry spans and timestamps:
+
+1. **Automatic Timestamp Tracking:** OpenTelemetry automatically tracks timestamps for spans. When a span is created with `tracer.start_span()` or `tracer.start_as_current_span()`, the start time is captured automatically. When `span.end()` is called, the end time is recorded.
+
+2. **No Manual Timestamp Setting Required:** The standard instrumentation pattern does not require manually setting timestamp attributes on spans. Instead, OpenTelemetry handles this internally through the SpanProcessor and Exporter classes.
+
+3. **Timestamp Representation:** In the OpenTelemetry data model, timestamps are stored as nanoseconds since the Unix epoch (January 1, 1970).
+
+4. **Serialization Responsibility:** The serialization of timestamps from OTel spans to output formats like JSON is handled by the Exporter components. If timestamps aren't appearing correctly in output APIs, the issue is likely in the API exporter, not in the span creation code.
+
+5. **Debugging Timestamps:** To debug timestamp issues, verify that spans are properly starting and ending, rather than manually setting timestamp attributes:
+
+```python
+# Good pattern - timestamps handled by OpenTelemetry automatically
+with tracer.start_as_current_span("my_operation") as span:
+    # Do work
+    pass  # span.end() is called automatically
+```
+
+Note: If timestamps are missing in API output (e.g., empty "start_time" fields), focus on fixes in the exporter and serialization layer, not by manually tracking timestamps in instrumentation code.
+
+## Attributes in OpenTelemetry
+
+When working with span attributes in OpenTelemetry:
+
+1. **Root Attributes Node:** The root `attributes` object in the API output JSON should always be empty. This is by design. All attribute data should be stored in the `span_attributes` object.
+
+2. **Span Attributes:** The `span_attributes` object is where all user-defined and semantic attribute data should be stored. This allows for a structured, hierarchical representation of attributes.
+
+3. **Structure Difference:** While the root `attributes` appears as an empty object in the API output, this is normal and expected. Do not attempt to populate this object directly or duplicate data from `span_attributes` into it.
+
+4. **Setting Attributes:** Always set span attributes using the semantic conventions defined in the `agentops/semconv` module:
+
+```python
+from agentops.semconv import agent
+
+# Good pattern - using semantic conventions
+span.set_attribute(agent.AGENT_NAME, "My Agent")
+```

agentops/instrumentation/README.md

@@ -0,0 +1,167 @@
+# AgentOps Instrumentation
+
+This package provides OpenTelemetry instrumentation for various LLM providers and related services.
+
+## Available Instrumentors
+
+- **OpenAI** (`v0.27.0+` and `v1.0.0+`)
+- **Anthropic** (`v0.7.0+`)
+- **Google GenAI** (`v0.1.0+`)
+- **IBM WatsonX AI** (`v0.1.0+`)
+- **CrewAI** (`v0.56.0+`)
+- **AG2/AutoGen** (`v0.3.2+`)
+- **Google ADK** (`v0.1.0+`)
+- **Agno** (`v0.0.1+`)
+- **Mem0** (`v0.1.0+`)
+- **smolagents** (`v0.1.0+`)
+
+## Common Module Usage
+
+The `agentops.instrumentation.common` module provides shared utilities for creating instrumentations:
+
+### Base Instrumentor
+
+Use `CommonInstrumentor` for creating new instrumentations:
+
+```python
+from agentops.instrumentation.common import CommonInstrumentor, InstrumentorConfig, WrapConfig
+
+class MyInstrumentor(CommonInstrumentor):
+    def __init__(self):
+        config = InstrumentorConfig(
+            library_name="my-library",
+            library_version="1.0.0",
+            wrapped_methods=[
+                WrapConfig(
+                    trace_name="my.method",
+                    package="my_library.module",
+                    class_name="MyClass",
+                    method_name="my_method",
+                    handler=my_attribute_handler
+                )
+            ],
+            dependencies=["my-library >= 1.0.0"]
+        )
+        super().__init__(config)
+```
+
+### Attribute Handlers
+
+Create attribute handlers to extract data from method calls:
+
+```python
+from agentops.instrumentation.common import AttributeMap
+
+def my_attribute_handler(args=None, kwargs=None, return_value=None) -> AttributeMap:
+    attributes = {}
+    
+    if kwargs and "model" in kwargs:
+        attributes["llm.request.model"] = kwargs["model"]
+    
+    if return_value and hasattr(return_value, "usage"):
+        attributes["llm.usage.total_tokens"] = return_value.usage.total_tokens
+    
+    return attributes
+```
+
+### Span Management
+
+Use the span management utilities for consistent span creation:
+
+```python
+from agentops.instrumentation.common import create_span, SpanAttributeManager
+
+# Create an attribute manager
+attr_manager = SpanAttributeManager(service_name="my-service")
+
+# Use the create_span context manager
+with create_span(
+    tracer,
+    "my.operation",
+    attributes={"my.attribute": "value"},
+    attribute_manager=attr_manager
+) as span:
+    # Your operation code here
+    pass
+```
+
+### Token Counting
+
+Use the token counting utilities for consistent token usage extraction:
+
+```python
+from agentops.instrumentation.common import TokenUsageExtractor, set_token_usage_attributes
+
+# Extract token usage from a response
+usage = TokenUsageExtractor.extract_from_response(response)
+
+# Set token usage attributes on a span
+set_token_usage_attributes(span, response)
+```
+
+### Streaming Support
+
+Use streaming utilities for handling streaming responses:
+
+```python
+from agentops.instrumentation.common import create_stream_wrapper_factory, StreamingResponseHandler
+
+# Create a stream wrapper factory
+wrapper = create_stream_wrapper_factory(
+    tracer,
+    "my.stream",
+    extract_chunk_content=StreamingResponseHandler.extract_generic_chunk_content,
+    initial_attributes={"stream.type": "text"}
+)
+
+# Apply to streaming methods
+wrap_function_wrapper("my_module", "stream_method", wrapper)
+```
+
+### Metrics
+
+Use standard metrics for consistency across instrumentations:
+
+```python
+from agentops.instrumentation.common import StandardMetrics, MetricsRecorder
+
+# Create standard metrics
+metrics = StandardMetrics.create_standard_metrics(meter)
+
+# Use the metrics recorder
+recorder = MetricsRecorder(metrics)
+recorder.record_token_usage(prompt_tokens=100, completion_tokens=50)
+recorder.record_duration(1.5)
+```
+
+## Creating a New Instrumentor
+
+1. Create a new directory under `agentops/instrumentation/` for your provider
+2. Create an `__init__.py` file with version information
+3. Create an `instrumentor.py` file extending `CommonInstrumentor`
+4. Create attribute handlers in an `attributes/` subdirectory
+5. Add your instrumentor to the main `__init__.py` configuration
+
+Example structure:
+```
+agentops/instrumentation/
+├── my_provider/
+│   ├── __init__.py
+│   ├── instrumentor.py
+│   └── attributes/
+│       ├── __init__.py
+│       └── handlers.py
+```
+
+## Best Practices
+
+1. **Use Common Utilities**: Leverage the common module for consistency
+2. **Follow Semantic Conventions**: Use attributes from `agentops.semconv`
+3. **Handle Errors Gracefully**: Wrap operations in try-except blocks
+4. **Support Async**: Provide both sync and async method wrapping
+5. **Document Attributes**: Comment on what attributes are captured
+6. **Test Thoroughly**: Write unit tests for your instrumentor
+
+## Examples
+
+See the `examples/` directory for usage examples of each instrumentor.