Skip to content

Python SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI

Better root span management (#999)

Dwij5b419d33ccbb
diff --git a/agentops/__init__.py b/agentops/__init__.py
index 29557e7d..3b252759 100755
--- a/agentops/__init__.py
+++ b/agentops/__init__.py
@@ -12,9 +12,12 @@ from agentops.legacy import (
LLMEvent,
) # type: ignore
-from typing import List, Optional, Union
+from typing import List, Optional, Union, Dict, Any
from agentops.client import Client
+from agentops.sdk.core import TracingCore, TraceContext
+from agentops.sdk.decorators import trace, session, agent, task, workflow, operation
+from agentops.logging.config import logger
# Client global instance; one per process runtime
_client = Client()
@@ -53,6 +56,7 @@ def init(
max_queue_size: Optional[int] = None,
tags: Optional[List[str]] = None,
default_tags: Optional[List[str]] = None,
+ trace_name: Optional[str] = None,
instrument_llm_calls: Optional[bool] = None,
auto_start_session: Optional[bool] = None,
auto_init: Optional[bool] = None,
@@ -78,6 +82,7 @@ def init(
max_queue_size (int, optional): The maximum size of the event queue. Defaults to 512.
tags (List[str], optional): [Deprecated] Use `default_tags` instead.
default_tags (List[str], optional): Default tags for the sessions that can be used for grouping or sorting later (e.g. ["GPT-4"]).
+ trace_name (str, optional): Name for the default trace/session. If none is provided, defaults to "default".
instrument_llm_calls (bool): Whether to instrument LLM calls and emit LLMEvents.
auto_start_session (bool): Whether to start a session automatically when the client is created.
auto_init (bool): Whether to automatically initialize the client on import. Defaults to True.
@@ -108,6 +113,7 @@ def init(
max_wait_time=max_wait_time,
max_queue_size=max_queue_size,
default_tags=merged_tags,
+ trace_name=trace_name,
instrument_llm_calls=instrument_llm_calls,
auto_start_session=auto_start_session,
auto_init=auto_init,
@@ -165,26 +171,80 @@ def configure(**kwargs):
# Check for invalid parameters
invalid_params = set(kwargs.keys()) - valid_params
if invalid_params:
- from .logging.config import logger
-
logger.warning(f"Invalid configuration parameters: {invalid_params}")
_client.configure(**kwargs)
+def start_trace(
+ trace_name: str = "session", tags: Optional[Union[Dict[str, Any], List[str]]] = None
+) -> Optional[TraceContext]:
+ """
+ Starts a new trace (root span) and returns its context.
+ This allows for multiple concurrent, user-managed traces.
+
+ Args:
+ trace_name: Name for the trace (e.g., "session", "my_custom_task").
+ tags: Optional tags to attach to the trace span (list of strings or dict).
+
+ Returns:
+ A TraceContext object containing the span and context token, or None if SDK not initialized.
+ """
+ tracing_core = TracingCore.get_instance()
+ if not tracing_core.initialized:
+ # Optionally, attempt to initialize the client if not already, or log a more severe warning.
+ # For now, align with legacy start_session that would try to init.
+ # However, explicit init is preferred before starting traces.
+ logger.warning("AgentOps SDK not initialized. Attempting to initialize with defaults before starting trace.")
+ try:
+ init() # Attempt to initialize with environment variables / defaults
+ if not tracing_core.initialized:
+ logger.error("SDK initialization failed. Cannot start trace.")
+ return None
+ except Exception as e:
+ logger.error(f"SDK auto-initialization failed during start_trace: {e}. Cannot start trace.")
+ return None
+
+ return tracing_core.start_trace(trace_name=trace_name, tags=tags)
+
+
+def end_trace(trace_context: Optional[TraceContext] = None, end_state: str = "Success") -> None:
+ """
+ Ends a trace (its root span) and finalizes it.
+ If no trace_context is provided, ends all active session spans.
+
+ Args:
+ trace_context: The TraceContext object returned by start_trace. If None, ends all active traces.
+ end_state: The final state of the trace (e.g., "Success", "Failure", "Error").
+ """
+ tracing_core = TracingCore.get_instance()
+ if not tracing_core.initialized:
+ logger.warning("AgentOps SDK not initialized. Cannot end trace.")
+ return
+ tracing_core.end_trace(trace_context=trace_context, end_state=end_state)
+
+
__all__ = [
"init",
"configure",
"get_client",
"record",
+ "start_trace",
+ "end_trace",
"start_session",
"end_session",
"track_agent",
"track_tool",
"end_all_sessions",
- "Session",
"ToolEvent",
"ErrorEvent",
"ActionEvent",
"LLMEvent",
+ "Session",
+ "trace",
+ "session",
+ "agent",
+ "task",
+ "workflow",
+ "operation",
]
diff --git a/agentops/client/api/versions/v3.py b/agentops/client/api/versions/v3.py
index f3a23286..62233141 100644
--- a/agentops/client/api/versions/v3.py
+++ b/agentops/client/api/versions/v3.py
@@ -30,28 +30,26 @@ class V3Client(BaseApiClient):
r = self.post(path, data, headers)
+ if r.status_code != 200:
+ error_msg = f"Authentication failed: {r.status_code}"
+ try:
+ error_data = r.json()
+ if "error" in error_data:
+ error_msg = f"{error_data['error']}"
+ except Exception:
+ pass
+ logger.error(f"{error_msg} - Perhaps an invalid API key?")
+ raise ApiServerException(error_msg)
+
try:
- if r.status_code != 200:
- error_msg = f"Authentication failed: {r.status_code}"
- try:
- error_data = r.json()
- if "error" in error_data:
- error_msg = f"{error_data['error']}"
- except Exception:
- pass
- raise ApiServerException(error_msg)
+ jr = r.json()
+ token = jr.get("token")
+ if not token:
+ raise ApiServerException("No token in authentication response")
- try:
- jr = r.json()
- token = jr.get("token")
- if not token:
- raise ApiServerException("No token in authentication response")
-
- return jr
- except Exception as e:
- raise ApiServerException(f"Failed to process authentication response: {str(e)}")
+ return jr
except Exception as e:
- logger.error(f"{str(e)} - Perhaps an invalid API key?")
- return None
+ logger.error(f"Failed to process authentication response: {str(e)}")
+ raise ApiServerException(f"Failed to process authentication response: {str(e)}")
# Add V3-specific API methods here
diff --git a/agentops/client/client.py b/agentops/client/client.py
index 9f29dcc9..2ceacd90 100644
--- a/agentops/client/client.py
+++ b/agentops/client/client.py
@@ -1,4 +1,5 @@
import atexit
+from typing import Optional, Any
from agentops.client.api import ApiClient
from agentops.config import Config
@@ -6,32 +7,32 @@ from agentops.exceptions import NoApiKeyException
from agentops.instrumentation import instrument_all
from agentops.logging import logger
from agentops.logging.config import configure_logging, intercept_opentelemetry_logging
-from agentops.sdk.core import TracingCore
+from agentops.sdk.core import TracingCore, TraceContext
+from agentops.legacy import Session
-# Global registry for active session
-_active_session = None
+# Global variables to hold the client's auto-started trace and its legacy session wrapper
+_client_init_trace_context: Optional[TraceContext] = None
+_client_legacy_session_for_init_trace: Optional[Session] = None
# Single atexit handler registered flag
_atexit_registered = False
-def _end_active_session():
- """Global handler to end the active session during shutdown"""
- global _active_session
- if _active_session is not None:
- logger.debug("Auto-ending active session during shutdown")
+def _end_init_trace_atexit():
+ """Global atexit handler to end the client's auto-initialized trace during shutdown."""
+ global _client_init_trace_context, _client_legacy_session_for_init_trace
+ if _client_init_trace_context is not None:
+ logger.debug("Auto-ending client's init trace during shutdown.")
try:
- from agentops.legacy import end_session
-
- end_session(_active_session)
+ # Use TracingCore to end the trace directly
+ tracing_core = TracingCore.get_instance()
+ if tracing_core.initialized and _client_init_trace_context.span.is_recording():
+ tracing_core.end_trace(_client_init_trace_context, end_state="Shutdown")
except Exception as e:
- logger.warning(f"Error ending active session during shutdown: {e}")
- # Final fallback: try to end the span directly
- try:
- if hasattr(_active_session, "span") and hasattr(_active_session.span, "end"):
- _active_session.span.end()
- except:
- pass
+ logger.warning(f"Error ending client's init trace during shutdown: {e}")
+ finally:
+ _client_init_trace_context = None
+ _client_legacy_session_for_init_trace = None # Clear its legacy wrapper too
class Client:
@@ -39,79 +40,143 @@ class Client:
config: Config
_initialized: bool
+ _init_trace_context: Optional[TraceContext] = None # Stores the context of the auto-started trace
+ _legacy_session_for_init_trace: Optional[
+ Session
+ ] = None # Stores the legacy Session wrapper for the auto-started trace
+
__instance = None # Class variable for singleton pattern
api: ApiClient
- def __new__(cls, *args, **kwargs):
+ def __new__(cls, *args: Any, **kwargs: Any) -> "Client":
if cls.__instance is None:
cls.__instance = super(Client, cls).__new__(cls)
+ # Initialize instance variables that should only be set once per instance
+ cls.__instance._init_trace_context = None
+ cls.__instance._legacy_session_for_init_trace = None
return cls.__instance
def __init__(self):
- # Only initialize once
- self._initialized = False
- self.config = Config()
-
- def init(self, **kwargs):
+ # Initialization of attributes like config, _initialized should happen here if they are instance-specific
+ # and not shared via __new__ for a true singleton that can be re-configured.
+ # However, the current pattern re-initializes config in init().
+ if (
+ not hasattr(self, "_initialized") or not self._initialized
+ ): # Ensure init logic runs only once per actual initialization intent
+ self.config = Config() # Initialize config here for the instance
+ self._initialized = False
+ # self._init_trace_context = None # Already done in __new__
+ # self._legacy_session_for_init_trace = None # Already done in __new__
+
+ def init(self, **kwargs: Any) -> None: # Return type updated to None
# Recreate the Config object to parse environment variables at the time of initialization
+ # This allows re-init with new env vars if needed, though true singletons usually init once.
self.config = Config()
self.configure(**kwargs)
+ # Only treat as re-initialization if a different non-None API key is explicitly provided
+ provided_api_key = kwargs.get("api_key")
+ if self.initialized and provided_api_key is not None and provided_api_key != self.config.api_key:
+ logger.warning("AgentOps Client being re-initialized with a different API key. This is unusual.")
+ # Reset initialization status to allow re-init with new key/config
+ self._initialized = False
+ if self._init_trace_context and self._init_trace_context.span.is_recording():
+ logger.warning("Ending previously auto-started trace due to re-initialization.")
+ TracingCore.get_instance().end_trace(self._init_trace_context, "Reinitialized")
+ self._init_trace_context = None
+ self._legacy_session_for_init_trace = None
+
+ if self.initialized:
+ logger.debug("AgentOps Client already initialized.")
+ # If auto_start_session was true, return the existing legacy session wrapper
+ if self.config.auto_start_session:
+ return self._legacy_session_for_init_trace
+ return None # If not auto-starting, and already initialized, return None
+
if not self.config.api_key:
raise NoApiKeyException
- # TODO we may need to initialize logging before importing OTEL to capture all
configure_logging(self.config)
intercept_opentelemetry_logging()
self.api = ApiClient(self.config.endpoint)
- # Prefetch JWT token if enabled
- # TODO: Move this validation somewhere else (and integrate with self.config.prefetch_jwt_token once we have a solution to that)
- response = self.api.v3.fetch_auth_token(self.config.api_key)
- if response is None:
- return
+ try:
+ response = self.api.v3.fetch_auth_token(self.config.api_key)
+ if response is None:
+ # If auth fails, we cannot proceed with TracingCore initialization that depends on project_id
+ logger.error("Failed to fetch auth token. AgentOps SDK will not be initialized.")
+ return None # Explicitly return None if auth fails
+ except Exception as e:
+ # Re-raise authentication exceptions so they can be caught by tests and calling code
+ logger.error(f"Authentication failed: {e}")
+ raise
- # Save the bearer for use with the v4 API
self.api.v4.set_auth_token(response["token"])
- # Initialize TracingCore with the current configuration and project_id
tracing_config = self.config.dict()
tracing_config["project_id"] = response["project_id"]
- TracingCore.initialize_from_config(tracing_config, jwt=response["token"])
+ tracing_core = TracingCore.get_instance()
+ tracing_core.initialize_from_config(tracing_config, jwt=response["token"])
- # Instrument LLM calls if enabled
if self.config.instrument_llm_calls:
instrument_all()
- self.initialized = True
+ # self._initialized = True # Set initialized to True here - MOVED to after trace start attempt
- # Register a single global atexit handler for session management
global _atexit_registered
if not _atexit_registered:
- atexit.register(_end_active_session)
+ atexit.register(_end_init_trace_atexit) # Register new atexit handler
_atexit_registered = True
- # Start a session if auto_start_session is True
- session = None
+ # Auto-start trace if configured
if self.config.auto_start_session:
- from agentops.legacy import start_session
-
- # Pass default_tags if they exist
- if self.config.default_tags:
- session = start_session(tags=list(self.config.default_tags))
- else:
- session = start_session()
-
- # Register this session globally
- global _active_session
- _active_session = session
-
- return session
-
- def configure(self, **kwargs):
+ if self._init_trace_context is None or not self._init_trace_context.span.is_recording():
+ logger.debug("Auto-starting init trace.")
+ trace_name = self.config.trace_name or "default"
+ self._init_trace_context = tracing_core.start_trace(
+ trace_name=trace_name,
+ tags=list(self.config.default_tags) if self.config.default_tags else None,
+ is_init_trace=True,
+ )
+ if self._init_trace_context:
+ self._legacy_session_for_init_trace = Session(self._init_trace_context)
+
+ # For backward compatibility, also update the global references in legacy and client modules
+ # These globals are what old code might have been using via agentops.legacy.get_session() or similar indirect access.
+ global _client_init_trace_context, _client_legacy_session_for_init_trace
+ _client_init_trace_context = self._init_trace_context
+ _client_legacy_session_for_init_trace = self._legacy_session_for_init_trace
+
+ # Update legacy module's _current_session and _current_trace_context
+ # This is tricky; direct access to another module's globals is not ideal.
+ # Prefer explicit calls if possible, but for maximum BC:
+ try:
+ import agentops.legacy
+
+ agentops.legacy._current_session = self._legacy_session_for_init_trace
+ agentops.legacy._current_trace_context = self._init_trace_context
+ except ImportError:
+ pass # Should not happen
+
+ else:
+ logger.error("Failed to start the auto-init trace.")
+ # Even if auto-start fails, core services up to TracingCore might be initialized.
+ # Set self.initialized to True if TracingCore is up, but return None.
+ self._initialized = tracing_core.initialized
+ return None # Failed to start trace
+
+ self._initialized = True # Successfully initialized and auto-trace started (if configured)
+ # For backward compatibility, return the legacy session wrapper when auto_start_session=True
+ return self._legacy_session_for_init_trace
+ else:
+ logger.debug("Auto-start session is disabled. No init trace started by client.")
+ self._initialized = True # Successfully initialized, just no auto-trace
+ return None # No auto-session, so return None
+
+ def configure(self, **kwargs: Any) -> None:
"""Update client configuration"""
self.config.configure(**kwargs)
@@ -120,10 +185,29 @@ class Client:
return self._initialized
@initialized.setter
- def initialized(self, value: bool):
+ def initialized(self, value: bool) -> None:
if self._initialized and self._initialized != value:
- raise ValueError("Client already initialized")
+ # Allow re-setting to False if we are intentionally re-initializing
+ # This logic is now partly in init() to handle re-init cases
+ pass
self._initialized = value
# ------------------------------------------------------------
- __instance = None
+ # Remove the old __instance = None at the end of the class definition if it's a repeat
+ # __instance = None # This was a class variable, should be defined once
+
+ # Make _init_trace_context and _legacy_session_for_init_trace accessible
+ # to the atexit handler if it becomes a static/class method or needs access
+ # For now, the atexit handler is global and uses global vars copied from these.
+
+ # Deprecate and remove the old global _active_session from this module.
+ # Consumers should use agentops.start_trace() or rely on the auto-init trace.
+ # For a transition, the auto-init trace's legacy wrapper is set to legacy module's globals.
+
+
+# Ensure the global _active_session (if needed for some very old compatibility) points to the client's legacy session for init trace.
+# This specific global _active_session in client.py is problematic and should be phased out.
+# For now, _client_legacy_session_for_init_trace is the primary global for the auto-init trace's legacy Session.
+
+# Remove the old global _active_session defined at the top of this file if it's no longer the primary mechanism.
+# The new globals _client_init_trace_context and _client_legacy_session_for_init_trace handle the auto-init trace.
diff --git a/agentops/config.py b/agentops/config.py
index 6af2005c..51fc6b1f 100644
--- a/agentops/config.py
+++ b/agentops/config.py
@@ -22,6 +22,7 @@ class ConfigDict(TypedDict):
export_flush_interval: Optional[int]
max_queue_size: Optional[int]
default_tags: Optional[List[str]]
+ trace_name: Optional[str]
instrument_llm_calls: Optional[bool]
auto_start_session: Optional[bool]
auto_init: Optional[bool]
@@ -69,6 +70,11 @@ class Config:
metadata={"description": "Default tags to apply to all sessions"},
)
+ trace_name: Optional[str] = field(
+ default_factory=lambda: os.getenv("AGENTOPS_TRACE_NAME"),
+ metadata={"description": "Default name for the trace/session"},
+ )
+
instrument_llm_calls: bool = field(
default_factory=lambda: get_env_bool("AGENTOPS_INSTRUMENT_LLM_CALLS", True),
metadata={"description": "Whether to automatically instrument and track LLM API calls"},
@@ -133,6 +139,7 @@ class Config:
export_flush_interval: Optional[int] = None,
max_queue_size: Optional[int] = None,
default_tags: Optional[List[str]] = None,
+ trace_name: Optional[str] = None,
instrument_llm_calls: Optional[bool] = None,
auto_start_session: Optional[bool] = None,
auto_init: Optional[bool] = None,
@@ -172,6 +179,9 @@ class Config:
if default_tags is not None:
self.default_tags = set(default_tags)
+ if trace_name is not None:
+ self.trace_name = trace_name
+
if instrument_llm_calls is not None:
self.instrument_llm_calls = instrument_llm_calls
@@ -224,6 +234,7 @@ class Config:
"export_flush_interval": self.export_flush_interval,
"max_queue_size": self.max_queue_size,
"default_tags": self.default_tags,
+ "trace_name": self.trace_name,
"instrument_llm_calls": self.instrument_llm_calls,
"auto_start_session": self.auto_start_session,
"auto_init": self.auto_init,
diff --git a/agentops/helpers/dashboard.py b/agentops/helpers/dashboard.py
index 8edde31c..ed43b807 100644
--- a/agentops/helpers/dashboard.py
+++ b/agentops/helpers/dashboard.py
@@ -2,7 +2,7 @@
Helpers for interacting with the AgentOps dashboard.
"""
-from typing import Union
+from typing import Union, Optional
from termcolor import colored
from opentelemetry.sdk.trace import Span, ReadableSpan
from agentops.logging import logger
@@ -33,7 +33,7 @@ def get_trace_url(span: Union[Span, ReadableSpan]) -> str:
return f"{app_url}/sessions?trace_id={trace_id}"
-def log_trace_url(span: Union[Span, ReadableSpan]) -> None:
+def log_trace_url(span: Union[Span, ReadableSpan], title: Optional[str] = None) -> None:
"""
Log the trace URL for the AgentOps dashboard.
@@ -41,4 +41,4 @@ def log_trace_url(span: Union[Span, ReadableSpan]) -> None:
span: The span to log the URL for.
"""
session_url = get_trace_url(span)
- logger.info(colored(f"\x1b[34mSession Replay: {session_url}\x1b[0m", "blue"))
+ logger.info(colored(f"\x1b[34mSession Replay for {title} trace: {session_url}\x1b[0m", "blue"))
diff --git a/agentops/instrumentation/crewai/instrumentation.py b/agentops/instrumentation/crewai/instrumentation.py
index b091a701..d655794b 100644
--- a/agentops/instrumentation/crewai/instrumentation.py
+++ b/agentops/instrumentation/crewai/instrumentation.py
@@ -171,8 +171,11 @@ def wrap_kickoff(
tag_list = list(config.default_tags)
attributes[CoreAttributes.TAGS] = tag_list
+ # Use trace_name from config if available, otherwise default to "crewai.workflow"
+ span_name = config.trace_name if config.trace_name else "crewai.workflow"
+
with tracer.start_as_current_span(
- "crewai.workflow",
+ span_name,
kind=SpanKind.INTERNAL,
attributes=attributes,
) as span:
diff --git a/agentops/legacy/__init__.py b/agentops/legacy/__init__.py
index f733f2ae..ff32beb8 100644
--- a/agentops/legacy/__init__.py
+++ b/agentops/legacy/__init__.py
@@ -12,10 +12,10 @@ This module maintains backward compatibility with all these API patterns.
from typing import Optional, Any, Dict, List, Union
from agentops.logging import logger
-from agentops.sdk.core import TracingCore
-from agentops.semconv.span_kinds import SpanKind
+from agentops.sdk.core import TracingCore, TraceContext
_current_session: Optional["Session"] = None
+_current_trace_context: Optional[TraceContext] = None
class Session:
@@ -28,306 +28,191 @@ class Session:
- end_session(): Called when a CrewAI run completes
"""
- def __init__(self, span: Any, token: Any):
- self.span = span
- self.token = token
+ def __init__(self, trace_context: Optional[TraceContext]):
+ self.trace_context = trace_context
- def __del__(self):
- try:
- if self.span is not None:
- self.span.end()
- except:
- pass
-
- def create_agent(self, name: Optional[str] = None, agent_id: Optional[str] = None, **kwargs):
- """
- Method to create an agent for CrewAI >= 0.105.0 compatibility.
+ @property
+ def span(self) -> Optional[Any]:
+ return self.trace_context.span if self.trace_context else None
- CrewAI >= 0.105.0 calls this with:
- - name=agent.role
- - agent_id=str(agent.id)
- """
- pass
+ @property
+ def token(self) -> Optional[Any]:
+ return self.trace_context.token if self.trace_context else None
- def record(self, event=None):
- """
- Method to record events for CrewAI >= 0.105.0 compatibility.
+ def __del__(self):
+ if self.trace_context and self.trace_context.span and self.trace_context.span.is_recording():
+ if not self.trace_context.is_init_trace:
+ logger.warning(
+ f"Legacy Session (trace ID: {self.trace_context.span.get_span_context().span_id}) \
+was garbage collected but its trace might still be recording. Ensure legacy sessions are ended with end_session()."
+ )
- CrewAI >= 0.105.0 calls this with a tool event when a tool is used.
- """
+ def create_agent(self, name: Optional[str] = None, agent_id: Optional[str] = None, **kwargs: Any):
+ """Method for CrewAI >= 0.105.0 compatibility. Currently a no-op."""
pass
- def end_session(self, **kwargs):
- """
- Method to end the session for CrewAI >= 0.105.0 compatibility.
-
- CrewAI >= 0.105.0 calls this with:
- - end_state="Success"
- - end_state_reason="Finished Execution"
-
- forces a flush to ensure the span is exported immediately.
- """
- if self.span is not None:
- _set_span_attributes(self.span, kwargs)
- self.span.end()
- _flush_span_processors()
-
-
-def _create_session_span(tags: Union[Dict[str, Any], List[str], None] = None) -> tuple:
- """
- Helper function to create a session span with tags.
-
- This is an internal function used by start_session() to create the
- from the SDK to create a span with kind=SpanKind.SESSION.
-
- Args:
- tags: Optional tags to attach to the span. These tags will be
- visible in the AgentOps dashboard and can be used for filtering.
-
- Returns:
- A tuple of (span, context, token) where:
- - context is the span context
- - token is the context token needed for detaching
- """
- from agentops.sdk.decorators.utility import _make_span
+ def record(self, event: Any = None):
+ """Method for CrewAI >= 0.105.0 compatibility. Currently a no-op."""
+ pass
- attributes = {}
- if tags:
- attributes["tags"] = tags
- return _make_span("session", span_kind=SpanKind.SESSION, attributes=attributes)
+ def end_session(self, **kwargs: Any):
+ """Ends the session for CrewAI >= 0.105.0 compatibility. Calls the global legacy end_session."""
+ end_session(session_or_status=self, **kwargs)
def start_session(
tags: Union[Dict[str, Any], List[str], None] = None,
) -> Session:
"""
- @deprecated
- Start a new AgentOps session manually.
-
- This function creates and starts a new session span, which can be used to group
- related operations together. The session will remain active until end_session
- is called either with the Session object or with kwargs.
-
- Usage patterns:
- 1. Standard pattern: session = start_session(); end_session(session)
- 2. CrewAI < 0.105.0: start_session(); end_session(end_state="Success", ...)
- 3. CrewAI >= 0.105.0: session = start_session(); session.end_session(end_state="Success", ...)
-
- This function stores the session in a global variable to support the CrewAI
- < 0.105.0 pattern where end_session is called without the session object.
-
- Args:
- tags: Optional tags to attach to the session, useful for filtering in the dashboard.
- Can be a list of strings or a dict of key-value pairs.
-
- Returns:
- A Session object that should be passed to end_session (except in the
- CrewAI < 0.105.0 pattern where end_session is called with kwargs only)
-
- Raises:
- AgentOpsClientNotInitializedException: If the client is not initialized
+ @deprecated Use agentops.start_trace() instead.
+ Starts a legacy AgentOps session. Calls TracingCore.start_trace internally.
"""
- global _current_session
+ global _current_session, _current_trace_context
+ tracing_core = TracingCore.get_instance()
- if not TracingCore.get_instance().initialized:
+ if not tracing_core.initialized:
from agentops import Client
- # Pass auto_start_session=False to prevent circular dependency
try:
Client().init(auto_start_session=False)
- # If initialization failed (returned None), create a dummy session
- if not TracingCore.get_instance().initialized:
- logger.warning(
- "AgentOps client initialization failed. Creating a dummy session that will not send data."
- )
- # Create a dummy session that won't send data but won't throw exceptions
- dummy_session = Session(None, None)
+ if not tracing_core.initialized:
+ logger.warning("AgentOps client init failed during legacy start_session. Creating dummy session.")
+ dummy_session = Session(None)
_current_session = dummy_session
+ _current_trace_context = None
return dummy_session
except Exception as e:
- logger.warning(
- f"AgentOps client initialization failed: {str(e)}. Creating a dummy session that will not send data."
- )
- # Create a dummy session that won't send data but won't throw exceptions
- dummy_session = Session(None, None)
+ logger.warning(f"AgentOps client init failed: {str(e)}. Creating dummy session.")
+ dummy_session = Session(None)
_current_session = dummy_session
+ _current_trace_context = None
return dummy_session
- span, ctx, token = _create_session_span(tags)
- session = Session(span, token)
+ trace_context = tracing_core.start_trace(trace_name="session", tags=tags)
+ if trace_context is None:
+ logger.error("Failed to start trace via TracingCore. Returning dummy session.")
+ dummy_session = Session(None)
+ _current_session = dummy_session
+ _current_trace_context = None
+ return dummy_session
- # Set the global session reference
- _current_session = session
+ session_obj = Session(trace_context)
+ _current_session = session_obj
+ _current_trace_context = trace_context
- # Also register with the client's session registry for consistent behavior
try:
import agentops.client.client
- agentops.client.client._active_session = session
- except Exception:
+ agentops.client.client._active_session = session_obj # type: ignore
+ if hasattr(agentops.client.client, "_active_trace_context"):
+ agentops.client.client._active_trace_context = trace_context # type: ignore
+ except (ImportError, AttributeError):
pass
-
- return session
+ return session_obj
def _set_span_attributes(span: Any, attributes: Dict[str, Any]) -> None:
- """
- Helper to set attributes on a span.
-
- Args:
- span: The span to set attributes on
- attributes: The attributes to set as a dictionary
- """
- if span is None:
+ """Helper to set attributes on a span for legacy purposes."""
+ if span is None or not attributes:
return
-
for key, value in attributes.items():
- span.set_attribute(f"agentops.status.{key}", str(value))
+ if key.lower() == "end_state" and "end_state" in attributes:
+ pass
+ else:
+ span.set_attribute(f"agentops.legacy.{key}", str(value))
-def _flush_span_processors() -> None:
+def end_session(session_or_status: Any = None, **kwargs: Any) -> None:
"""
- Helper to force flush all span processors.
+ @deprecated Use agentops.end_trace() instead.
+ Ends a legacy AgentOps session. Calls TracingCore.end_trace internally.
+ Supports multiple calling patterns for backward compatibility.
"""
- try:
- from opentelemetry.trace import get_tracer_provider
+ global _current_session, _current_trace_context
+ tracing_core = TracingCore.get_instance()
- tracer_provider = get_tracer_provider()
- tracer_provider.force_flush() # type: ignore
- except Exception as e:
- logger.warning(f"Failed to force flush span processor: {e}")
+ if not tracing_core.initialized:
+ logger.debug("Ignoring end_session: TracingCore not initialized.")
+ return
+ target_trace_context: Optional[TraceContext] = None
+ end_state_from_args = "Success"
+ extra_attributes = kwargs.copy()
+
+ if isinstance(session_or_status, Session):
+ target_trace_context = session_or_status.trace_context
+ if "end_state" in extra_attributes:
+ end_state_from_args = str(extra_attributes.pop("end_state"))
+ elif isinstance(session_or_status, str):
+ end_state_from_args = session_or_status
+ target_trace_context = _current_trace_context
+ if "end_state" in extra_attributes:
+ end_state_from_args = str(extra_attributes.pop("end_state"))
+ elif session_or_status is None and kwargs:
+ target_trace_context = _current_trace_context
+ if "end_state" in extra_attributes:
+ end_state_from_args = str(extra_attributes.pop("end_state"))
+ else:
+ target_trace_context = _current_trace_context
+ if "end_state" in extra_attributes:
+ end_state_from_args = str(extra_attributes.pop("end_state"))
+
+ if not target_trace_context:
+ logger.warning("end_session called but no active trace context found.")
+ return
-def end_session(session_or_status: Any = None, **kwargs) -> None:
- """
- @deprecated
- End a previously started AgentOps session.
-
- This function ends the session span and detaches the context token,
- completing the session lifecycle.
-
- This function supports multiple calling patterns for backward compatibility:
- 1. With a Session object: Used by most code and CrewAI >= 0.105.0 event system
- 2. With named parameters only: Used by CrewAI < 0.105.0 direct integration
- 3. With a string status: Used by some older code
-
- Args:
- session_or_status: The session object returned by start_session,
- or a string representing the status (for backwards compatibility)
- **kwargs: Additional arguments for CrewAI < 0.105.0 compatibility.
- CrewAI < 0.105.0 passes these named arguments:
- - end_state="Success"
- - end_state_reason="Finished Execution"
- - is_auto_end=True
-
- When called this way, the function will use the most recently
- created session via start_session().
- """
- global _current_session
+ if target_trace_context.span and extra_attributes:
+ _set_span_attributes(target_trace_context.span, extra_attributes)
- from agentops.sdk.decorators.utility import _finalize_span
- from agentops.sdk.core import TracingCore
+ tracing_core.end_trace(target_trace_context, end_state=end_state_from_args)
- if not TracingCore.get_instance().initialized:
- logger.debug("Ignoring end_session call - TracingCore not initialized")
- return
+ if target_trace_context is _current_trace_context:
+ _current_session = None
+ _current_trace_context = None
- # Clear client active session reference
try:
import agentops.client.client
- if session_or_status is None and kwargs:
- if _current_session is agentops.client.client._active_session:
- agentops.client.client._active_session = None
- elif hasattr(session_or_status, "span"):
- if session_or_status is agentops.client.client._active_session:
- agentops.client.client._active_session = None
- except Exception:
+ if (
+ hasattr(agentops.client.client, "_active_trace_context")
+ and agentops.client.client._active_trace_context is target_trace_context
+ ): # type: ignore
+ agentops.client.client._active_trace_context = None # type: ignore
+ agentops.client.client._active_session = None # type: ignore
+ elif (
+ hasattr(agentops.client.client, "_init_trace_context")
+ and agentops.client.client._init_trace_context is target_trace_context
+ ): # type: ignore
+ logger.debug("Legacy end_session called on client's auto-init trace. This is unusual.")
+ except (ImportError, AttributeError):
pass
- # In some old implementations, and in crew < 0.10.5 `end_session` will be
- # called with a single string as a positional argument like: "Success"
-
- # Handle the CrewAI < 0.105.0 integration pattern where end_session is called
- # with only named parameters. In this pattern, CrewAI does not keep a reference
- # to the Session object, instead it calls:
- #
- # agentops.end_session(
- # end_state="Success",
- # end_state_reason="Finished Execution",
- # is_auto_end=True
- # )
- if session_or_status is None and kwargs:
- if _current_session is not None:
- try:
- if _current_session.span is not None:
- _set_span_attributes(_current_session.span, kwargs)
- _finalize_span(_current_session.span, _current_session.token)
- _flush_span_processors()
- _current_session = None
- except Exception as e:
- logger.warning(f"Error ending current session: {e}")
- # Fallback: try direct span ending
- try:
- if hasattr(_current_session.span, "end"):
- _current_session.span.end()
- _current_session = None
- except:
- pass
+
+def end_all_sessions() -> None:
+ """@deprecated Ends all active sessions/traces."""
+ from agentops.sdk.core import TracingCore
+
+ tracing_core = TracingCore.get_instance()
+ if not tracing_core.initialized:
+ logger.debug("Ignoring end_all_sessions: TracingCore not initialized.")
return
- # Handle the standard pattern and CrewAI >= 0.105.0 pattern where a Session object is passed.
- # In both cases, we call _finalize_span with the span and token from the Session.
- # This is the most direct and precise way to end a specific session.
- if hasattr(session_or_status, "span") and hasattr(session_or_status, "token"):
- try:
- # Set attributes and finalize the span
- if session_or_status.span is not None:
- _set_span_attributes(session_or_status.span, kwargs)
- if session_or_status.span is not None:
- _finalize_span(session_or_status.span, session_or_status.token)
- _flush_span_processors()
-
- # Clear the global session reference if this is the current session
- if _current_session is session_or_status:
- _current_session = None
- except Exception as e:
- logger.warning(f"Error ending session object: {e}")
- # Fallback: try direct span ending
- try:
- if hasattr(session_or_status.span, "end"):
- session_or_status.span.end()
- if _current_session is session_or_status:
- _current_session = None
- except:
- pass
-
-
-def end_all_sessions():
- """
- @deprecated
- We don't automatically track more than one session, so just end the session
- that we are tracking.
- """
- end_session()
+ # Use the new end_trace functionality to end all active traces
+ tracing_core.end_trace(trace_context=None, end_state="Success")
+ # Clear legacy global state
+ global _current_session, _current_trace_context
+ _current_session = None
+ _current_trace_context = None
-def ToolEvent(*args, **kwargs) -> None:
- """
- @deprecated
- Use tracing instead.
- """
- return None
+def ToolEvent(*args: Any, **kwargs: Any) -> None:
+ """@deprecated Use tracing instead."""
+ return None
-def ErrorEvent(*args, **kwargs):
- """
- @deprecated
- Use tracing instead.
- For backward compatibility with tests, this returns a minimal object with the
- required attributes.
- """
+def ErrorEvent(*args: Any, **kwargs: Any) -> Any:
+ """@deprecated Use tracing instead. Returns minimal object for test compatibility."""
from agentops.helpers.time import get_ISO_time
class LegacyErrorEvent:
@@ -338,14 +223,8 @@ def ErrorEvent(*args, **kwargs):
return LegacyErrorEvent()
-def ActionEvent(*args, **kwargs):
- """
- @deprecated
- Use tracing instead.
-
- For backward compatibility with tests, this returns a minimal object with the
- required attributes.
- """
+def ActionEvent(*args: Any, **kwargs: Any) -> Any:
+ """@deprecated Use tracing instead. Returns minimal object for test compatibility."""
from agentops.helpers.time import get_ISO_time
class LegacyActionEvent:
@@ -356,33 +235,24 @@ def ActionEvent(*args, **kwargs):
return LegacyActionEvent()
-def LLMEvent(*args, **kwargs) -> None:
- """
- @deprecated
- Use tracing instead.
- """
+def LLMEvent(*args: Any, **kwargs: Any) -> None:
+ """@deprecated Use tracing instead."""
return None
-def track_agent(*args, **kwargs):
- """
- @deprecated
- Decorator for marking agents in legacy projects.
- """
+def track_agent(*args: Any, **kwargs: Any) -> Any:
+ """@deprecated No-op decorator."""
- def noop(f):
+ def noop(f: Any) -> Any:
return f
return noop
-def track_tool(*args, **kwargs):
- """
- @deprecated
- Decorator for marking tools and legacy projects.
- """
+def track_tool(*args: Any, **kwargs: Any) -> Any:
+ """@deprecated No-op decorator."""
- def noop(f):
+ def noop(f: Any) -> Any:
return f
return noop
@@ -397,4 +267,6 @@ __all__ = [
"track_agent",
"track_tool",
"end_all_sessions",
+ "Session", # Exposing the legacy Session class itself
+ "LLMEvent",
]
diff --git a/agentops/sdk/core.py b/agentops/sdk/core.py
index feecbc6f..d36c5522 100644
--- a/agentops/sdk/core.py
+++ b/agentops/sdk/core.py
@@ -6,7 +6,7 @@ import platform
import sys
import os
import psutil
-from typing import Optional
+from typing import Optional, Any, Dict
from opentelemetry import metrics, trace
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
@@ -14,7 +14,7 @@ from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExport
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import Resource
-from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace import TracerProvider, Span
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry import context as context_api
@@ -22,11 +22,20 @@ from agentops.exceptions import AgentOpsClientNotInitializedException
from agentops.logging import logger, setup_print_logger
from agentops.sdk.processors import InternalSpanProcessor
from agentops.sdk.types import TracingConfig
-from agentops.semconv import ResourceAttributes
+from agentops.semconv import ResourceAttributes, SpanKind, SpanAttributes, CoreAttributes
+from agentops.helpers.dashboard import log_trace_url
# No need to create shortcuts since we're using our own ResourceAttributes class now
+# Define TraceContext to hold span and token
+class TraceContext:
+ def __init__(self, span: Span, token: Optional[context_api.Token] = None, is_init_trace: bool = False):
+ self.span = span
+ self.token = token
+ self.is_init_trace = is_init_trace # Flag to identify the auto-started trace
+
+
def get_imported_libraries():
"""
Get the top-level imported libraries in the current script.
@@ -163,12 +172,14 @@ def setup_telemetry(
schedule_delay_millis=export_flush_interval,
)
provider.add_span_processor(processor)
- provider.add_span_processor(InternalSpanProcessor()) # Catches spans for AgentOps on-terminal printing
+ internal_processor = InternalSpanProcessor() # Catches spans for AgentOps on-terminal printing
+ provider.add_span_processor(internal_processor)
# Setup metrics
- metric_reader = PeriodicExportingMetricReader(
- OTLPMetricExporter(endpoint=metrics_endpoint, headers={"Authorization": f"Bearer {jwt}"} if jwt else {})
+ metric_exporter = OTLPMetricExporter(
+ endpoint=metrics_endpoint, headers={"Authorization": f"Bearer {jwt}"} if jwt else {}
)
+ metric_reader = PeriodicExportingMetricReader(metric_exporter)
meter_provider = MeterProvider(resource=resource, metric_readers=[metric_reader])
metrics.set_meter_provider(meter_provider)
@@ -176,7 +187,7 @@ def setup_telemetry(
setup_print_logger()
# Initialize root context
- context_api.get_current()
+ # context_api.get_current() # It's better to manage context explicitly with traces
logger.debug("Telemetry system initialized")
@@ -205,14 +216,18 @@ class TracingCore:
def __init__(self):
"""Initialize the tracing core."""
- self._provider = None
+ self._provider: Optional[TracerProvider] = None
+ self._meter_provider: Optional[MeterProvider] = None
self._initialized = False
- self._config = None
+ self._config: Optional[TracingConfig] = None
+ self._span_processors: list = []
+ self._active_traces: dict = {}
+ self._traces_lock = threading.Lock()
# Register shutdown handler
atexit.register(self.shutdown)
- def initialize(self, jwt: Optional[str] = None, **kwargs) -> None:
+ def initialize(self, jwt: Optional[str] = None, **kwargs: Any) -> None:
"""
Initialize the tracing core with the given configuration.
@@ -258,7 +273,7 @@ class TracingCore:
self._config = config
# Setup telemetry using the extracted configuration
- self._provider, self._meter_provider = setup_telemetry(
+ provider, meter_provider = setup_telemetry(
service_name=config["service_name"] or "",
project_id=config.get("project_id"),
exporter_endpoint=config["exporter_endpoint"],
@@ -269,6 +284,9 @@ class TracingCore:
jwt=jwt,
)
+ self._provider = provider
+ self._meter_provider = meter_provider
+
self._initialized = True
logger.debug("Tracing core initialized")
@@ -280,25 +298,48 @@ class TracingCore:
@property
def config(self) -> TracingConfig:
"""Get the tracing configuration."""
- return self._config # type: ignore
+ if self._config is None:
+ # This case should ideally not be reached if initialized properly
+ raise AgentOpsClientNotInitializedException("TracingCore config accessed before initialization.")
+ return self._config
def shutdown(self) -> None:
"""Shutdown the tracing core."""
with self._lock:
- # Perform a single flush on the SynchronousSpanProcessor (which takes care of all processors' shutdown)
- if not self._initialized:
+ if not self._initialized or not self._provider:
return
- self._provider._active_span_processor.force_flush(self.config["max_wait_time"]) # type: ignore
+
+ logger.debug("Attempting to flush span processors during shutdown...")
+ self._flush_span_processors()
# Shutdown provider
- if self._provider:
+ try:
+ self._provider.shutdown()
+ except Exception as e:
+ logger.warning(f"Error shutting down provider: {e}")
+
+ # Shutdown meter_provider
+ if hasattr(self, "_meter_provider") and self._meter_provider:
try:
- self._provider.shutdown()
+ self._meter_provider.shutdown()
except Exception as e:
- logger.warning(f"Error shutting down provider: {e}")
+ logger.warning(f"Error shutting down meter provider: {e}")
self._initialized = False
+ logger.debug("Tracing core shut down")
+
+ def _flush_span_processors(self) -> None:
+ """Helper to force flush all span processors."""
+ if not self._provider or not hasattr(self._provider, "force_flush"):
+ logger.debug("No provider or provider cannot force_flush.")
+ return
+
+ try:
+ self._provider.force_flush() # type: ignore
+ logger.debug("Provider force_flush completed.")
+ except Exception as e:
+ logger.warning(f"Failed to force flush provider's span processors: {e}", exc_info=True)
def get_tracer(self, name: str = "agentops") -> trace.Tracer:
"""
@@ -316,7 +357,7 @@ class TracingCore:
return trace.get_tracer(name)
@classmethod
- def initialize_from_config(cls, config, **kwargs):
+ def initialize_from_config(cls, config_obj: Any, **kwargs: Any) -> None:
"""
Initialize the tracing core from a configuration object.
@@ -328,9 +369,9 @@ class TracingCore:
# Extract tracing-specific configuration
# For TracingConfig, we can directly pass it to initialize
- if isinstance(config, dict):
+ if isinstance(config_obj, dict):
# If it's already a dict (TracingConfig), use it directly
- tracing_kwargs = config.copy()
+ tracing_kwargs = config_obj.copy()
else:
# For backward compatibility with old Config object
# Extract tracing-specific configuration from the Config object
@@ -338,15 +379,15 @@ class TracingCore:
tracing_kwargs = {
k: v
for k, v in {
- "exporter": getattr(config, "exporter", None),
- "processor": getattr(config, "processor", None),
- "exporter_endpoint": getattr(config, "exporter_endpoint", None),
- "max_queue_size": getattr(config, "max_queue_size", 512),
- "max_wait_time": getattr(config, "max_wait_time", 5000),
- "export_flush_interval": getattr(config, "export_flush_interval", 1000),
- "api_key": getattr(config, "api_key", None),
- "project_id": getattr(config, "project_id", None),
- "endpoint": getattr(config, "endpoint", None),
+ "exporter": getattr(config_obj, "exporter", None),
+ "processor": getattr(config_obj, "processor", None),
+ "exporter_endpoint": getattr(config_obj, "exporter_endpoint", None),
+ "max_queue_size": getattr(config_obj, "max_queue_size", 512),
+ "max_wait_time": getattr(config_obj, "max_wait_time", 5000),
+ "export_flush_interval": getattr(config_obj, "export_flush_interval", 1000),
+ "api_key": getattr(config_obj, "api_key", None),
+ "project_id": getattr(config_obj, "project_id", None),
+ "endpoint": getattr(config_obj, "endpoint", None),
}.items()
if v is not None
}
@@ -358,3 +399,151 @@ class TracingCore:
# Span types are registered in the constructor
# No need to register them here anymore
+
+ def start_trace(
+ self, trace_name: str = "session", tags: Optional[dict | list] = None, is_init_trace: bool = False
+ ) -> Optional[TraceContext]:
+ """
+ Starts a new trace (root span) and returns its context.
+
+ Args:
+ trace_name: Name for the trace (e.g., "session", "my_custom_trace").
+ tags: Optional tags to attach to the trace span.
+ is_init_trace: Internal flag to mark if this is the automatically started init trace.
+
+ Returns:
+ A TraceContext object containing the span and context token, or None if not initialized.
+ """
+ if not self.initialized:
+ logger.warning("TracingCore not initialized. Cannot start trace.")
+ return None
+
+ from agentops.sdk.decorators.utility import _make_span # Local import
+
+ attributes: dict = {}
+ if tags:
+ if isinstance(tags, list):
+ attributes[CoreAttributes.TAGS] = tags
+ elif isinstance(tags, dict):
+ attributes.update(tags) # Add dict tags directly
+ else:
+ logger.warning(f"Invalid tags format: {tags}. Must be list or dict.")
+
+ # _make_span creates and starts the span, and activates it in the current context
+ # It returns: span, context_object, context_token
+ span, _, context_token = _make_span(trace_name, span_kind=SpanKind.SESSION, attributes=attributes)
+ logger.debug(f"Trace '{trace_name}' started with span ID: {span.get_span_context().span_id}")
+
+ # Log the session replay URL for this new trace
+ try:
+ log_trace_url(span, title=trace_name)
+ except Exception as e:
+ logger.warning(f"Failed to log trace URL for '{trace_name}': {e}")
+
+ trace_context = TraceContext(span, token=context_token, is_init_trace=is_init_trace)
+
+ # Track the active trace
+ with self._traces_lock:
+ try:
+ trace_id = f"{span.get_span_context().trace_id:x}"
+ except (TypeError, ValueError):
+ # Handle case where span is mocked or trace_id is not a valid integer
+ trace_id = str(span.get_span_context().trace_id)
+ self._active_traces[trace_id] = trace_context
+ logger.debug(f"Added trace {trace_id} to active traces. Total active: {len(self._active_traces)}")
+
+ return trace_context
+
+ def end_trace(self, trace_context: Optional[TraceContext] = None, end_state: str = "Success") -> None:
+ """
+ Ends a trace (its root span) and finalizes it.
+ If no trace_context is provided, ends all active session spans.
+
+ Args:
+ trace_context: The TraceContext object returned by start_trace. If None, ends all active traces.
+ end_state: The final state of the trace (e.g., "Success", "Failure", "Error").
+ """
+ if not self.initialized:
+ logger.warning("TracingCore not initialized. Cannot end trace.")
+ return
+
+ # If no specific trace_context provided, end all active traces
+ if trace_context is None:
+ with self._traces_lock:
+ active_traces = list(self._active_traces.values())
+ logger.debug(f"Ending all {len(active_traces)} active traces with state: {end_state}")
+
+ for active_trace in active_traces:
+ self._end_single_trace(active_trace, end_state)
+ return
+
+ # End specific trace
+ self._end_single_trace(trace_context, end_state)
+
+ def _end_single_trace(self, trace_context: TraceContext, end_state: str) -> None:
+ """
+ Internal method to end a single trace.
+
+ Args:
+ trace_context: The TraceContext object to end.
+ end_state: The final state of the trace.
+ """
+ from agentops.sdk.decorators.utility import _finalize_span # Local import
+
+ if not trace_context or not trace_context.span:
+ logger.warning("Invalid TraceContext or span provided to end trace.")
+ return
+
+ span = trace_context.span
+ token = trace_context.token
+ try:
+ trace_id = f"{span.get_span_context().trace_id:x}"
+ except (TypeError, ValueError):
+ # Handle case where span is mocked or trace_id is not a valid integer
+ trace_id = str(span.get_span_context().trace_id)
+
+ logger.debug(f"Ending trace with span ID: {span.get_span_context().span_id}, end_state: {end_state}")
+
+ try:
+ span.set_attribute(SpanAttributes.AGENTOPS_SESSION_END_STATE, end_state)
+ _finalize_span(span, token=token)
+
+ # Remove from active traces
+ with self._traces_lock:
+ if trace_id in self._active_traces:
+ del self._active_traces[trace_id]
+ logger.debug(f"Removed trace {trace_id} from active traces. Remaining: {len(self._active_traces)}")
+
+ # For root spans (traces), we might want an immediate flush after they end.
+ self._flush_span_processors()
+
+ # Log the session replay URL again after the trace has ended
+ # The span object should still contain the necessary context (trace_id)
+ try:
+ # Use span.name as the title, which should reflect the original trace_name
+ log_trace_url(span, title=span.name)
+ except Exception as e:
+ logger.warning(f"Failed to log trace URL after ending trace '{span.name}': {e}")
+
+ except Exception as e:
+ logger.error(f"Error ending trace: {e}", exc_info=True)
+
+ def get_active_traces(self) -> Dict[str, TraceContext]:
+ """
+ Get a copy of currently active traces.
+
+ Returns:
+ Dictionary mapping trace IDs to TraceContext objects.
+ """
+ with self._traces_lock:
+ return self._active_traces.copy()
+
+ def get_active_trace_count(self) -> int:
+ """
+ Get the number of currently active traces.
+
+ Returns:
+ Number of active traces.
+ """
+ with self._traces_lock:
+ return len(self._active_traces)
diff --git a/agentops/sdk/decorators/__init__.py b/agentops/sdk/decorators/__init__.py
index c17b08aa..f775b45d 100644
--- a/agentops/sdk/decorators/__init__.py
+++ b/agentops/sdk/decorators/__init__.py
@@ -1,22 +1,40 @@
"""
Decorators for instrumenting code with AgentOps.
-
-This module provides a simplified set of decorators for instrumenting functions
-and methods with appropriate span kinds. Decorators can be used with or without parentheses.
+Provides @trace for creating trace-level spans (sessions) and other decorators for nested spans.
"""
+import functools
+from termcolor import colored
+
+from agentops.logging import logger
from agentops.sdk.decorators.factory import create_entity_decorator
from agentops.semconv.span_kinds import SpanKind
# Create decorators for specific entity types using the factory
agent = create_entity_decorator(SpanKind.AGENT)
task = create_entity_decorator(SpanKind.TASK)
-operation = create_entity_decorator(SpanKind.OPERATION)
+operation_decorator = create_entity_decorator(SpanKind.OPERATION)
workflow = create_entity_decorator(SpanKind.WORKFLOW)
+trace = create_entity_decorator(SpanKind.SESSION)
session = create_entity_decorator(SpanKind.SESSION)
tool = create_entity_decorator(SpanKind.TOOL)
operation = task
-__all__ = ["agent", "task", "workflow", "session", "operation", "tool"]
+# For backward compatibility: @session decorator calls @trace decorator
+def session(*args, **kwargs):
+ """@deprecated Use @agentops.trace instead. Wraps the @trace decorator for backward compatibility."""
+ logger.info(colored("@agentops.session decorator is deprecated. Please use @agentops.trace instead.", "yellow"))
+ # If called as @session or @session(...)
+ if not args or not callable(args[0]): # called with kwargs like @session(name=...)
+ return trace(*args, **kwargs)
+ else: # called as @session directly on a function
+ return trace(args[0], **kwargs) # args[0] is the wrapped function
+
+
+# Note: The original `operation = task` was potentially problematic if `operation` was meant to be distinct.
+# Using operation_decorator for clarity if a distinct OPERATION kind decorator is needed.
+# For now, keeping the alias as it was, assuming it was intentional for `operation` to be `task`.
+operation = task
-# Create decorators task, workflow, session, agent
+__all__ = ["agent", "task", "workflow", "trace", "session", "operation", "tool"]
diff --git a/agentops/sdk/decorators/factory.py b/agentops/sdk/decorators/factory.py
index 582005cc..cbf0e702 100644
--- a/agentops/sdk/decorators/factory.py
+++ b/agentops/sdk/decorators/factory.py
@@ -1,13 +1,15 @@
import inspect
import functools
import asyncio
+from typing import Any, Dict, Callable, Optional, Union
import wrapt # type: ignore
from agentops.logging import logger
-from agentops.sdk.core import TracingCore
-from agentops.semconv.span_attributes import SpanAttributes
+from agentops.sdk.core import TracingCore, TraceContext
+from agentops.semconv.span_kinds import SpanKind
+from agentops.semconv import SpanAttributes, CoreAttributes
from .utility import (
_create_as_current_span,
@@ -19,134 +21,200 @@ from .utility import (
)
-def create_entity_decorator(entity_kind: str):
+def create_entity_decorator(entity_kind: str) -> Callable[..., Any]:
"""
- Factory function that creates decorators for specific entity kinds.
-
- Args:
- entity_kind: The type of operation being performed (SpanKind.*)
-
- Returns:
- A decorator with optional arguments for name and version
+ Factory that creates decorators for instrumenting functions and classes.
+ Handles different entity kinds (e.g., SESSION, TASK) and function types (sync, async, generator).
"""
- def decorator(wrapped=None, *, name=None, version=None, cost=None):
- # Handle case where decorator is called with parameters
+ def decorator(
+ wrapped: Optional[Callable[..., Any]] = None,
+ *,
+ name: Optional[str] = None,
+ version: Optional[Any] = None,
+ tags: Optional[Union[list, dict]] = None,
+ cost=None,
+ ) -> Callable[..., Any]:
if wrapped is None:
- return functools.partial(decorator, name=name, version=version, cost=cost)
+ return functools.partial(decorator, name=name, version=version, tags=tags, cost=cost)
- # Handle class decoration
if inspect.isclass(wrapped):
- # Create a proxy class that wraps the original class
+ # Class decoration wraps __init__ and aenter/aexit for context management.
+ # For SpanKind.SESSION, this creates a span for __init__ or async context, not instance lifetime.
class WrappedClass(wrapped):
- def __init__(self, *args, **kwargs):
- operation_name = name or wrapped.__name__
+ def __init__(self, *args: Any, **kwargs: Any):
+ op_name = name or wrapped.__name__
+ self._agentops_span_context_manager = _create_as_current_span(op_name, entity_kind, version)
- self._agentops_span_context_manager = _create_as_current_span(operation_name, entity_kind, version)
self._agentops_active_span = self._agentops_span_context_manager.__enter__()
-
try:
_record_entity_input(self._agentops_active_span, args, kwargs)
except Exception as e:
- logger.warning(f"Failed to record entity input: {e}")
-
- # Call the original __init__
+ logger.warning(f"Failed to record entity input for class {op_name}: {e}")
super().__init__(*args, **kwargs)
- async def __aenter__(self):
- # If span is already created in __init__, just return self
+ async def __aenter__(self) -> "WrappedClass":
if hasattr(self, "_agentops_active_span") and self._agentops_active_span is not None:
return self
-
- # Otherwise create span (for backward compatibility)
- operation_name = name or wrapped.__name__
-
- self._agentops_span_context_manager = _create_as_current_span(operation_name, entity_kind, version)
+ op_name = name or wrapped.__name__
+ self._agentops_span_context_manager = _create_as_current_span(op_name, entity_kind, version)
self._agentops_active_span = self._agentops_span_context_manager.__enter__()
return self
- async def __aexit__(self, exc_type, exc_val, exc_tb):
+ async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
if hasattr(self, "_agentops_active_span") and hasattr(self, "_agentops_span_context_manager"):
try:
_record_entity_output(self._agentops_active_span, self)
except Exception as e:
- logger.warning(f"Failed to record entity output: {e}")
-
+ logger.warning(f"Failed to record entity output for class instance: {e}")
self._agentops_span_context_manager.__exit__(exc_type, exc_val, exc_tb)
- # Clear the span references after cleanup
self._agentops_span_context_manager = None
self._agentops_active_span = None
- # Preserve metadata of the original class
WrappedClass.__name__ = wrapped.__name__
WrappedClass.__qualname__ = wrapped.__qualname__
WrappedClass.__module__ = wrapped.__module__
WrappedClass.__doc__ = wrapped.__doc__
-
return WrappedClass
- # Create the actual decorator wrapper function for functions
@wrapt.decorator
- def wrapper(wrapped, instance, args, kwargs):
- # Skip instrumentation if tracer not initialized
- if not TracingCore.get_instance()._initialized:
- return wrapped(*args, **kwargs)
-
- # Use provided name or function name
- operation_name = name or wrapped.__name__
-
- # Handle different types of functions (sync, async, generators)
- is_async = asyncio.iscoroutinefunction(wrapped) or inspect.iscoroutinefunction(wrapped)
- is_generator = inspect.isgeneratorfunction(wrapped)
- is_async_generator = inspect.isasyncgenfunction(wrapped)
-
- # Handle generator functions
- if is_generator:
- span, ctx, token = _make_span(operation_name, entity_kind, version)
+ def wrapper(
+ wrapped_func: Callable[..., Any], instance: Optional[Any], args: tuple, kwargs: Dict[str, Any]
+ ) -> Any:
+ if not TracingCore.get_instance().initialized:
+ return wrapped_func(*args, **kwargs)
+
+ operation_name = name or wrapped_func.__name__
+ is_async = asyncio.iscoroutinefunction(wrapped_func)
+ is_generator = inspect.isgeneratorfunction(wrapped_func)
+ is_async_generator = inspect.isasyncgenfunction(wrapped_func)
+
+ if entity_kind == SpanKind.SESSION:
+ if is_generator or is_async_generator:
+ logger.warning(
+ f"@agentops.trace on generator '{operation_name}' creates a single span, not a full trace."
+ )
+ # Fallthrough to existing generator logic which creates a single span.
+ elif is_async:
+
+ async def _wrapped_session_async() -> Any:
+ trace_context: Optional[TraceContext] = None
+ try:
+ trace_context = TracingCore.get_instance().start_trace(trace_name=operation_name, tags=tags)
+ if not trace_context:
+ logger.error(
+ f"Failed to start trace for @trace '{operation_name}'. Executing without trace."
+ )
+ return await wrapped_func(*args, **kwargs)
+ try:
+ _record_entity_input(trace_context.span, args, kwargs)
+ except Exception as e:
+ logger.warning(f"Input recording failed for @trace '{operation_name}': {e}")
+ result = await wrapped_func(*args, **kwargs)
+ try:
+ _record_entity_output(trace_context.span, result)
+ except Exception as e:
+ logger.warning(f"Output recording failed for @trace '{operation_name}': {e}")
+ TracingCore.get_instance().end_trace(trace_context, "Success")
+ return result
+ except Exception:
+ if trace_context:
+ TracingCore.get_instance().end_trace(trace_context, "Failure")
+ raise
+ finally:
+ if trace_context and trace_context.span.is_recording():
+ logger.warning(
+ f"Trace for @trace '{operation_name}' not explicitly ended. Ending as 'Unknown'."
+ )
+ TracingCore.get_instance().end_trace(trace_context, "Unknown")
+
+ return _wrapped_session_async()
+ else: # Sync function for SpanKind.SESSION
+ trace_context: Optional[TraceContext] = None
+ try:
+ trace_context = TracingCore.get_instance().start_trace(trace_name=operation_name, tags=tags)
+ if not trace_context:
+ logger.error(
+ f"Failed to start trace for @trace '{operation_name}'. Executing without trace."
+ )
+ return wrapped_func(*args, **kwargs)
+ try:
+ _record_entity_input(trace_context.span, args, kwargs)
+ except Exception as e:
+ logger.warning(f"Input recording failed for @trace '{operation_name}': {e}")
+ result = wrapped_func(*args, **kwargs)
+ try:
+ _record_entity_output(trace_context.span, result)
+ except Exception as e:
+ logger.warning(f"Output recording failed for @trace '{operation_name}': {e}")
+ TracingCore.get_instance().end_trace(trace_context, "Success")
+ return result
+ except Exception:
+ if trace_context:
+ TracingCore.get_instance().end_trace(trace_context, "Failure")
+ raise
+ finally:
+ if trace_context and trace_context.span.is_recording():
+ logger.warning(
+ f"Trace for @trace '{operation_name}' not explicitly ended. Ending as 'Unknown'."
+ )
+ TracingCore.get_instance().end_trace(trace_context, "Unknown")
+
+ # Logic for non-SESSION kinds or generators under @trace (as per fallthrough)
+ elif is_generator:
+ span, _, token = _make_span(
+ operation_name,
+ entity_kind,
+ version=version,
+ attributes={CoreAttributes.TAGS: tags} if tags else None,
+ )
try:
_record_entity_input(span, args, kwargs)
# Set cost attribute if tool
if entity_kind == "tool" and cost is not None:
span.set_attribute(SpanAttributes.LLM_USAGE_TOOL_COST, cost)
except Exception as e:
- logger.warning(f"Failed to record entity input: {e}")
-
- result = wrapped(*args, **kwargs)
+ logger.warning(f"Input recording failed for '{operation_name}': {e}")
+ result = wrapped_func(*args, **kwargs)
return _process_sync_generator(span, result)
-
- # Handle async generator functions
elif is_async_generator:
- span, ctx, token = _make_span(operation_name, entity_kind, version)
+ span, _, token = _make_span(
+ operation_name,
+ entity_kind,
+ version=version,
+ attributes={CoreAttributes.TAGS: tags} if tags else None,
+ )
try:
_record_entity_input(span, args, kwargs)
# Set cost attribute if tool
if entity_kind == "tool" and cost is not None:
span.set_attribute(SpanAttributes.LLM_USAGE_TOOL_COST, cost)
except Exception as e:
- logger.warning(f"Failed to record entity input: {e}")
-
- result = wrapped(*args, **kwargs)
+ logger.warning(f"Input recording failed for '{operation_name}': {e}")
+ result = wrapped_func(*args, **kwargs)
return _process_async_generator(span, token, result)
-
- # Handle async functions
elif is_async:
- async def _wrapped_async():
- with _create_as_current_span(operation_name, entity_kind, version) as span:
+ async def _wrapped_async() -> Any:
+ with _create_as_current_span(
+ operation_name,
+ entity_kind,
+ version=version,
+ attributes={CoreAttributes.TAGS: tags} if tags else None,
+ ) as span:
try:
_record_entity_input(span, args, kwargs)
# Set cost attribute if tool
if entity_kind == "tool" and cost is not None:
span.set_attribute(SpanAttributes.LLM_USAGE_TOOL_COST, cost)
except Exception as e:
- logger.warning(f"Failed to record entity input: {e}")
-
+ logger.warning(f"Input recording failed for '{operation_name}': {e}")
try:
- result = await wrapped(*args, **kwargs)
+ result = await wrapped_func(*args, **kwargs)
try:
_record_entity_output(span, result)
except Exception as e:
- logger.warning(f"Failed to record entity output: {e}")
+ logger.warning(f"Output recording failed for '{operation_name}': {e}")
return result
except Exception as e:
logger.error(f"Error in async function execution: {e}")
@@ -154,32 +222,32 @@ def create_entity_decorator(entity_kind: str):
raise
return _wrapped_async()
-
- # Handle sync functions
- else:
- with _create_as_current_span(operation_name, entity_kind, version) as span:
+ else: # Sync function for non-SESSION kinds
+ with _create_as_current_span(
+ operation_name,
+ entity_kind,
+ version=version,
+ attributes={CoreAttributes.TAGS: tags} if tags else None,
+ ) as span:
try:
_record_entity_input(span, args, kwargs)
# Set cost attribute if tool
if entity_kind == "tool" and cost is not None:
span.set_attribute(SpanAttributes.LLM_USAGE_TOOL_COST, cost)
except Exception as e:
- logger.warning(f"Failed to record entity input: {e}")
-
+ logger.warning(f"Input recording failed for '{operation_name}': {e}")
try:
- result = wrapped(*args, **kwargs)
-
+ result = wrapped_func(*args, **kwargs)
try:
_record_entity_output(span, result)
except Exception as e:
- logger.warning(f"Failed to record entity output: {e}")
+ logger.warning(f"Output recording failed for '{operation_name}': {e}")
return result
except Exception as e:
logger.error(f"Error in sync function execution: {e}")
span.record_exception(e)
raise
- # Return the wrapper for functions, we already returned WrappedClass for classes
- return wrapper(wrapped) # type: ignore
+ return wrapper(wrapped)
return decorator
diff --git a/agentops/sdk/processors.py b/agentops/sdk/processors.py
index 9984ad9d..2f65a163 100644
--- a/agentops/sdk/processors.py
+++ b/agentops/sdk/processors.py
@@ -13,7 +13,6 @@ from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor
from opentelemetry.sdk.trace.export import SpanExporter
from agentops.logging import logger
-from agentops.helpers.dashboard import log_trace_url
from agentops.semconv.core import CoreAttributes
from agentops.logging import upload_logfile
@@ -108,7 +107,6 @@ class InternalSpanProcessor(SpanProcessor):
if not self._root_span_id:
self._root_span_id = span.context.span_id
logger.debug(f"[agentops.InternalSpanProcessor] Found root span: {span.name}")
- log_trace_url(span)
def on_end(self, span: ReadableSpan) -> None:
"""
@@ -123,7 +121,6 @@ class InternalSpanProcessor(SpanProcessor):
if self._root_span_id and (span.context.span_id is self._root_span_id):
logger.debug(f"[agentops.InternalSpanProcessor] Ending root span: {span.name}")
- log_trace_url(span)
try:
upload_logfile(span.context.trace_id)
except Exception as e:
diff --git a/agentops/semconv/span_attributes.py b/agentops/semconv/span_attributes.py
index 23d1d3d2..67320bff 100644
--- a/agentops/semconv/span_attributes.py
+++ b/agentops/semconv/span_attributes.py
@@ -92,3 +92,6 @@ class SpanAttributes:
# Operation attributes
OPERATION_NAME = "operation.name"
OPERATION_VERSION = "operation.version"
+
+ # Session/Trace attributes
+ AGENTOPS_SESSION_END_STATE = "agentops.session.end_state"
diff --git a/tests/integration/test_auth_flow.py b/tests/integration/test_auth_flow.py
index b6bd72e9..da8ccda8 100644
--- a/tests/integration/test_auth_flow.py
+++ b/tests/integration/test_auth_flow.py
@@ -4,6 +4,16 @@ from agentops.client import Client
from agentops.exceptions import InvalidApiKeyException, ApiServerException
[email protected](autouse=True)
+def reset_client():
+ """Reset the client singleton between tests"""
+ # Reset the singleton instance
+ Client._Client__instance = None
+ yield
+ # Clean up after test
+ Client._Client__instance = None
+
+
@pytest.mark.vcr()
def test_auth_flow(mock_api_key):
"""Test the authentication flow using the AgentOps client."""
diff --git a/tests/integration/test_session_concurrency.py b/tests/integration/test_session_concurrency.py
index 692e8512..9b17caeb 100644
--- a/tests/integration/test_session_concurrency.py
+++ b/tests/integration/test_session_concurrency.py
@@ -1,21 +1,20 @@
import pytest
import concurrent.futures
+from unittest.mock import patch, MagicMock
from fastapi import FastAPI
from fastapi.testclient import TestClient
import agentops
-from agentops.sdk.decorators import operation, session
+from agentops.client import Client
# Create FastAPI app
app = FastAPI()
-@operation
def process_request(x: str):
"""Process a request and return a response."""
return f"Processed: {x}"
-@session
@app.get("/completion")
def completion():
result = process_request("Hello")
@@ -31,9 +30,32 @@ def client():
@pytest.fixture(autouse=True)
def setup_agentops(mock_api_key):
"""Setup AgentOps with mock API key."""
- agentops.init(api_key=mock_api_key, auto_start_session=True)
- yield
- agentops.end_all_sessions()
+ # Reset client singleton
+ Client._Client__instance = None
+
+ # Mock the API client to avoid real authentication
+ with patch("agentops.client.client.ApiClient") as mock_api_client:
+ # Create mock API instance
+ mock_api = MagicMock()
+ mock_api.v3.fetch_auth_token.return_value = {"token": "mock_token", "project_id": "mock_project_id"}
+ mock_api_client.return_value = mock_api
+
+ # Mock TracingCore to avoid actual initialization
+ with patch("agentops.sdk.core.TracingCore.get_instance") as mock_tracing_core:
+ mock_instance = MagicMock()
+ mock_instance.initialized = True
+ mock_tracing_core.return_value = mock_instance
+
+ agentops.init(api_key=mock_api_key, auto_start_session=True)
+ yield
+
+ try:
+ agentops.end_all_sessions()
+ except:
+ pass
+
+ # Clean up client singleton
+ Client._Client__instance = None
def test_concurrent_api_requests(client):
@@ -58,13 +80,11 @@ def test_concurrent_api_requests(client):
def test_session_isolation():
- """Test that sessions are properly isolated."""
+ """Test that basic functions work in parallel (simplified concurrency test)."""
- @session
def session_a():
return process_request("A")
- @session
def session_b():
return process_request("B")
@@ -81,13 +101,11 @@ def test_session_isolation():
def test_session_error_handling():
- """Test error handling in concurrent sessions."""
+ """Test error handling in concurrent execution."""
- @session
def error_session():
raise ValueError("Test error")
- @session
def success_session():
return process_request("Success")
diff --git a/tests/unit/sdk/test_internal_span_processor.py b/tests/unit/sdk/test_internal_span_processor.py
index c67dcb2f..dc397d3a 100644
--- a/tests/unit/sdk/test_internal_span_processor.py
+++ b/tests/unit/sdk/test_internal_span_processor.py
@@ -1,162 +1,397 @@
"""
-Unit tests for the InternalSpanProcessor.
+Unit tests for URL logging functionality and InternalSpanProcessor.
"""
import unittest
-from unittest.mock import patch, MagicMock, call
+from unittest.mock import patch, MagicMock
from opentelemetry.sdk.trace import Span, ReadableSpan
from agentops.sdk.processors import InternalSpanProcessor
+from agentops.sdk.core import TracingCore, TraceContext
-class TestInternalSpanProcessor(unittest.TestCase):
- """Tests for InternalSpanProcessor."""
+class TestURLLogging(unittest.TestCase):
+ """Tests for URL logging functionality in TracingCore."""
def setUp(self):
- self.processor = InternalSpanProcessor()
+ self.tracing_core = TracingCore.get_instance()
+ # Mock the initialization to avoid actual setup
+ self.tracing_core._initialized = True
+ self.tracing_core._config = {"project_id": "test_project"}
+
+ @patch("agentops.sdk.core.log_trace_url")
+ @patch("agentops.sdk.decorators.utility._make_span")
+ def test_start_trace_logs_url(self, mock_make_span, mock_log_trace_url):
+ """Test that start_trace logs the trace URL."""
+ # Create a mock span
+ mock_span = MagicMock(spec=Span)
+ mock_context = MagicMock()
+ mock_token = MagicMock()
+ mock_span.get_span_context.return_value.span_id = 12345
+ mock_make_span.return_value = (mock_span, mock_context, mock_token)
+
+ # Call start_trace
+ trace_context = self.tracing_core.start_trace(trace_name="test_trace")
+
+ # Assert that log_trace_url was called with the span and title
+ mock_log_trace_url.assert_called_once_with(mock_span, title="test_trace")
+ self.assertIsInstance(trace_context, TraceContext)
+ self.assertEqual(trace_context.span, mock_span)
+
+ @patch("agentops.sdk.core.log_trace_url")
+ @patch("agentops.sdk.decorators.utility._finalize_span")
+ def test_end_trace_logs_url(self, mock_finalize_span, mock_log_trace_url):
+ """Test that end_trace logs the trace URL."""
+ # Create a mock trace context
+ mock_span = MagicMock(spec=Span)
+ mock_span.name = "test_trace"
+ mock_span.get_span_context.return_value.span_id = 12345
+ mock_token = MagicMock()
+ trace_context = TraceContext(mock_span, mock_token)
- # Reset the root span ID before each test
- self.processor._root_span_id = None
+ # Call end_trace
+ self.tracing_core.end_trace(trace_context, "Success")
+
+ # Assert that log_trace_url was called with the span and title
+ mock_log_trace_url.assert_called_once_with(mock_span, title="test_trace")
- @patch("agentops.sdk.processors.log_trace_url")
- def test_logs_url_for_first_span(self, mock_log_trace_url):
- """Test that the first span triggers a log_trace_url call."""
+ @patch("agentops.sdk.core.log_trace_url")
+ @patch("agentops.sdk.decorators.utility._make_span")
+ def test_start_trace_url_logging_failure_does_not_break_trace(self, mock_make_span, mock_log_trace_url):
+ """Test that URL logging failure doesn't break trace creation."""
# Create a mock span
mock_span = MagicMock(spec=Span)
mock_context = MagicMock()
- mock_context.trace_flags.sampled = True
- mock_context.span_id = 12345
- mock_span.context = mock_context
+ mock_token = MagicMock()
+ mock_span.get_span_context.return_value.span_id = 12345
+ mock_make_span.return_value = (mock_span, mock_context, mock_token)
+
+ # Make log_trace_url raise an exception
+ mock_log_trace_url.side_effect = Exception("URL logging failed")
+
+ # Call start_trace - should not raise exception
+ trace_context = self.tracing_core.start_trace(trace_name="test_trace")
+
+ # Assert that trace was still created successfully
+ self.assertIsInstance(trace_context, TraceContext)
+ self.assertEqual(trace_context.span, mock_span)
+ mock_log_trace_url.assert_called_once_with(mock_span, title="test_trace")
+
+ @patch("agentops.sdk.core.log_trace_url")
+ @patch("agentops.sdk.decorators.utility._finalize_span")
+ def test_end_trace_url_logging_failure_does_not_break_trace(self, mock_finalize_span, mock_log_trace_url):
+ """Test that URL logging failure doesn't break trace ending."""
+ # Create a mock trace context
+ mock_span = MagicMock(spec=Span)
+ mock_span.name = "test_trace"
+ mock_span.get_span_context.return_value.span_id = 12345
+ mock_token = MagicMock()
+ trace_context = TraceContext(mock_span, mock_token)
- # Call on_start
- self.processor.on_start(mock_span)
+ # Make log_trace_url raise an exception
+ mock_log_trace_url.side_effect = Exception("URL logging failed")
- # Assert that log_trace_url was called once
- mock_log_trace_url.assert_called_once_with(mock_span)
+ # Call end_trace - should not raise exception
+ self.tracing_core.end_trace(trace_context, "Success")
- @patch("agentops.sdk.processors.log_trace_url")
- def test_logs_url_only_for_root_span(self, mock_log_trace_url):
- """Test that log_trace_url is only called for the root span."""
- # First, create and start the root span
- mock_root_span = MagicMock(spec=Span)
- mock_root_context = MagicMock()
- mock_root_context.trace_flags.sampled = True
- mock_root_context.span_id = 12345
- mock_root_span.context = mock_root_context
+ # Assert that finalize_span was still called
+ mock_finalize_span.assert_called_once()
+ mock_log_trace_url.assert_called_once_with(mock_span, title="test_trace")
- self.processor.on_start(mock_root_span)
+ @patch("agentops.sdk.core.log_trace_url")
+ @patch("agentops.sdk.decorators.utility._make_span")
+ def test_start_trace_with_tags_logs_url(self, mock_make_span, mock_log_trace_url):
+ """Test that start_trace with tags logs the trace URL."""
+ # Create a mock span
+ mock_span = MagicMock(spec=Span)
+ mock_context = MagicMock()
+ mock_token = MagicMock()
+ mock_span.get_span_context.return_value.span_id = 12345
+ mock_make_span.return_value = (mock_span, mock_context, mock_token)
+
+ # Call start_trace with tags
+ trace_context = self.tracing_core.start_trace(trace_name="tagged_trace", tags=["test", "integration"])
+
+ # Assert that log_trace_url was called with the span and title
+ mock_log_trace_url.assert_called_once_with(mock_span, title="tagged_trace")
+ self.assertIsInstance(trace_context, TraceContext)
- # Reset the mock after root span creation
- mock_log_trace_url.reset_mock()
- # Now create and start a non-root span
- mock_non_root_span = MagicMock(spec=Span)
- mock_non_root_context = MagicMock()
- mock_non_root_context.trace_flags.sampled = True
- mock_non_root_context.span_id = 67890 # Different from root span ID
- mock_non_root_span.context = mock_non_root_context
+class TestSessionDecoratorURLLogging(unittest.TestCase):
+ """Tests for URL logging functionality in session decorators."""
+
+ def setUp(self):
+ self.tracing_core = TracingCore.get_instance()
+ # Mock the initialization to avoid actual setup
+ self.tracing_core._initialized = True
+ self.tracing_core._config = {"project_id": "test_project"}
+
+ @patch("agentops.sdk.core.log_trace_url")
+ @patch("agentops.sdk.decorators.utility._make_span")
+ @patch("agentops.sdk.decorators.utility._finalize_span")
+ def test_session_decorator_logs_url_on_start_and_end(self, mock_finalize_span, mock_make_span, mock_log_trace_url):
+ """Test that session decorator logs URLs on both start and end."""
+ from agentops.sdk.decorators import session
- self.processor.on_start(mock_non_root_span)
+ # Create a mock span
+ mock_span = MagicMock(spec=Span)
+ mock_span.name = "test_function"
+ mock_context = MagicMock()
+ mock_token = MagicMock()
+ mock_span.get_span_context.return_value.span_id = 12345
+ mock_make_span.return_value = (mock_span, mock_context, mock_token)
+
+ @session(name="test_session")
+ def test_function():
+ return "test_result"
+
+ # Call the decorated function
+ result = test_function()
+
+ # Assert that log_trace_url was called (start and end)
+ # Note: The actual number of calls may vary based on implementation details
+ self.assertGreaterEqual(mock_log_trace_url.call_count, 2)
+ # Verify that the calls include the expected session name
+ call_args_list = [
+ call_args[1]["title"] for call_args in mock_log_trace_url.call_args_list if "title" in call_args[1]
+ ]
+ self.assertIn("test_session", call_args_list)
+ self.assertEqual(result, "test_result")
+
+ @patch("agentops.sdk.core.log_trace_url")
+ @patch("agentops.sdk.decorators.utility._make_span")
+ @patch("agentops.sdk.decorators.utility._finalize_span")
+ def test_session_decorator_with_default_name_logs_url(self, mock_finalize_span, mock_make_span, mock_log_trace_url):
+ """Test that session decorator with default name logs URLs."""
+ from agentops.sdk.decorators import session
- # Assert that log_trace_url was not called for the non-root span
- mock_log_trace_url.assert_not_called()
+ # Create a mock span
+ mock_span = MagicMock(spec=Span)
+ mock_span.name = "my_function"
+ mock_context = MagicMock()
+ mock_token = MagicMock()
+ mock_span.get_span_context.return_value.span_id = 12345
+ mock_make_span.return_value = (mock_span, mock_context, mock_token)
+
+ @session
+ def my_function():
+ return "result"
+
+ # Call the decorated function
+ result = my_function()
+
+ # Assert that log_trace_url was called with function name as title
+ self.assertGreaterEqual(mock_log_trace_url.call_count, 2)
+ # Verify that the calls include the expected function name
+ call_args_list = [
+ call_args[1]["title"] for call_args in mock_log_trace_url.call_args_list if "title" in call_args[1]
+ ]
+ self.assertIn("my_function", call_args_list)
+ self.assertEqual(result, "result")
+
+ @patch("agentops.sdk.core.log_trace_url")
+ @patch("agentops.sdk.decorators.utility._make_span")
+ @patch("agentops.sdk.decorators.utility._finalize_span")
+ def test_session_decorator_handles_url_logging_failure(
+ self, mock_finalize_span, mock_make_span, mock_log_trace_url
+ ):
+ """Test that session decorator handles URL logging failures gracefully."""
+ from agentops.sdk.decorators import session
- # End the non-root span
- mock_non_root_readable = MagicMock(spec=ReadableSpan)
- mock_non_root_readable.context = mock_non_root_context
+ # Create a mock span
+ mock_span = MagicMock(spec=Span)
+ mock_span.name = "test_function"
+ mock_context = MagicMock()
+ mock_token = MagicMock()
+ mock_span.get_span_context.return_value.span_id = 12345
+ mock_make_span.return_value = (mock_span, mock_context, mock_token)
- self.processor.on_end(mock_non_root_readable)
+ # Make log_trace_url raise an exception
+ mock_log_trace_url.side_effect = Exception("URL logging failed")
- # Assert that log_trace_url was still not called
- mock_log_trace_url.assert_not_called()
+ @session(name="failing_session")
+ def test_function():
+ return "test_result"
- # Now end the root span
- mock_root_readable = MagicMock(spec=ReadableSpan)
- mock_root_readable.context = mock_root_context
+ # Call the decorated function - should not raise exception
+ result = test_function()
- self.processor.on_end(mock_root_readable)
+ # Assert that function still executed successfully
+ self.assertEqual(result, "test_result")
+ # Assert that log_trace_url was called (even though it failed)
+ self.assertGreaterEqual(mock_log_trace_url.call_count, 2)
- # Assert that log_trace_url was called for the root span end
- mock_log_trace_url.assert_called_once_with(mock_root_readable)
- @patch("agentops.sdk.processors.log_trace_url")
- def test_logs_url_exactly_twice_for_root_span(self, mock_log_trace_url):
- """Test that log_trace_url is called exactly twice for the root span (start and end)."""
- # Create a mock root span
- mock_root_span = MagicMock(spec=Span)
- mock_root_context = MagicMock()
- mock_root_context.trace_flags.sampled = True
- mock_root_context.span_id = 12345
- mock_root_span.context = mock_root_context
+class TestInternalSpanProcessor(unittest.TestCase):
+ """Tests for InternalSpanProcessor functionality."""
- # Start the root span
- self.processor.on_start(mock_root_span)
+ def setUp(self):
+ self.processor = InternalSpanProcessor()
+ # Reset the root span ID before each test
+ self.processor._root_span_id = None
- # Create a mock readable span for the end event
- mock_root_readable = MagicMock(spec=ReadableSpan)
- mock_root_readable.context = mock_root_context
+ def test_tracks_root_span_on_start(self):
+ """Test that the processor tracks the first span as root span."""
+ # Create a mock span
+ mock_span = MagicMock(spec=Span)
+ mock_context = MagicMock()
+ mock_context.trace_flags.sampled = True
+ mock_context.span_id = 12345
+ mock_span.context = mock_context
- # End the root span
- self.processor.on_end(mock_root_readable)
+ # Call on_start
+ self.processor.on_start(mock_span)
- # Assert that log_trace_url was called exactly twice
- self.assertEqual(mock_log_trace_url.call_count, 2)
- mock_log_trace_url.assert_has_calls([call(mock_root_span), call(mock_root_readable)])
+ # Assert that root span ID was set
+ self.assertEqual(self.processor._root_span_id, 12345)
- @patch("agentops.sdk.processors.log_trace_url")
- def test_ignores_unsampled_spans(self, mock_log_trace_url):
- """Test that unsampled spans are ignored."""
+ def test_ignores_unsampled_spans_on_start(self):
+ """Test that unsampled spans are ignored on start."""
# Create a mock unsampled span
mock_span = MagicMock(spec=Span)
mock_context = MagicMock()
mock_context.trace_flags.sampled = False
mock_span.context = mock_context
- # Start and end the span
+ # Call on_start
self.processor.on_start(mock_span)
- self.processor.on_end(mock_span)
- # Assert that log_trace_url was not called
- mock_log_trace_url.assert_not_called()
-
- # Assert that root_span_id was not set
+ # Assert that root span ID was not set
self.assertIsNone(self.processor._root_span_id)
- @patch("agentops.sdk.processors.log_trace_url")
- def test_shutdown_resets_root_span_id(self, mock_log_trace_url):
- """Test that shutdown resets the root span ID."""
- # First set a root span
- mock_root_span = MagicMock(spec=Span)
- mock_root_context = MagicMock()
- mock_root_context.trace_flags.sampled = True
- mock_root_context.span_id = 12345
- mock_root_span.context = mock_root_context
-
- self.processor.on_start(mock_root_span)
+ def test_only_tracks_first_span_as_root(self):
+ """Test that only the first span is tracked as root span."""
+ # First span
+ mock_span1 = MagicMock(spec=Span)
+ mock_context1 = MagicMock()
+ mock_context1.trace_flags.sampled = True
+ mock_context1.span_id = 12345
+ mock_span1.context = mock_context1
+
+ # Second span
+ mock_span2 = MagicMock(spec=Span)
+ mock_context2 = MagicMock()
+ mock_context2.trace_flags.sampled = True
+ mock_context2.span_id = 67890
+ mock_span2.context = mock_context2
+
+ # Start first span
+ self.processor.on_start(mock_span1)
+ self.assertEqual(self.processor._root_span_id, 12345)
- # Verify root span ID was set
+ # Start second span - should not change root span ID
+ self.processor.on_start(mock_span2)
self.assertEqual(self.processor._root_span_id, 12345)
- # Call shutdown
- self.processor.shutdown()
+ @patch("agentops.sdk.processors.upload_logfile")
+ def test_uploads_logfile_on_root_span_end(self, mock_upload_logfile):
+ """Test that logfile is uploaded when root span ends."""
+ # Set up root span
+ mock_span = MagicMock(spec=Span)
+ mock_context = MagicMock()
+ mock_context.trace_flags.sampled = True
+ mock_context.span_id = 12345
+ mock_context.trace_id = 98765
+ mock_span.context = mock_context
- # Verify root span ID was reset
- self.assertIsNone(self.processor._root_span_id)
+ # Start the span to set it as root
+ self.processor.on_start(mock_span)
- # Create another span after shutdown
+ # Create readable span for end event
+ mock_readable_span = MagicMock(spec=ReadableSpan)
+ mock_readable_span.context = mock_context
+
+ # End the span
+ self.processor.on_end(mock_readable_span)
+
+ # Assert that upload_logfile was called with trace_id
+ mock_upload_logfile.assert_called_once_with(98765)
+
+ @patch("agentops.sdk.processors.upload_logfile")
+ def test_does_not_upload_logfile_for_non_root_span(self, mock_upload_logfile):
+ """Test that logfile is not uploaded for non-root spans."""
+ # Set up root span
+ root_span = MagicMock(spec=Span)
+ root_context = MagicMock()
+ root_context.trace_flags.sampled = True
+ root_context.span_id = 12345
+ root_span.context = root_context
+
+ # Start root span
+ self.processor.on_start(root_span)
+
+ # Create non-root span
+ non_root_span = MagicMock(spec=ReadableSpan)
+ non_root_context = MagicMock()
+ non_root_context.trace_flags.sampled = True
+ non_root_context.span_id = 67890 # Different from root
+ non_root_span.context = non_root_context
+
+ # End non-root span
+ self.processor.on_end(non_root_span)
+
+ # Assert that upload_logfile was not called
+ mock_upload_logfile.assert_not_called()
+
+ @patch("agentops.sdk.processors.upload_logfile")
+ def test_handles_upload_logfile_error(self, mock_upload_logfile):
+ """Test that processor handles upload_logfile errors gracefully."""
+ # Set up root span
mock_span = MagicMock(spec=Span)
mock_context = MagicMock()
mock_context.trace_flags.sampled = True
- mock_context.span_id = 67890
+ mock_context.span_id = 12345
+ mock_context.trace_id = 98765
+ mock_span.context = mock_context
+
+ # Start the span to set it as root
+ self.processor.on_start(mock_span)
+
+ # Make upload_logfile raise an exception
+ mock_upload_logfile.side_effect = Exception("Upload failed")
+
+ # Create readable span for end event
+ mock_readable_span = MagicMock(spec=ReadableSpan)
+ mock_readable_span.context = mock_context
+
+ # End the span - should not raise exception
+ self.processor.on_end(mock_readable_span)
+
+ # Assert that upload_logfile was called
+ mock_upload_logfile.assert_called_once_with(98765)
+
+ def test_ignores_unsampled_spans_on_end(self):
+ """Test that unsampled spans are ignored on end."""
+ # Create a mock unsampled span
+ mock_span = MagicMock(spec=ReadableSpan)
+ mock_context = MagicMock()
+ mock_context.trace_flags.sampled = False
mock_span.context = mock_context
- # Reset mocks
- mock_log_trace_url.reset_mock()
+ # Call on_end - should not raise exception
+ self.processor.on_end(mock_span)
+
+ def test_shutdown_resets_root_span_id(self):
+ """Test that shutdown resets the root span ID."""
+ # Set up root span
+ mock_span = MagicMock(spec=Span)
+ mock_context = MagicMock()
+ mock_context.trace_flags.sampled = True
+ mock_context.span_id = 12345
+ mock_span.context = mock_context
- # Start the span, it should be treated as a new root span
+ # Start span to set root span ID
self.processor.on_start(mock_span)
+ self.assertEqual(self.processor._root_span_id, 12345)
+
+ # Call shutdown
+ self.processor.shutdown()
+
+ # Verify root span ID was reset
+ self.assertIsNone(self.processor._root_span_id)
- # Verify new root span was identified
- self.assertEqual(self.processor._root_span_id, 67890)
- mock_log_trace_url.assert_called_once_with(mock_span)
+ def test_force_flush_returns_true(self):
+ """Test that force_flush returns True."""
+ result = self.processor.force_flush()
+ self.assertTrue(result)
diff --git a/tests/unit/test_session.py b/tests/unit/test_session.py
index ad652520..bf20aa76 100644
--- a/tests/unit/test_session.py
+++ b/tests/unit/test_session.py
@@ -1,7 +1,7 @@
import pytest
from unittest.mock import patch, MagicMock
-# Tests for the session auto-start functionality
+# Tests for the new session management functionality
# These tests call the actual public API but mock the underlying implementation
# to avoid making real API calls or initializing the full telemetry pipeline
@@ -9,16 +9,13 @@ from unittest.mock import patch, MagicMock
@pytest.fixture(scope="function")
def mock_tracing_core():
"""Mock the TracingCore to avoid actual initialization"""
- with patch("agentops.sdk.core.TracingCore") as mock_core:
+ with patch("agentops.sdk.core.TracingCore.get_instance") as mock_get_instance:
# Create a mock instance that will be returned by get_instance()
mock_instance = MagicMock()
mock_instance.initialized = True
- mock_core.get_instance.return_value = mock_instance
+ mock_get_instance.return_value = mock_instance
- # Configure the initialize_from_config method
- mock_core.initialize_from_config = MagicMock()
-
- yield mock_core
+ yield mock_instance
@pytest.fixture(scope="function")
@@ -34,187 +31,398 @@ def mock_api_client():
@pytest.fixture(scope="function")
-def mock_span_creation():
- """Mock the span creation to avoid actual OTel span creation"""
- with patch("agentops.legacy._create_session_span") as mock_create:
- # Return a mock span, context, and token
- mock_span = MagicMock()
- mock_context = MagicMock()
- mock_token = MagicMock()
-
- mock_create.return_value = (mock_span, mock_context, mock_token)
+def mock_trace_context():
+ """Mock the TraceContext creation"""
+ mock_span = MagicMock()
+ mock_token = MagicMock()
+ mock_trace_context_instance = MagicMock()
+ mock_trace_context_instance.span = mock_span
+ mock_trace_context_instance.token = mock_token
+ mock_trace_context_instance.is_init_trace = False
- yield mock_create
+ return mock_trace_context_instance
-def test_explicit_init_then_explicit_session(mock_tracing_core, mock_api_client, mock_span_creation):
- """Test explicitly initializing followed by explicitly starting a session"""
[email protected](scope="function")
+def reset_client():
+ """Reset the AgentOps client before each test"""
import agentops
- from agentops.legacy import Session
- # Reset client for test
+ # Create a fresh client instance for each test
agentops._client = agentops.Client()
+ # Reset all client state
+ agentops._client._initialized = False
+ agentops._client._init_trace_context = None
+ agentops._client._legacy_session_for_init_trace = None
+ yield
+ # Clean up after test
+ try:
+ if hasattr(agentops._client, "_initialized"):
+ agentops._client._initialized = False
+ if hasattr(agentops._client, "_init_trace_context"):
+ agentops._client._init_trace_context = None
+ if hasattr(agentops._client, "_legacy_session_for_init_trace"):
+ agentops._client._legacy_session_for_init_trace = None
+ except:
+ pass
+
+
+def test_explicit_init_then_explicit_start_trace(mock_tracing_core, mock_api_client, mock_trace_context, reset_client):
+ """Test explicitly initializing followed by explicitly starting a trace"""
+ import agentops
# Explicitly initialize with auto_start_session=False
agentops.init(api_key="test-api-key", auto_start_session=False)
- # Verify that no session was auto-started
- mock_span_creation.assert_not_called()
+ # Verify that no auto-trace was started
+ mock_tracing_core.start_trace.assert_not_called()
- # Explicitly start a session
- session = agentops.start_session(tags=["test"])
+ # Mock the start_trace method to return our mock trace context
+ mock_tracing_core.start_trace.return_value = mock_trace_context
- # Verify the session was created
- mock_span_creation.assert_called_once()
- assert isinstance(session, Session)
+ # Explicitly start a trace
+ trace_context = agentops.start_trace(trace_name="test_trace", tags=["test"])
+
+ # Verify the trace was created
+ mock_tracing_core.start_trace.assert_called_once_with(trace_name="test_trace", tags=["test"])
+ assert trace_context == mock_trace_context
-def test_auto_start_session_true(mock_tracing_core, mock_api_client, mock_span_creation):
+def test_auto_start_session_true(mock_tracing_core, mock_api_client, mock_trace_context, reset_client):
"""Test initializing with auto_start_session=True"""
import agentops
from agentops.legacy import Session
- # Reset client for test
- agentops._client = agentops.Client()
+ # Mock the start_trace method to return our mock trace context
+ mock_tracing_core.start_trace.return_value = mock_trace_context
# Initialize with auto_start_session=True
- session = agentops.init(api_key="test-api-key", auto_start_session=True)
+ result = agentops.init(api_key="test-api-key", auto_start_session=True)
- # Verify a session was auto-started
- mock_span_creation.assert_called_once()
- assert isinstance(session, Session)
+ # Verify a trace was auto-started
+ mock_tracing_core.start_trace.assert_called_once()
+ # init() should return a Session object when auto-starting a session
+ assert isinstance(result, Session)
+ assert result.trace_context == mock_trace_context
-def test_auto_start_session_default(mock_tracing_core, mock_api_client, mock_span_creation):
- """Test initializing with default auto_start_session (should be True)"""
+def test_auto_start_session_default(mock_tracing_core, mock_api_client, mock_trace_context, reset_client):
+ """Test initializing with default auto_start_session behavior"""
import agentops
from agentops.legacy import Session
- # Reset client for test
- agentops._client = agentops.Client()
+ # Mock the start_trace method to return our mock trace context
+ mock_tracing_core.start_trace.return_value = mock_trace_context
- # Initialize with default auto_start_session
- session = agentops.init(api_key="test-api-key")
+ # Initialize without explicitly setting auto_start_session (defaults to True)
+ result = agentops.init(api_key="test-api-key")
- # Verify a session was auto-started by default
- mock_span_creation.assert_called_once()
- assert isinstance(session, Session)
+ # Verify that the client was initialized
+ assert agentops._client.initialized
+ # Since auto_start_session defaults to True, init() should return a Session object
+ assert isinstance(result, Session)
+ assert result.trace_context == mock_trace_context
-def test_auto_init_from_start_session(mock_tracing_core, mock_api_client, mock_span_creation):
- """Test auto-initializing from start_session() call"""
- # Set up the test with a clean environment
- # Rather than using complex patching, let's use a more direct approach
- # by checking that our fix is in the source code
+def test_start_trace_without_init():
+ """Test starting a trace without initialization triggers auto-init"""
+ import agentops
- # First, check that our fix in legacy/__init__.py is working correctly
- # by verifying the code contains auto_start_session=False in Client().init() call
- import agentops.legacy
+ # Reset client for test
+ agentops._client = agentops.Client()
- # For the second part of the test, we'll use patching to avoid the _finalize_span call
- with patch("agentops.sdk.decorators.utility._finalize_span") as mock_finalize_span:
- # Import the functions we need
- from agentops.legacy import Session, end_session
+ # Mock TracingCore to be uninitialized initially, then initialized after init
+ with patch("agentops.sdk.core.TracingCore.get_instance") as mock_get_instance:
+ mock_instance = MagicMock()
+ mock_instance.initialized = False
+ mock_get_instance.return_value = mock_instance
- # Create a fake session directly
- mock_span = MagicMock()
- mock_token = MagicMock()
- test_session = Session(mock_span, mock_token)
+ # Mock the init function to simulate successful initialization
+ with patch("agentops.init") as mock_init:
- # Set it as the current session
- agentops.legacy._current_session = test_session
+ def side_effect():
+ # After init is called, mark TracingCore as initialized
+ mock_instance.initialized = True
- # End the session
- end_session(test_session)
+ mock_init.side_effect = side_effect
+ mock_instance.start_trace.return_value = None
- # Verify _current_session was cleared
- assert (
- agentops.legacy._current_session is None
- ), "_current_session should be None after end_session with the same session"
+ # Try to start a trace without initialization
+ result = agentops.start_trace(trace_name="test_trace")
- # Verify _finalize_span was called with the right parameters
- mock_finalize_span.assert_called_once_with(mock_span, mock_token)
+ # Verify that init was called automatically
+ mock_init.assert_called_once()
+ # Should return None since start_trace returned None
+ assert result is None
-def test_multiple_start_session_calls(mock_tracing_core, mock_api_client, mock_span_creation):
- """Test calling start_session multiple times"""
+def test_end_trace(mock_tracing_core, mock_trace_context):
+ """Test ending a trace"""
import agentops
- from agentops.legacy import Session
- import warnings
- # Reset client for test
- agentops._client = agentops.Client()
+ # End the trace
+ agentops.end_trace(mock_trace_context, end_state="Success")
+
+ # Verify end_trace was called on TracingCore
+ mock_tracing_core.end_trace.assert_called_once_with(trace_context=mock_trace_context, end_state="Success")
+
- # Initialize
+def test_session_decorator_creates_trace(mock_tracing_core, mock_api_client, mock_trace_context, reset_client):
+ """Test that the @session decorator creates a trace-level span"""
+ import agentops
+ from agentops.sdk.decorators import session
+
+ # Initialize AgentOps
agentops.init(api_key="test-api-key", auto_start_session=False)
- # Start the first session
- session1 = agentops.start_session(tags=["test1"])
- assert isinstance(session1, Session)
- assert mock_span_creation.call_count == 1
+ # Mock the start_trace and end_trace methods
+ mock_tracing_core.start_trace.return_value = mock_trace_context
+
+ @session(name="test_session", tags=["decorator_test"])
+ def test_function():
+ return "test_result"
- # Capture warnings to check if the multiple session warning is issued
- with warnings.catch_warnings(record=True):
- # Start another session without ending the first
- session2 = agentops.start_session(tags=["test2"])
+ # Execute the decorated function
+ result = test_function()
- # Verify another session was created and warning was issued
- assert isinstance(session2, Session)
- assert mock_span_creation.call_count == 2
+ # Verify the function executed successfully
+ assert result == "test_result"
- # Note: This test expects a warning to be issued - implementation needed
- # assert len(w) > 0 # Uncomment after implementing warning
+ # Verify that start_trace and end_trace were called
+ # Note: The decorator might call start_trace multiple times due to initialization
+ assert mock_tracing_core.start_trace.call_count >= 1
+ assert mock_tracing_core.end_trace.call_count >= 1
-def test_end_session_state_handling(mock_tracing_core, mock_api_client, mock_span_creation):
- """Test ending a session clears state properly"""
+def test_session_decorator_with_exception(mock_tracing_core, mock_api_client, mock_trace_context, reset_client):
+ """Test that the @session decorator handles exceptions properly"""
import agentops
- import agentops.legacy
+ from agentops.sdk.decorators import session
- # Reset client for test
- agentops._client = agentops.Client()
+ # Initialize AgentOps
+ agentops.init(api_key="test-api-key", auto_start_session=False)
+
+ # Mock the start_trace method
+ mock_tracing_core.start_trace.return_value = mock_trace_context
+
+ @session(name="failing_session")
+ def failing_function():
+ raise ValueError("Test exception")
+
+ # Execute the decorated function and expect an exception
+ with pytest.raises(ValueError, match="Test exception"):
+ failing_function()
+
+ # Verify that start_trace was called
+ assert mock_tracing_core.start_trace.call_count >= 1
+ # Verify that end_trace was called
+ assert mock_tracing_core.end_trace.call_count >= 1
- # Initialize with no auto-start session
+
+def test_legacy_start_session_compatibility(mock_tracing_core, mock_api_client, mock_trace_context, reset_client):
+ """Test that legacy start_session still works and calls TracingCore.start_trace"""
+ import agentops
+ from agentops.legacy import Session
+
+ # Initialize AgentOps
agentops.init(api_key="test-api-key", auto_start_session=False)
- # Directly set _current_session to None to start from a clean state
- # This is necessary because the current implementation may have global state issues
- agentops.legacy._current_session = None
+ # Mock the start_trace method
+ mock_tracing_core.start_trace.return_value = mock_trace_context
- # Start a session
- session = agentops.start_session(tags=["test"])
+ # Start a legacy session
+ session = agentops.start_session(tags=["legacy_test"])
- # CHECK FOR BUG: _current_session should be properly set
- assert agentops.legacy._current_session is not None, "_current_session should be set by start_session"
- assert agentops.legacy._current_session is session, "_current_session should reference the session created"
+ # Verify the session was created
+ assert isinstance(session, Session)
+ assert session.trace_context == mock_trace_context
- # Mock the cleanup in _finalize_span since we're not actually creating real spans
- with patch("agentops.sdk.decorators.utility._finalize_span") as mock_finalize:
- # End the session
- agentops.end_session(session)
+ # Verify that TracingCore.start_trace was called
+ # Note: May be called multiple times due to initialization
+ assert mock_tracing_core.start_trace.call_count >= 1
- # Verify _finalize_span was called
- mock_finalize.assert_called_once()
- # CHECK FOR BUG: _current_session should be cleared after end_session
- assert agentops.legacy._current_session is None, "_current_session should be None after end_session"
+def test_legacy_end_session_compatibility(mock_tracing_core, mock_api_client, mock_trace_context, reset_client):
+ """Test that legacy end_session still works and calls TracingCore.end_trace"""
+ import agentops
+ from agentops.legacy import Session
+
+ # Initialize AgentOps
+ agentops.init(api_key="test-api-key", auto_start_session=False)
+
+ # Create a legacy session object
+ session = Session(mock_trace_context)
+ # End the session
+ agentops.end_session(session)
-def test_no_double_init(mock_tracing_core, mock_api_client):
+ # Verify that TracingCore.end_trace was called
+ mock_tracing_core.end_trace.assert_called_once_with(mock_trace_context, end_state="Success")
+
+
+def test_no_double_init(mock_tracing_core, mock_api_client, reset_client):
"""Test that calling init multiple times doesn't reinitialize"""
import agentops
- # Reset client for test
- agentops._client = agentops.Client()
-
# Initialize once
agentops.init(api_key="test-api-key", auto_start_session=False)
# Track the call count
call_count = mock_api_client.call_count
- # Call init again
+ # Call init again with the same API key
agentops.init(api_key="test-api-key", auto_start_session=False)
# Verify that API client wasn't constructed again
assert mock_api_client.call_count == call_count
+
+
+def test_client_initialization_behavior(mock_tracing_core, mock_api_client, mock_trace_context, reset_client):
+ """Test basic client initialization behavior"""
+ import agentops
+
+ # Mock the start_trace method
+ mock_tracing_core.start_trace.return_value = mock_trace_context
+
+ # Test that initialization works
+ agentops.init(api_key="test-api-key", auto_start_session=False)
+
+ # Verify that the client was initialized
+ assert agentops._client.initialized
+
+ # The API client might not be called if already mocked at a higher level
+ # Just verify that the initialization completed successfully
+
+ # Test that calling init again doesn't cause issues
+ agentops.init(api_key="test-api-key", auto_start_session=False)
+
+ # Should still be initialized
+ assert agentops._client.initialized
+
+
+def test_multiple_concurrent_traces(mock_tracing_core, mock_api_client, reset_client):
+ """Test that multiple traces can be started concurrently"""
+ import agentops
+
+ # Initialize AgentOps
+ agentops.init(api_key="test-api-key", auto_start_session=False)
+
+ # Create mock trace contexts for different traces
+ mock_trace_context_1 = MagicMock()
+ mock_trace_context_2 = MagicMock()
+
+ # Mock start_trace to return different contexts
+ mock_tracing_core.start_trace.side_effect = [
+ mock_trace_context_1,
+ mock_trace_context_2,
+ ]
+
+ # Start multiple traces
+ trace1 = agentops.start_trace(trace_name="trace1", tags=["test1"])
+ trace2 = agentops.start_trace(trace_name="trace2", tags=["test2"])
+
+ # Verify both traces were created
+ assert trace1 == mock_trace_context_1
+ assert trace2 == mock_trace_context_2
+
+ # Verify start_trace was called twice
+ assert mock_tracing_core.start_trace.call_count == 2
+
+
+def test_trace_context_properties(mock_trace_context):
+ """Test that TraceContext properties work correctly"""
+ from agentops.legacy import Session
+
+ # Create a legacy session with the mock trace context
+ session = Session(mock_trace_context)
+
+ # Test that properties are accessible
+ assert session.span == mock_trace_context.span
+ assert session.token == mock_trace_context.token
+ assert session.trace_context == mock_trace_context
+
+
+def test_session_decorator_async_function(mock_tracing_core, mock_api_client, mock_trace_context, reset_client):
+ """Test that the @session decorator works with async functions"""
+ import agentops
+ import asyncio
+ from agentops.sdk.decorators import session
+
+ # Initialize AgentOps
+ agentops.init(api_key="test-api-key", auto_start_session=False)
+
+ # Mock the start_trace method
+ mock_tracing_core.start_trace.return_value = mock_trace_context
+
+ @session(name="async_test_session")
+ async def async_test_function():
+ await asyncio.sleep(0.01) # Simulate async work
+ return "async_result"
+
+ # Execute the decorated async function
+ result = asyncio.run(async_test_function())
+
+ # Verify the function executed successfully
+ assert result == "async_result"
+
+ # Verify that start_trace and end_trace were called
+ assert mock_tracing_core.start_trace.call_count >= 1
+ assert mock_tracing_core.end_trace.call_count >= 1
+
+
+def test_trace_context_creation():
+ """Test that TraceContext can be created with proper attributes"""
+ from agentops.sdk.core import TraceContext
+
+ mock_span = MagicMock()
+ mock_token = MagicMock()
+
+ # Test creating a TraceContext
+ trace_context = TraceContext(span=mock_span, token=mock_token, is_init_trace=False)
+
+ assert trace_context.span == mock_span
+ assert trace_context.token == mock_token
+ assert trace_context.is_init_trace == False
+
+
+def test_session_management_integration():
+ """Test the integration between new and legacy session management"""
+ import agentops
+
+ # Reset client for test
+ agentops._client = agentops.Client()
+
+ # Test that we can use both new and legacy APIs together
+ with patch("agentops.sdk.core.TracingCore.get_instance") as mock_get_instance:
+ mock_instance = MagicMock()
+ mock_instance.initialized = True
+ mock_get_instance.return_value = mock_instance
+
+ # Mock API client
+ with patch("agentops.client.api.ApiClient") as mock_api:
+ mock_v3 = MagicMock()
+ mock_v3.fetch_auth_token.return_value = {"token": "mock-jwt-token", "project_id": "mock-project-id"}
+ mock_api.return_value.v3 = mock_v3
+
+ # Initialize AgentOps
+ agentops.init(api_key="test-api-key", auto_start_session=False)
+
+ # Create mock trace context
+ mock_trace_context = MagicMock()
+ mock_instance.start_trace.return_value = mock_trace_context
+
+ # Test new API
+ trace_context = agentops.start_trace(trace_name="new_api_trace")
+ assert trace_context == mock_trace_context
+
+ # Test legacy API
+ session = agentops.start_session(tags=["legacy"])
+ assert session.trace_context == mock_trace_context
+
+ # Test ending both
+ agentops.end_trace(trace_context)
+ agentops.end_session(session)
+
+ # Verify calls were made
+ assert mock_instance.start_trace.call_count >= 2
+ assert mock_instance.end_trace.call_count >= 2