otelzero 0.2.0__py3-none-any.whl

otelzero/__init__.py

@@ -0,0 +1,62 @@
+"""otelzero: instrument agent frameworks via import hooks and send telemetry.
+
+Install monitoring for your framework *before* importing it, then run as usual::
+
+    from otelzero import install_crewai_monitoring
+
+    install_crewai_monitoring(server_url="http://localhost:8000")
+    from crewai import Agent, Crew, Task  # now auto-instrumented
+
+Supports CrewAI, LangChain, LangGraph, LlamaIndex, the OpenAI Agents SDK,
+Pydantic AI, smolagents, AWS Strands Agents, Google ADK, Databricks Agent Bricks,
+the Claude Agent SDK, Microsoft Agent Framework and the Snowflake Cortex Agent
+SDK, plus framework-agnostic manual instrumentation via ``install_monitoring``.
+
+Pydantic AI, AWS Strands Agents, Google ADK and Microsoft Agent Framework already
+trace themselves in the GenAI semantic conventions, and LangChain / LangGraph
+trace themselves through LangSmith's OpenTelemetry export. Their install
+functions switch that native OpenTelemetry on (exporting to the registry)
+instead of wrapping anything, so for these the import order does not matter.
+
+"""
+
+from otelzero.context import run_context
+from otelzero.hooks import (
+    install_adk_monitoring,
+    install_claude_agent_monitoring,
+    install_crewai_monitoring,
+    install_databricks_monitoring,
+    install_langchain_monitoring,
+    install_langgraph_monitoring,
+    install_llama_index_monitoring,
+    install_microsoft_monitoring,
+    install_openai_agents_monitoring,
+    install_pydantic_ai_monitoring,
+    install_smolagents_monitoring,
+    install_snowflake_monitoring,
+    install_strands_monitoring,
+)
+from otelzero.telemetry import TelemetryClient, install_monitoring
+
+# Kept in sync with [project].version by commitizen (`cz bump`).
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    "TelemetryClient",
+    "run_context",
+    "install_monitoring",
+    "install_adk_monitoring",
+    "install_claude_agent_monitoring",
+    "install_crewai_monitoring",
+    "install_databricks_monitoring",
+    "install_langchain_monitoring",
+    "install_langgraph_monitoring",
+    "install_llama_index_monitoring",
+    "install_microsoft_monitoring",
+    "install_openai_agents_monitoring",
+    "install_pydantic_ai_monitoring",
+    "install_smolagents_monitoring",
+    "install_snowflake_monitoring",
+    "install_strands_monitoring",
+]

otelzero/__main__.py

@@ -0,0 +1,140 @@
+"""
+CrewAI Monitoring Demo
+"""
+
+import sys
+import time
+
+from otelzero import TelemetryClient, install_crewai_monitoring
+from otelzero.detection import _detect_package_version
+
+
+def main():
+    print("=" * 60)
+    print("CrewAI Monitoring Demo")
+    print("=" * 60)
+    print()
+    print("Make sure the server is running:")
+    print("   uv run kiji-agent-registry  (in the kiji-agent-registry repo)")
+    print()
+    print("Then open the dashboard:")
+    print("   http://localhost:8000")
+    print()
+    print("=" * 60)
+    print()
+
+    # Install monitoring BEFORE importing crewai
+    install_crewai_monitoring(server_url="http://localhost:8000")
+
+    # Now import crewai - it will be instrumented automatically
+    try:
+        from crewai import Agent, Crew, Task
+
+        print("CrewAI imported and instrumented")
+        print()
+    except ImportError:
+        print("CrewAI not installed. Install with: pip install crewai")
+        print("   For demo purposes, we'll simulate the workflow...")
+        print()
+
+        # Simulate some agent activity for demo
+        telemetry = TelemetryClient(
+            framework="CrewAI",
+            framework_version=_detect_package_version("crewai") or "0.102.0",
+            user="Sarah",
+        )
+
+        print("Simulating agent activities...")
+        for i in range(5):
+            agent_role = f"Agent-{i % 2 + 1}"
+
+            # Start
+            telemetry.send_log(
+                event_type="agent_start",
+                agent_role=agent_role,
+                details={"goal": f"Complete task {i}"},
+            )
+            time.sleep(0.5)
+
+            # End or Error
+            if i % 4 == 0:  # Simulate occasional error
+                telemetry.send_log(
+                    event_type="agent_error",
+                    agent_role=agent_role,
+                    error="Simulated error",
+                    traceback="Sample traceback...",
+                )
+            else:
+                telemetry.send_log(
+                    event_type="agent_end",
+                    agent_role=agent_role,
+                    details={"status": "success"},
+                )
+
+            print(f"  {agent_role}: Run {i + 1} completed")
+            time.sleep(1)
+
+        print()
+        print("Simulation complete! Check the dashboard.")
+        sys.exit(0)
+
+    # Real CrewAI example
+    print("Creating CrewAI agents and tasks...")
+    print()
+
+    # Create multiple agents
+    researcher = Agent(
+        role="Research Analyst",
+        goal="Conduct comprehensive research on AI trends",
+        backstory="Expert data analyst with 10 years of experience in AI research",
+        verbose=True,
+    )
+
+    writer = Agent(
+        role="Content Writer",
+        goal="Write engaging content based on research",
+        backstory="Professional writer specializing in technology topics",
+        verbose=True,
+    )
+
+    # Create tasks
+    research_task = Task(
+        description="Research the latest developments in Large Language Models",
+        expected_output="A detailed research report",
+        agent=researcher,
+    )
+
+    writing_task = Task(
+        description="Write an article based on the research findings",
+        expected_output="A well-written article",
+        agent=writer,
+    )
+
+    # Create and run crew
+    crew = Crew(
+        agents=[researcher, writer], tasks=[research_task, writing_task], verbose=True
+    )
+
+    print("Starting crew execution...")
+    print("Watch the dashboard at http://localhost:8000")
+    print()
+
+    try:
+        result = crew.kickoff()
+        print()
+        print("=" * 60)
+        print("Crew execution completed!")
+        print("=" * 60)
+        print(f"Result: {result}")
+    except Exception as e:
+        print()
+        print("=" * 60)
+        print(f"Crew execution failed: {e}")
+        print("=" * 60)
+
+    print()
+    print("Check the monitoring dashboard for detailed logs!")
+    print("Dashboard: http://localhost:8000")
+
+
+main()

otelzero/context.py

@@ -0,0 +1,86 @@
+"""Per-run identity for agents that serve more than one user.
+
+:class:`~otelzero.telemetry.TelemetryClient` carries a process-wide user and
+session, which is right for a script: one process, one person, one run. It is
+wrong for a hosted agent, where a single process handles many callers -- every
+run would report the same user and collapse into one flow.
+
+Wrapping a run in :func:`run_context` gives it its own identity::
+
+    with otelzero.run_context(user="alice", conversation_id=thread_id):
+        crew.kickoff(...)
+
+Because the scope lives in a :class:`~contextvars.ContextVar`, concurrent
+``asyncio`` tasks and threads each see their own without any hook signature
+having to thread it through. Outside a scope nothing changes: the client's
+defaults apply exactly as before.
+"""
+
+import contextlib
+import contextvars
+import uuid
+from typing import Iterator, Optional
+
+
+class RunScope:
+    """The identity of one agent run: who invoked it, and which flow it is.
+
+    ``session_name`` is mutable because the title is discovered rather than
+    given -- the first framework hook to see the run's intent text fills it in
+    via :meth:`TelemetryClient.suggest_session_name`.
+    """
+
+    __slots__ = ("user", "conversation_id", "session_name")
+
+    def __init__(
+        self,
+        user: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        session_name: Optional[str] = None,
+    ):
+        self.user = user
+        self.conversation_id = conversation_id
+        self.session_name = session_name
+
+
+_current_scope: contextvars.ContextVar[Optional[RunScope]] = contextvars.ContextVar(
+    "otelzero_run_scope", default=None
+)
+
+
+def current_scope() -> Optional[RunScope]:
+    """The :class:`RunScope` in effect, or ``None`` outside :func:`run_context`."""
+    return _current_scope.get()
+
+
+@contextlib.contextmanager
+def run_context(
+    user: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    name: Optional[str] = None,
+) -> Iterator[RunScope]:
+    """Scope the enclosed agent run to its own user and conversation.
+
+    Args:
+        user: Who this run is for. Falls back to the client's user when omitted.
+        conversation_id: Groups this run's events into one flow, and is exported
+            as ``gen_ai.conversation.id``. Pass your own thread/session id to
+            keep a multi-turn conversation together; a fresh one is generated
+            per scope otherwise.
+        name: A short human title for the flow. Left to the framework hooks to
+            derive from the run's intent text when omitted.
+
+    Yields:
+        The active :class:`RunScope`, mainly so callers can read back the
+        generated ``conversation_id``.
+    """
+    scope = RunScope(
+        user=user,
+        conversation_id=conversation_id or uuid.uuid4().hex[:8],
+        session_name=name.strip() if isinstance(name, str) and name.strip() else None,
+    )
+    token = _current_scope.set(scope)
+    try:
+        yield scope
+    finally:
+        _current_scope.reset(token)

otelzero/detection.py

@@ -0,0 +1,58 @@
+"""Best-effort detection of the executing user and installed package versions.
+
+These helpers are intentionally defensive: every lookup degrades to ``None``
+rather than raising, so instrumentation never breaks the host application just
+because a name or version could not be resolved.
+"""
+
+import getpass
+from typing import Optional
+
+
+def _detect_user() -> Optional[str]:
+    """Best-effort login name of the user running the agent.
+
+    Uses ``getpass.getuser()`` (env vars LOGNAME/USER/USERNAME, then the password
+    database) -- works without a controlling TTY, unlike ``os.getlogin()``.
+    """
+    try:
+        return getpass.getuser()
+    except Exception:  # getpass can raise OSError when it cannot resolve a name
+        return None
+
+
+def _detect_package_version(package: str) -> Optional[str]:
+    """Try to detect the installed version of a package."""
+    try:
+        from importlib.metadata import version
+
+        return version(package)
+    except Exception:
+        return None
+
+
+# Framework display labels whose PyPI distribution name is not simply the label
+# lower-cased with spaces hyphenated. Microsoft's framework is branded "Microsoft
+# Agent Framework" but ships as the ``agent-framework`` distribution; Snowflake's
+# is branded "Snowflake Cortex" but ships as ``cortex-code-agent-sdk``; LlamaIndex
+# is one word but its core ships as ``llama-index-core``.
+_FRAMEWORK_DIST_ALIASES = {
+    "microsoft agent framework": "agent-framework",
+    "snowflake cortex": "cortex-code-agent-sdk",
+    "llamaindex": "llama-index-core",
+}
+
+
+def _detect_framework_version(framework: Optional[str]) -> Optional[str]:
+    """Detect the installed version of a framework from its name.
+
+    Normalizes the framework label to a distribution name (e.g. ``"CrewAI"`` ->
+    ``"crewai"``, ``"LangChain"`` -> ``"langchain"``) and looks up its version.
+    A few labels whose distribution name differs from that convention are mapped
+    explicitly via :data:`_FRAMEWORK_DIST_ALIASES`.
+    """
+    if not framework:
+        return None
+    key = framework.lower()
+    dist = _FRAMEWORK_DIST_ALIASES.get(key, key.replace(" ", "-"))
+    return _detect_package_version(dist)

otelzero/hooks/__init__.py

@@ -0,0 +1,96 @@
+"""Framework-specific import hooks and their ``install_*_monitoring`` helpers.
+
+Most submodules instrument one agent framework by intercepting its import and
+wrapping the run entry point(s), building on :mod:`otelzero.hooks.base`. The
+frameworks that already trace themselves in the GenAI semantic conventions
+(Pydantic AI, AWS Strands Agents, Google ADK, Microsoft Agent Framework) and
+LangChain / LangGraph (through LangSmith's OTel export) are instead switched
+onto their *native* OpenTelemetry and observed through
+:mod:`otelzero.hooks._native`.
+"""
+
+from otelzero.hooks.adk import install_adk_monitoring
+from otelzero.hooks.base import (
+    _ImportInstrumenter,
+    _InstrumentingLoader,
+    install_hook,
+    nesting_guard,
+    start_agent_run,
+    trace_agent_run,
+)
+from otelzero.hooks.claude_sdk import (
+    ClaudeAgentSDKImportHook,
+    _claude_model_id,
+    install_claude_agent_monitoring,
+)
+from otelzero.hooks.crewai import (
+    CrewAIImportHook,
+    _crewai_model_id,
+    install_crewai_monitoring,
+)
+from otelzero.hooks.databricks import (
+    DatabricksImportHook,
+    install_databricks_monitoring,
+)
+from otelzero.hooks.langchain import install_langchain_monitoring
+from otelzero.hooks.langgraph import install_langgraph_monitoring
+from otelzero.hooks.llama_index import (
+    LlamaIndexImportHook,
+    _llama_index_model_id,
+    install_llama_index_monitoring,
+    wrap_workflow_module,
+)
+from otelzero.hooks.microsoft import install_microsoft_monitoring
+from otelzero.hooks.openai_agents import (
+    OpenAIAgentsImportHook,
+    _agents_model_id,
+    install_openai_agents_monitoring,
+)
+from otelzero.hooks.pydantic_ai import install_pydantic_ai_monitoring
+from otelzero.hooks.smolagents import (
+    SmolagentsImportHook,
+    _smolagents_model_id,
+    install_smolagents_monitoring,
+)
+from otelzero.hooks.snowflake import (
+    SnowflakeCortexImportHook,
+    _snowflake_model_id,
+    install_snowflake_monitoring,
+)
+from otelzero.hooks.strands import install_strands_monitoring
+
+__all__ = [
+    "ClaudeAgentSDKImportHook",
+    "CrewAIImportHook",
+    "DatabricksImportHook",
+    "LlamaIndexImportHook",
+    "OpenAIAgentsImportHook",
+    "SmolagentsImportHook",
+    "SnowflakeCortexImportHook",
+    "install_adk_monitoring",
+    "install_claude_agent_monitoring",
+    "install_crewai_monitoring",
+    "install_databricks_monitoring",
+    "install_langchain_monitoring",
+    "install_langgraph_monitoring",
+    "install_llama_index_monitoring",
+    "install_microsoft_monitoring",
+    "install_openai_agents_monitoring",
+    "install_pydantic_ai_monitoring",
+    "install_smolagents_monitoring",
+    "install_snowflake_monitoring",
+    "install_strands_monitoring",
+    "install_hook",
+    "nesting_guard",
+    "start_agent_run",
+    "trace_agent_run",
+    "wrap_workflow_module",
+    "_ImportInstrumenter",
+    "_InstrumentingLoader",
+    "_agents_model_id",
+    "_claude_model_id",
+    "_crewai_model_id",
+    "_llama_index_model_id",
+    "_smolagents_model_id",
+    "_snowflake_model_id",
+]