Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
Lorenze/emphemeral tracing (#3323)
Lorenze Jay04a03d332f00
diff --git a/src/crewai/cli/authentication/token.py b/src/crewai/cli/authentication/token.pyindex 46ff75e89..e59a13b38 100644--- a/src/crewai/cli/authentication/token.py+++ b/src/crewai/cli/authentication/token.py@@ -1,9 +1,13 @@from .utils import TokenManager+class AuthError(Exception):+ pass++def get_auth_token() -> str:"""Get the authentication token."""access_token = TokenManager().get_token()if not access_token:- raise Exception("No token found, make sure you are logged in")+ raise AuthError("No token found, make sure you are logged in")return access_tokendiff --git a/src/crewai/cli/plus_api.py b/src/crewai/cli/plus_api.pyindex 26f0953f0..d86858c4a 100644--- a/src/crewai/cli/plus_api.py+++ b/src/crewai/cli/plus_api.py@@ -18,6 +18,7 @@ class PlusAPI:CREWS_RESOURCE = "/crewai_plus/api/v1/crews"AGENTS_RESOURCE = "/crewai_plus/api/v1/agents"TRACING_RESOURCE = "/crewai_plus/api/v1/tracing"+ EPHEMERAL_TRACING_RESOURCE = "/crewai_plus/api/v1/tracing/ephemeral"def __init__(self, api_key: str) -> None:self.api_key = api_key@@ -124,6 +125,11 @@ class PlusAPI:"POST", f"{self.TRACING_RESOURCE}/batches", json=payload)+ def initialize_ephemeral_trace_batch(self, payload) -> requests.Response:+ return self._make_request(+ "POST", f"{self.EPHEMERAL_TRACING_RESOURCE}/batches", json=payload+ )+def send_trace_events(self, trace_batch_id: str, payload) -> requests.Response:return self._make_request("POST",@@ -131,9 +137,27 @@ class PlusAPI:json=payload,)+ def send_ephemeral_trace_events(+ self, trace_batch_id: str, payload+ ) -> requests.Response:+ return self._make_request(+ "POST",+ f"{self.EPHEMERAL_TRACING_RESOURCE}/batches/{trace_batch_id}/events",+ json=payload,+ )+def finalize_trace_batch(self, trace_batch_id: str, payload) -> requests.Response:return self._make_request("PATCH",f"{self.TRACING_RESOURCE}/batches/{trace_batch_id}/finalize",json=payload,)++ def finalize_ephemeral_trace_batch(+ self, trace_batch_id: str, payload+ ) -> requests.Response:+ return self._make_request(+ "PATCH",+ f"{self.EPHEMERAL_TRACING_RESOURCE}/batches/{trace_batch_id}/finalize",+ json=payload,+ )diff --git a/src/crewai/crew.py b/src/crewai/crew.pyindex 5e654463c..a14c8f278 100644--- a/src/crewai/crew.py+++ b/src/crewai/crew.py@@ -77,7 +77,10 @@ from crewai.utilities.events.listeners.tracing.trace_listener import ()-from crewai.utilities.events.listeners.tracing.utils import is_tracing_enabled+from crewai.utilities.events.listeners.tracing.utils import (+ is_tracing_enabled,+ on_first_execution_tracing_confirmation,+)from crewai.utilities.formatter import (aggregate_raw_outputs_from_task_outputs,aggregate_raw_outputs_from_tasks,@@ -283,8 +286,11 @@ class Crew(FlowTrackable, BaseModel):self._cache_handler = CacheHandler()event_listener = EventListener()+ if on_first_execution_tracing_confirmation():+ self.tracing = True+if is_tracing_enabled() or self.tracing:- trace_listener = TraceCollectionListener(tracing=self.tracing)+ trace_listener = TraceCollectionListener()trace_listener.setup_listeners(crewai_event_bus)event_listener.verbose = self.verboseevent_listener.formatter.verbose = self.verbosediff --git a/src/crewai/flow/flow.py b/src/crewai/flow/flow.pyindex 111cae7d6..35a83ea1f 100644--- a/src/crewai/flow/flow.py+++ b/src/crewai/flow/flow.py@@ -38,7 +38,10 @@ from crewai.utilities.events.flow_events import (from crewai.utilities.events.listeners.tracing.trace_listener import (TraceCollectionListener,)-from crewai.utilities.events.listeners.tracing.utils import is_tracing_enabled+from crewai.utilities.events.listeners.tracing.utils import (+ is_tracing_enabled,+ on_first_execution_tracing_confirmation,+)from crewai.utilities.printer import Printerlogger = logging.getLogger(__name__)@@ -476,8 +479,12 @@ class Flow(Generic[T], metaclass=FlowMeta):# Initialize state with initial valuesself._state = self._create_initial_state()self.tracing = tracing- if is_tracing_enabled() or tracing:- trace_listener = TraceCollectionListener(tracing=tracing)+ if (+ on_first_execution_tracing_confirmation()+ or is_tracing_enabled()+ or self.tracing+ ):+ trace_listener = TraceCollectionListener()trace_listener.setup_listeners(crewai_event_bus)# Apply any additional kwargsif kwargs:diff --git a/src/crewai/utilities/events/listeners/tracing/trace_batch_manager.py b/src/crewai/utilities/events/listeners/tracing/trace_batch_manager.pyindex 4a1f06621..c06d51af7 100644--- a/src/crewai/utilities/events/listeners/tracing/trace_batch_manager.py+++ b/src/crewai/utilities/events/listeners/tracing/trace_batch_manager.py@@ -4,7 +4,7 @@ from typing import Dict, List, Any, Optionalfrom dataclasses import dataclass, fieldfrom crewai.utilities.constants import CREWAI_BASE_URL-from crewai.cli.authentication.token import get_auth_token+from crewai.cli.authentication.token import AuthError, get_auth_tokenfrom crewai.cli.version import get_crewai_versionfrom crewai.cli.plus_api import PlusAPI@@ -41,14 +41,21 @@ class TraceBatchManager:"""Single responsibility: Manage batches and event buffering"""def __init__(self):- self.plus_api = PlusAPI(api_key=get_auth_token())+ try:+ self.plus_api = PlusAPI(api_key=get_auth_token())+ except AuthError:+ self.plus_api = PlusAPI(api_key="")+self.trace_batch_id: Optional[str] = None # Backend IDself.current_batch: Optional[TraceBatch] = Noneself.event_buffer: List[TraceEvent] = []self.execution_start_times: Dict[str, datetime] = {}def initialize_batch(- self, user_context: Dict[str, str], execution_metadata: Dict[str, Any]+ self,+ user_context: Dict[str, str],+ execution_metadata: Dict[str, Any],+ use_ephemeral: bool = False,) -> TraceBatch:"""Initialize a new trace batch"""self.current_batch = TraceBatch(@@ -57,13 +64,15 @@ class TraceBatchManager:self.event_buffer.clear()self.record_start_time("execution")-- self._initialize_backend_batch(user_context, execution_metadata)+ self._initialize_backend_batch(user_context, execution_metadata, use_ephemeral)return self.current_batchdef _initialize_backend_batch(- self, user_context: Dict[str, str], execution_metadata: Dict[str, Any]+ self,+ user_context: Dict[str, str],+ execution_metadata: Dict[str, Any],+ use_ephemeral: bool = False,):"""Send batch initialization to backend"""@@ -74,6 +83,7 @@ class TraceBatchManager:payload = {"trace_id": self.current_batch.batch_id,"execution_type": execution_metadata.get("execution_type", "crew"),+ "user_identifier": execution_metadata.get("user_context", None),"execution_context": {"crew_fingerprint": execution_metadata.get("crew_fingerprint"),"crew_name": execution_metadata.get("crew_name", None),@@ -91,12 +101,22 @@ class TraceBatchManager:"execution_started_at": datetime.now(timezone.utc).isoformat(),},}+ if use_ephemeral:+ payload["ephemeral_trace_id"] = self.current_batch.batch_id- response = self.plus_api.initialize_trace_batch(payload)+ response = (+ self.plus_api.initialize_ephemeral_trace_batch(payload)+ if use_ephemeral+ else self.plus_api.initialize_trace_batch(payload)+ )if response.status_code == 201 or response.status_code == 200:response_data = response.json()- self.trace_batch_id = response_data["trace_id"]+ self.trace_batch_id = (+ response_data["trace_id"]+ if not use_ephemeral+ else response_data["ephemeral_trace_id"]+ )console = Console()panel = Panel(f"✅ Trace batch initialized with session ID: {self.trace_batch_id}",@@ -116,7 +136,7 @@ class TraceBatchManager:"""Add event to buffer"""self.event_buffer.append(trace_event)- def _send_events_to_backend(self):+ def _send_events_to_backend(self, ephemeral: bool = True):"""Send buffered events to backend"""if not self.plus_api or not self.trace_batch_id or not self.event_buffer:return@@ -134,7 +154,11 @@ class TraceBatchManager:if not self.trace_batch_id:raise Exception("❌ Trace batch ID not found")- response = self.plus_api.send_trace_events(self.trace_batch_id, payload)+ response = (+ self.plus_api.send_ephemeral_trace_events(self.trace_batch_id, payload)+ if ephemeral+ else self.plus_api.send_trace_events(self.trace_batch_id, payload)+ )if response.status_code == 200 or response.status_code == 201:self.event_buffer.clear()@@ -146,15 +170,15 @@ class TraceBatchManager:except Exception as e:logger.error(f"❌ Error sending events to backend: {str(e)}")- def finalize_batch(self) -> Optional[TraceBatch]:+ def finalize_batch(self, ephemeral: bool = True) -> Optional[TraceBatch]:"""Finalize batch and return it for sending"""if not self.current_batch:return Noneif self.event_buffer:- self._send_events_to_backend()+ self._send_events_to_backend(ephemeral)- self._finalize_backend_batch()+ self._finalize_backend_batch(ephemeral)self.current_batch.events = self.event_buffer.copy()@@ -168,7 +192,7 @@ class TraceBatchManager:return finalized_batch- def _finalize_backend_batch(self):+ def _finalize_backend_batch(self, ephemeral: bool = True):"""Send batch finalization to backend"""if not self.plus_api or not self.trace_batch_id:return@@ -182,12 +206,24 @@ class TraceBatchManager:"final_event_count": total_events,}- response = self.plus_api.finalize_trace_batch(self.trace_batch_id, payload)+ response = (+ self.plus_api.finalize_ephemeral_trace_batch(+ self.trace_batch_id, payload+ )+ if ephemeral+ else self.plus_api.finalize_trace_batch(self.trace_batch_id, payload)+ )if response.status_code == 200:+ access_code = response.json().get("access_code", None)console = Console()+ return_link = (+ f"{CREWAI_BASE_URL}/crewai_plus/trace_batches/{self.trace_batch_id}"+ if not ephemeral and access_code+ else f"{CREWAI_BASE_URL}/crewai_plus/ephemeral_trace_batches/{self.trace_batch_id}?access_code={access_code}"+ )panel = Panel(- f"✅ Trace batch finalized with session ID: {self.trace_batch_id}. View here: {CREWAI_BASE_URL}/crewai_plus/trace_batches/{self.trace_batch_id}",+ f"✅ Trace batch finalized with session ID: {self.trace_batch_id}. View here: {return_link} {f', Access Code: {access_code}' if access_code else ''}",title="Trace Batch Finalization",border_style="green",)diff --git a/src/crewai/utilities/events/listeners/tracing/trace_listener.py b/src/crewai/utilities/events/listeners/tracing/trace_listener.pyindex e8d68ccae..eaa993c8f 100644--- a/src/crewai/utilities/events/listeners/tracing/trace_listener.py+++ b/src/crewai/utilities/events/listeners/tracing/trace_listener.py@@ -13,7 +13,6 @@ from crewai.utilities.events.agent_events import (AgentExecutionErrorEvent,)from crewai.utilities.events.listeners.tracing.types import TraceEvent-from crewai.utilities.events.listeners.tracing.utils import is_tracing_enabledfrom crewai.utilities.events.reasoning_events import (AgentReasoningStartedEvent,AgentReasoningCompletedEvent,@@ -67,7 +66,7 @@ from crewai.utilities.events.memory_events import (MemorySaveFailedEvent,)-from crewai.cli.authentication.token import get_auth_token+from crewai.cli.authentication.token import AuthError, get_auth_tokenfrom crewai.cli.version import get_crewai_version@@ -76,13 +75,12 @@ class TraceCollectionListener(BaseEventListener):Trace collection listener that orchestrates trace collection"""- trace_enabled: Optional[bool] = Falsecomplex_events = ["task_started", "llm_call_started", "llm_call_completed"]_instance = None_initialized = False- def __new__(cls, batch_manager=None, tracing: Optional[bool] = False):+ def __new__(cls, batch_manager=None):if cls._instance is None:cls._instance = super().__new__(cls)return cls._instance@@ -90,25 +88,22 @@ class TraceCollectionListener(BaseEventListener):def __init__(self,batch_manager: Optional[TraceBatchManager] = None,- tracing: Optional[bool] = False,):if self._initialized:returnsuper().__init__()self.batch_manager = batch_manager or TraceBatchManager()- self.tracing = tracing or False- self.trace_enabled = self._check_trace_enabled()self._initialized = True- def _check_trace_enabled(self) -> bool:+ def _check_authenticated(self) -> bool:"""Check if tracing should be enabled"""- auth_token = get_auth_token()- if not auth_token:+ try:+ res = bool(get_auth_token())+ return res+ except AuthError:return False- return is_tracing_enabled() or self.tracing-def _get_user_context(self) -> Dict[str, str]:"""Extract user context for tracing"""return {@@ -120,8 +115,6 @@ class TraceCollectionListener(BaseEventListener):def setup_listeners(self, crewai_event_bus):"""Setup event listeners - delegates to specific handlers"""- if not self.trace_enabled:- returnself._register_flow_event_handlers(crewai_event_bus)self._register_context_event_handlers(crewai_event_bus)@@ -167,13 +160,13 @@ class TraceCollectionListener(BaseEventListener):@event_bus.on(CrewKickoffStartedEvent)def on_crew_started(source, event):if not self.batch_manager.is_batch_initialized():- self._initialize_batch(source, event)+ self._initialize_crew_batch(source, event)self._handle_trace_event("crew_kickoff_started", source, event)@event_bus.on(CrewKickoffCompletedEvent)def on_crew_completed(source, event):self._handle_trace_event("crew_kickoff_completed", source, event)- self.batch_manager.finalize_batch()+ self.batch_manager.finalize_batch(ephemeral=True)@event_bus.on(CrewKickoffFailedEvent)def on_crew_failed(source, event):@@ -287,7 +280,7 @@ class TraceCollectionListener(BaseEventListener):def on_agent_reasoning_failed(source, event):self._handle_action_event("agent_reasoning_failed", source, event)- def _initialize_batch(self, source: Any, event: Any):+ def _initialize_crew_batch(self, source: Any, event: Any):"""Initialize trace batch"""user_context = self._get_user_context()execution_metadata = {@@ -296,7 +289,7 @@ class TraceCollectionListener(BaseEventListener):"crewai_version": get_crewai_version(),}- self.batch_manager.initialize_batch(user_context, execution_metadata)+ self._initialize_batch(user_context, execution_metadata)def _initialize_flow_batch(self, source: Any, event: Any):"""Initialize trace batch for Flow execution"""@@ -308,7 +301,20 @@ class TraceCollectionListener(BaseEventListener):"execution_type": "flow",}- self.batch_manager.initialize_batch(user_context, execution_metadata)+ self._initialize_batch(user_context, execution_metadata)++ def _initialize_batch(+ self, user_context: Dict[str, str], execution_metadata: Dict[str, Any]+ ):+ """Initialize trace batch if ephemeral"""+ if not self._check_authenticated():+ self.batch_manager.initialize_batch(+ user_context, execution_metadata, use_ephemeral=True+ )+ else:+ self.batch_manager.initialize_batch(+ user_context, execution_metadata, use_ephemeral=False+ )def _handle_trace_event(self, event_type: str, source: Any, event: Any):"""Generic handler for context end events"""diff --git a/src/crewai/utilities/events/listeners/tracing/utils.py b/src/crewai/utilities/events/listeners/tracing/utils.pyindex e498bc4f9..89a27a7d5 100644--- a/src/crewai/utilities/events/listeners/tracing/utils.py+++ b/src/crewai/utilities/events/listeners/tracing/utils.py@@ -1,5 +1,153 @@import os+import platform+import uuid+import hashlib+import subprocess+import getpass+from pathlib import Path+from datetime import datetime+import re+import json++import click++from crewai.utilities.paths import db_storage_pathdef is_tracing_enabled() -> bool:return os.getenv("CREWAI_TRACING_ENABLED", "false").lower() == "true"+++def on_first_execution_tracing_confirmation() -> bool:+ if _is_test_environment():+ return False++ if is_first_execution():+ mark_first_execution_done()+ return click.confirm(+ "This is the first execution of CrewAI. Do you want to enable tracing?",+ default=True,+ show_default=True,+ )+ return False+++def _is_test_environment() -> bool:+ """Detect if we're running in a test environment."""+ return os.environ.get("CREWAI_TESTING", "").lower() == "true"+++def _get_machine_id() -> str:+ """Stable, privacy-preserving machine fingerprint (cross-platform)."""+ parts = []++ try:+ mac = ":".join(+ ["{:02x}".format((uuid.getnode() >> b) & 0xFF) for b in range(0, 12, 2)][+ ::-1+ ]+ )+ parts.append(mac)+ except Exception:+ pass++ sysname = platform.system()+ parts.append(sysname)++ try:+ if sysname == "Darwin":+ res = subprocess.run(+ ["system_profiler", "SPHardwareDataType"],+ capture_output=True,+ text=True,+ timeout=2,+ )+ m = re.search(r"Hardware UUID:\s*([A-Fa-f0-9\-]+)", res.stdout)+ if m:+ parts.append(m.group(1))+ elif sysname == "Linux":+ try:+ parts.append(Path("/etc/machine-id").read_text().strip())+ except Exception:+ parts.append(Path("/sys/class/dmi/id/product_uuid").read_text().strip())+ elif sysname == "Windows":+ res = subprocess.run(+ ["wmic", "csproduct", "get", "UUID"],+ capture_output=True,+ text=True,+ timeout=2,+ )+ lines = [line.strip() for line in res.stdout.splitlines() if line.strip()]+ if len(lines) >= 2:+ parts.append(lines[1])+ except Exception:+ pass++ return hashlib.sha256("".join(parts).encode()).hexdigest()+++def _user_data_file() -> Path:+ base = Path(db_storage_path())+ base.mkdir(parents=True, exist_ok=True)+ return base / ".crewai_user.json"+++def _load_user_data() -> dict:+ p = _user_data_file()+ if p.exists():+ try:+ return json.loads(p.read_text())+ except Exception:+ pass+ return {}+++def _save_user_data(data: dict) -> None:+ try:+ p = _user_data_file()+ p.write_text(json.dumps(data, indent=2))+ except Exception:+ pass+++def get_user_id() -> str:+ """Stable, anonymized user identifier with caching."""+ data = _load_user_data()++ if "user_id" in data:+ return data["user_id"]++ try:+ username = getpass.getuser()+ except Exception:+ username = "unknown"++ seed = f"{username}|{_get_machine_id()}"+ uid = hashlib.sha256(seed.encode()).hexdigest()++ data["user_id"] = uid+ _save_user_data(data)+ return uid+++def is_first_execution() -> bool:+ """True if this is the first execution for this user."""+ data = _load_user_data()+ return not data.get("first_execution_done", False)+++def mark_first_execution_done() -> None:+ """Mark that the first execution has been completed."""+ data = _load_user_data()+ if data.get("first_execution_done", False):+ return++ data.update(+ {+ "first_execution_done": True,+ "first_execution_at": datetime.now().timestamp(),+ "user_id": get_user_id(),+ "machine_id": _get_machine_id(),+ }+ )+ _save_user_data(data)diff --git a/tests/conftest.py b/tests/conftest.pyindex 2a6f3b481..f67ad7222 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -34,11 +34,11 @@ def setup_test_environment():f"Test storage directory {storage_dir} is not writable: {e}")- # Set environment variable to point to the test storage directoryos.environ["CREWAI_STORAGE_DIR"] = str(storage_dir)-+ os.environ["CREWAI_TESTING"] = "true"yield+ os.environ.pop("CREWAI_TESTING", None)# Cleanup is handled automatically when tempfile context exitsdiff --git a/tests/tracing/test_tracing.py b/tests/tracing/test_tracing.pyindex 806eab3fb..62ef56c8b 100644--- a/tests/tracing/test_tracing.py+++ b/tests/tracing/test_tracing.py@@ -2,8 +2,8 @@ import osimport pytestfrom unittest.mock import patch, MagicMock-# Remove the module-level patchfrom crewai import Agent, Task, Crew+from crewai.flow.flow import Flow, startfrom crewai.utilities.events.listeners.tracing.trace_listener import (TraceCollectionListener,)@@ -284,29 +284,42 @@ class TestTraceListenerSetup:f"Found {len(trace_handlers)} trace handlers when tracing should be disabled")- def test_trace_listener_setup_correctly(self):+ def test_trace_listener_setup_correctly_for_crew(self):"""Test that trace listener is set up correctly when enabled"""with patch.dict(os.environ, {"CREWAI_TRACING_ENABLED": "true"}):- trace_listener = TraceCollectionListener()-- assert trace_listener.trace_enabled is True- assert trace_listener.batch_manager is not None+ agent = Agent(+ role="Test Agent",+ goal="Test goal",+ backstory="Test backstory",+ llm="gpt-4o-mini",+ )+ task = Task(+ description="Say hello to the world",+ expected_output="hello world",+ agent=agent,+ )+ with patch.object(+ TraceCollectionListener, "setup_listeners"+ ) as mock_listener_setup:+ Crew(agents=[agent], tasks=[task], verbose=True)+ assert mock_listener_setup.call_count >= 1- @pytest.mark.vcr(filter_headers=["authorization"])- def test_trace_listener_setup_correctly_with_tracing_flag(self):+ def test_trace_listener_setup_correctly_for_flow(self):"""Test that trace listener is set up correctly when enabled"""- agent = Agent(role="Test Agent", goal="Test goal", backstory="Test backstory")- task = Task(- description="Say hello to the world",- expected_output="hello world",- agent=agent,- )- crew = Crew(agents=[agent], tasks=[task], verbose=True, tracing=True)- crew.kickoff()- trace_listener = TraceCollectionListener(tracing=True)- assert trace_listener.trace_enabled is True- assert trace_listener.batch_manager is not None++ with patch.dict(os.environ, {"CREWAI_TRACING_ENABLED": "true"}):++ class FlowExample(Flow):+ @start()+ def start(self):+ pass++ with patch.object(+ TraceCollectionListener, "setup_listeners"+ ) as mock_listener_setup:+ FlowExample()+ assert mock_listener_setup.call_count >= 1# Helper method to ensure cleanupdef teardown_method(self):