fiddler-adk 1.0.0rc1__py3-none-any.whl

fiddler_adk/__init__.py

@@ -0,0 +1,17 @@
+"""Fiddler ADK - Google ADK (Agent Development Kit) instrumentation for Fiddler."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from fiddler_adk.instrumentation import GoogleADKInstrumentor
+from fiddler_adk.span_processor import ADKSpanProcessor
+
+try:
+    __version__ = version('fiddler-adk')
+except PackageNotFoundError:
+    __version__ = 'unknown'
+
+__all__ = [
+    'ADKSpanProcessor',
+    'GoogleADKInstrumentor',
+    '__version__',
+]

fiddler_adk/instrumentation.py

@@ -0,0 +1,121 @@
+"""OpenTelemetry instrumentation for Google ADK (Agent Development Kit).
+
+Google ADK emits OpenTelemetry spans natively through a module-level tracer
+named ``gcp.vertex.agent`` that resolves against the **global** tracer
+provider.  This instrumentor sets up a Fiddler-managed tracer provider (via
+:class:`~fiddler_otel.client.FiddlerClient`) and promotes it to global so
+ADK's tracer resolves to it.
+
+The SDK operates in standalone mode: it initialises its own isolated tracer,
+provider, processor, and exporter via ``FiddlerClient``.  It does not interact
+with customer-configured tracers or providers.
+
+Content extraction and attribute mapping are handled by the Fiddler backend's
+``GoogleADKSpanMapper`` — not by this SDK.
+
+Example::
+
+    from fiddler_otel import FiddlerClient
+    from fiddler_adk import GoogleADKInstrumentor
+
+    client = FiddlerClient(url="...", api_key="...", application_id="...")
+    GoogleADKInstrumentor(client).instrument()
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Collection
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry.instrumentation.instrumentor import (  # type: ignore[attr-defined]
+    BaseInstrumentor,
+)
+from opentelemetry.sdk.trace import TracerProvider as SDKTracerProvider
+
+from fiddler_adk.span_processor import ADKSpanProcessor
+from fiddler_otel.client import FiddlerClient
+
+logger = logging.getLogger(__name__)
+
+
+def _get_package_version(package_name: str) -> str:
+    """Return the installed version of a package, or ``'unknown'``."""
+    try:
+        return version(package_name)
+    except PackageNotFoundError:
+        return 'unknown'
+
+
+class GoogleADKInstrumentor(BaseInstrumentor):
+    """OpenTelemetry instrumentor for Google ADK agents.
+
+    Sets up the Fiddler tracing pipeline via ``FiddlerClient`` and promotes
+    it to the global tracer provider so ADK's ``gcp.vertex.agent`` tracer
+    resolves to it.  Adds ``ADKSpanProcessor`` for root-span conversation-id
+    backfill.
+
+    The SDK operates in standalone mode — it initialises its own isolated
+    tracer, provider, processor, and exporter.  It does not interact with
+    customer-configured tracers.
+    """
+
+    def __init__(self, client: FiddlerClient):
+        """Initialise the Google ADK instrumentor.
+
+        :param client: The ``FiddlerClient`` instance that owns the tracing
+            pipeline (tracer, provider, processor, exporter).
+        """
+        self._client = client
+        self._provider_configured = False
+
+        self._client.update_resource(
+            {
+                'lib.google-adk.version': _get_package_version('google-adk'),
+                'lib.fiddler-adk.version': _get_package_version('fiddler-adk'),
+            }
+        )
+        super().__init__()
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        """Return the packages required for this instrumentation."""
+        return ['google-adk']
+
+    def _instrument(self, **kwargs: Any) -> None:
+        """Enable instrumentation: set up tracer provider with ADKSpanProcessor."""
+        self._setup_tracer_provider()
+        logger.info('Google ADK instrumentation enabled')
+
+    def _uninstrument(self, **kwargs: Any) -> None:
+        """Disable instrumentation.
+
+        The tracer provider wiring is left in place: OpenTelemetry does not
+        support unsetting the global provider or removing span processors.
+        """
+        logger.info('Google ADK instrumentation disabled')
+
+    def _setup_tracer_provider(self) -> None:
+        """Set up the Fiddler tracer provider and promote it to global.
+
+        Uses ``FiddlerClient.get_tracer()`` which initialises the complete
+        tracing pipeline (provider, processor, exporter) in isolation.
+        The client's provider is then promoted to the global provider so
+        ADK's ``gcp.vertex.agent`` tracer resolves to it.
+        """
+        if self._provider_configured:
+            return
+
+        # Initialise the Fiddler tracing pipeline
+        self._client.get_tracer()
+        provider = self._client.get_tracer_provider()
+
+        # Add ADK-specific span processor for root-span conversation-id backfill.
+        if isinstance(provider, SDKTracerProvider):
+            provider.add_span_processor(ADKSpanProcessor())
+
+        # Promote to global so ADK's tracer resolves to Fiddler's provider
+        trace.set_tracer_provider(provider)
+
+        self._provider_configured = True

fiddler_adk/span_processor.py

@@ -0,0 +1,109 @@
+"""ADK span processor: extends fiddler-otel with ADK-specific span enrichment.
+
+This is a pure ``SpanProcessor`` approach — no monkey-patching.
+
+Responsibilities:
+
+*  ``on_end``: backfill ``gen_ai.conversation.id`` onto the root ``invocation``
+   span, which ADK leaves attribute-less (it only stamps conversation id on
+   child spans).
+
+All other enrichment (span-type classification, agent ID, content extraction,
+attribute normalization) is handled by the Fiddler backend's
+``GoogleADKSpanMapper``.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+
+from opentelemetry import context
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace import Span as SDKSpan
+from opentelemetry.trace import Span
+
+from fiddler_otel.attributes import FiddlerSpanAttributes
+from fiddler_otel.span_processor import FiddlerSpanProcessor as CoreFiddlerSpanProcessor
+
+logger = logging.getLogger(__name__)
+
+
+class ADKSpanProcessor(CoreFiddlerSpanProcessor):
+    """Backfills ``gen_ai.conversation.id`` onto the root ADK span.
+
+    Extends :class:`CoreFiddlerSpanProcessor` (contextvar injection, attribute
+    denormalization). ADK sets ``gen_ai.conversation.id`` only on child spans
+    (``invoke_agent``, ``call_llm``, etc.); the root ``invocation`` span gets no
+    attributes. This processor copies the conversation id onto the still-open
+    root span when the first child carrying it ends.
+
+    All other enrichment (span-type classification, agent ID computation,
+    content extraction, attribute normalization) is delegated to the Fiddler
+    backend's ``GoogleADKSpanMapper``.
+    """
+
+    def __init__(self) -> None:
+        """Initialise the processor and the live-root-span registry."""
+        super().__init__()
+        # Maps trace_id -> the still-open root span, so a child's
+        # ``gen_ai.conversation.id`` can be backfilled onto the root on end.
+        self._root_spans: dict[int, Span] = {}
+        self._root_lock = threading.Lock()
+
+    def on_start(self, span: Span, parent_context: context.Context | None = None) -> None:
+        """Track root spans, then delegate to core."""
+        self._track_root_span(span)
+        super().on_start(span, parent_context)
+
+    def on_end(self, span: ReadableSpan) -> None:
+        """Backfill ``gen_ai.conversation.id`` onto the root span.
+
+        ADK only sets ``gen_ai.conversation.id`` on child spans (``invoke_agent``,
+        ``call_llm``, etc.); the root ``invocation`` span gets no attributes. The
+        root span stays open for the whole run, so when a child ends we copy its
+        conversation id onto the still-recording root span.
+        """
+        try:
+            self._backfill_root_conversation_id(span)
+        except Exception as e:  # pylint: disable=broad-except
+            logger.debug('Failed to backfill root conversation id: %s', e, exc_info=True)
+        super().on_end(span)
+
+    def _track_root_span(self, span: Span) -> None:
+        """Remember the root span of each trace so children can backfill onto it."""
+        if getattr(span, 'parent', None) is not None:
+            return
+        span_context = span.get_span_context()
+        if span_context is None:
+            return
+        with self._root_lock:
+            self._root_spans[span_context.trace_id] = span
+
+    def _backfill_root_conversation_id(self, span: ReadableSpan) -> None:
+        """Copy a child's conversation id onto the open root span; clean up on root end."""
+        span_context = span.context
+        if span_context is None:
+            return
+        trace_id = span_context.trace_id
+
+        with self._root_lock:
+            root = self._root_spans.get(trace_id)
+            # The root span itself is ending — drop the reference and stop.
+            if root is not None and span_context.span_id == root.get_span_context().span_id:
+                del self._root_spans[trace_id]
+                return
+
+        if not isinstance(root, SDKSpan):
+            return
+
+        conversation_id = (span.attributes or {}).get(FiddlerSpanAttributes.CONVERSATION_ID)
+        if not conversation_id:
+            return
+
+        if not (root.is_recording() and root.attributes is not None):
+            return
+        if FiddlerSpanAttributes.CONVERSATION_ID in root.attributes:
+            return
+
+        root.set_attribute(FiddlerSpanAttributes.CONVERSATION_ID, conversation_id)

fiddler_adk-1.0.0rc1.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: fiddler-adk
+Version: 1.0.0rc1
+Summary: Fiddler SDK for Google ADK (Agent Development Kit) instrumentation with OpenTelemetry
+Author-email: Fiddler AI <support@fiddler.ai>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://fiddler.ai
+Project-URL: Documentation, https://docs.fiddler.ai
+Project-URL: Repository, https://github.com/fiddler-labs/fiddler-sdk
+Project-URL: Issues, https://github.com/fiddler-labs/fiddler-sdk/issues
+Keywords: fiddler,ai,genai,llm,monitoring,observability,instrumentation,google-adk,adk,opentelemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fiddler-otel<2.0.0,>=1.0.0
+Requires-Dist: google-adk>=1.34.2
+Requires-Dist: opentelemetry-api>=1.37.0
+Requires-Dist: opentelemetry-sdk>=1.37.0
+Requires-Dist: opentelemetry-instrumentation>=0.58b0
+Requires-Dist: opentelemetry-exporter-otlp>=1.37.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: examples
+Requires-Dist: python-dotenv>=1.0.0; extra == "examples"
+
+# fiddler-adk
+
+Fiddler SDK for instrumenting [Google ADK](https://github.com/google/adk-python) (Agent Development Kit) with OpenTelemetry.
+
+This package lives in the [fiddler-sdk](https://github.com/fiddler-labs/fiddler-sdk) monorepo under `packages/integrations/fiddler-adk/`. It depends on [`fiddler-otel`](../../fiddler-otel) for the OTel pipeline, span attributes, and span processing.
+
+## Install
+
+```bash
+pip install fiddler-adk
+```
+
+## Usage
+
+```python
+from fiddler_otel import FiddlerClient
+from fiddler_adk import GoogleADKInstrumentor
+
+client = FiddlerClient(
+    api_key='YOUR_API_KEY',
+    application_id='YOUR_APPLICATION_ID',  # UUID4 from the Fiddler GenAI Applications page
+    url='https://your-instance.fiddler.ai',
+)
+GoogleADKInstrumentor(client).instrument()
+
+# Build and run ADK agents as usual — traces flow to Fiddler automatically.
+```
+
+## How it works
+
+Google ADK emits OpenTelemetry spans natively (`invoke_agent`, `call_llm`,
+`execute_tool`, ...) through a tracer that resolves against the **global**
+tracer provider. `GoogleADKInstrumentor.instrument()`:
+
+1. **Routes spans to Fiddler.** If no global tracer provider is configured,
+   the Fiddler client's provider (span processor + OTLP exporter) is promoted
+   to global. If your application (or `adk web`) already configured one, the
+   Fiddler span processor and exporter are attached to it instead.
+2. **Enriches span attributes.** An `ADKSpanProcessor` reads the JSON attributes
+   that ADK natively sets on spans (`gcp.vertex.agent.llm_request`, etc.) and
+   maps them to `gen_ai.llm.input.user`, `gen_ai.llm.input.system`,
+   `gen_ai.llm.output`, `gen_ai.tool.input`, and `gen_ai.tool.output` — the
+   attributes Fiddler's evaluations consume. No monkey-patching is involved.
+
+### Conversation and session context
+
+```python
+import uuid
+from fiddler_adk import add_session_attributes, set_conversation_id
+
+set_conversation_id(str(uuid.uuid4()))          # gen_ai.conversation.id on all spans
+add_session_attributes('user_tier', 'premium')  # fiddler.session.user.user_tier on all spans
+```
+
+### Content capture
+
+ADK includes full LLM request/response payloads in span attributes by default.
+Set `ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false` to disable ADK's payload
+capture if your prompts may contain PII.
+
+See `examples/` in this directory for a runnable agent.

fiddler_adk-1.0.0rc1.dist-info/RECORD

@@ -0,0 +1,7 @@
+fiddler_adk/__init__.py,sha256=b3gnUqv24j7yBFllu1XuSb5A1BUgxloLuwj_SMqs5N8,456
+fiddler_adk/instrumentation.py,sha256=l--RYnW1IIPR0gkmKK4KQrnGIGWB-82GcmxOpukKsZA,4513
+fiddler_adk/span_processor.py,sha256=1PGjJYUfAskTGDc7KPgNeMukpZa1XV9FyBlL1qwqQws,4392
+fiddler_adk-1.0.0rc1.dist-info/METADATA,sha256=MRQo1YSfHQBX-wJENTuJh8vi1-Prp3XqUUiTBl94p9Y,3974
+fiddler_adk-1.0.0rc1.dist-info/WHEEL,sha256=YLJXdYXQ2FQ0Uqn2J-6iEIC-3iOey8lH3xCtvFLkd8Q,91
+fiddler_adk-1.0.0rc1.dist-info/top_level.txt,sha256=8MFhPOdEqsxcEyzJjg7CuXkoX4ro4lgvAx8reLEc5W0,12
+fiddler_adk-1.0.0rc1.dist-info/RECORD,,

fiddler_adk-1.0.0rc1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (81.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fiddler_adk-1.0.0rc1.dist-info/top_level.txt

@@ -0,0 +1 @@
+fiddler_adk