genkit-plugin-google-cloud 0.3.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

genkit/plugins/google_cloud/__init__.py

@@ -15,7 +15,132 @@
 # SPDX-License-Identifier: Apache-2.0
 
 
-"""Google Cloud Plugin for Genkit."""
+"""Google Cloud Plugin for Genkit.
+
+This plugin provides Google Cloud observability integration for Genkit,
+enabling telemetry export to Cloud Trace and Cloud Monitoring.
+
+Key Concepts (ELI5)::
+
+    ┌─────────────────────┬────────────────────────────────────────────────────┐
+    │ Concept             │ ELI5 Explanation                                   │
+    ├─────────────────────┼────────────────────────────────────────────────────┤
+    │ Telemetry           │ Data about how your app is running. Like a        │
+    │                     │ fitness tracker for your code.                    │
+    ├─────────────────────┼────────────────────────────────────────────────────┤
+    │ Cloud Trace         │ Shows the path requests take through your app.    │
+    │                     │ Like GPS tracking for your API calls.             │
+    ├─────────────────────┼────────────────────────────────────────────────────┤
+    │ Cloud Monitoring    │ Graphs and alerts for your app's health.          │
+    │                     │ Like a heart rate monitor dashboard.              │
+    ├─────────────────────┼────────────────────────────────────────────────────┤
+    │ Span                │ One step in a request's journey. Like one         │
+    │                     │ leg of a relay race.                              │
+    ├─────────────────────┼────────────────────────────────────────────────────┤
+    │ Trace               │ All spans for one request connected together.     │
+    │                     │ The complete story of one API call.               │
+    ├─────────────────────┼────────────────────────────────────────────────────┤
+    │ Metrics             │ Numbers that describe your app (requests/sec,     │
+    │                     │ error rate, latency). Like a report card.         │
+    ├─────────────────────┼────────────────────────────────────────────────────┤
+    │ PII Redaction       │ Hiding sensitive data in traces. Like blurring    │
+    │                     │ faces in photos before sharing.                   │
+    └─────────────────────┴────────────────────────────────────────────────────┘
+
+Data Flow::
+
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │                    HOW TELEMETRY FLOWS TO GOOGLE CLOUD                  │
+    │                                                                         │
+    │    Your Genkit App                                                      │
+    │         │                                                               │
+    │         │  (1) App runs flows, calls models, uses tools                 │
+    │         ▼                                                               │
+    │    ┌─────────────────┐                                                  │
+    │    │  OpenTelemetry  │   Automatically creates spans for each           │
+    │    │  SDK            │   operation (you don't write this code!)         │
+    │    └────────┬────────┘                                                  │
+    │             │                                                           │
+    │             │  (2) Spans collected and processed                        │
+    │             ▼                                                           │
+    │    ┌─────────────────┐                                                  │
+    │    │  GCP Exporters  │   • Redact PII (input/output)                    │
+    │    │                 │   • Add error markers                            │
+    │    │                 │   • Batch for efficiency                         │
+    │    └────────┬────────┘                                                  │
+    │             │                                                           │
+    │             │  (3) HTTPS to Google Cloud                                │
+    │             ▼                                                           │
+    │    ════════════════════════════════════════════════════                 │
+    │             │  Internet                                                 │
+    │             ▼                                                           │
+    │    ┌─────────────────────────────────────────────────────┐              │
+    │    │  Google Cloud Console                               │              │
+    │    │  ┌──────────────┐  ┌──────────────┐                │              │
+    │    │  │ Cloud Trace  │  │ Cloud        │                │              │
+    │    │  │ (waterfall   │  │ Monitoring   │                │              │
+    │    │  │  diagrams)   │  │ (dashboards) │                │              │
+    │    │  └──────────────┘  └──────────────┘                │              │
+    │    └─────────────────────────────────────────────────────┘              │
+    └─────────────────────────────────────────────────────────────────────────┘
+
+Architecture Overview::
+
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │                      Google Cloud Plugin                                │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  Plugin Entry Point (__init__.py)                                       │
+    │  └── add_gcp_telemetry() - Enable Cloud Trace/Monitoring export         │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  telemetry/__init__.py - Telemetry Module                               │
+    │  └── Re-exports from submodules                                         │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  telemetry/tracing.py - Distributed Tracing                             │
+    │  ├── Cloud Trace exporter configuration                                 │
+    │  └── OpenTelemetry integration                                          │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  telemetry/metrics.py - Metrics Collection                              │
+    │  ├── Cloud Monitoring exporter                                          │
+    │  └── Custom Genkit metrics                                              │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  telemetry/action.py - Action Instrumentation                           │
+    │  └── Automatic span creation for Genkit actions                         │
+    └─────────────────────────────────────────────────────────────────────────┘
+
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │                     Telemetry Data Flow                                 │
+    │                                                                         │
+    │  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────┐      │
+    │  │ Genkit App   │───►│ OpenTelemetry│───►│ Google Cloud         │      │
+    │  │ (actions,    │    │ SDK          │    │ (Trace, Monitoring)  │      │
+    │  │  flows)      │    └──────────────┘    └──────────────────────┘      │
+    │  └──────────────┘                                                       │
+    └─────────────────────────────────────────────────────────────────────────┘
+
+Example:
+    ```python
+    from genkit.plugins.google_cloud import add_gcp_telemetry
+
+    # Enable telemetry export to Google Cloud
+    add_gcp_telemetry()
+
+    # Traces and metrics are now exported to:
+    # - Cloud Trace (distributed tracing)
+    # - Cloud Monitoring (metrics)
+    ```
+
+Caveats:
+    - Requires Google Cloud credentials (ADC or explicit)
+    - Telemetry is disabled by default in development mode (GENKIT_ENV=dev)
+    - Requires opentelemetry and google-cloud-* packages
+
+See Also:
+    - Cloud Trace: https://cloud.google.com/trace
+    - Cloud Monitoring: https://cloud.google.com/monitoring
+    - Genkit documentation: https://genkit.dev/
+"""
+
+from .telemetry import add_gcp_telemetry
 
 
 def package_name() -> str:
@@ -27,4 +152,4 @@ def package_name() -> str:
     return 'genkit.plugins.google_cloud'
 
 
-__all__ = ['package_name']
+__all__ = ['add_gcp_telemetry', 'package_name']

genkit/plugins/google_cloud/telemetry/__init__.py

@@ -0,0 +1,74 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Google Cloud telemetry integration for Genkit.
+
+This package provides telemetry export to Google Cloud's observability suite,
+enabling monitoring and debugging of Genkit applications through Cloud Trace,
+Cloud Monitoring, and Cloud Logging.
+
+Module Structure:
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │ Module          │ Purpose                                               │
+    ├─────────────────┼───────────────────────────────────────────────────────┤
+    │ tracing.py      │ Main entry point, exporters, configuration            │
+    │ feature.py      │ Root span metrics (requests, latency)                 │
+    │ path.py         │ Error path tracking and failure metrics               │
+    │ generate.py     │ Model/generate metrics (tokens, latency, media)       │
+    │ action.py       │ Action I/O logging (tools, flows)                     │
+    │ engagement.py   │ User feedback and acceptance metrics                  │
+    │ metrics.py      │ Metric definitions and lazy initialization            │
+    │ utils.py        │ Shared utilities (truncation, path parsing, logging)  │
+    └─────────────────┴───────────────────────────────────────────────────────┘
+
+Quick Start:
+    ```python
+    from genkit.plugins.google_cloud import add_gcp_telemetry
+
+    # Enable telemetry with defaults (PII redaction enabled)
+    add_gcp_telemetry()
+
+    # Or with custom options
+    add_gcp_telemetry(
+        project_id='my-project',
+        log_input_and_output=True,  # Disable PII redaction (caution!)
+    )
+    ```
+
+Cross-Language Parity:
+    This implementation maintains feature parity with:
+    - JavaScript: js/plugins/google-cloud/src/gcpOpenTelemetry.ts
+    - Go: go/plugins/googlecloud/ and go/plugins/firebase/telemetry.go
+
+See Also:
+    - tracing.py module docstring for detailed architecture documentation
+
+GCP Documentation:
+    Cloud Trace:
+        - Overview: https://cloud.google.com/trace/docs
+        - IAM Roles: https://cloud.google.com/trace/docs/iam
+
+    Cloud Monitoring:
+        - Overview: https://cloud.google.com/monitoring/docs
+        - Quotas & Limits: https://cloud.google.com/monitoring/quotas
+
+    OpenTelemetry GCP:
+        - Python Exporters: https://google-cloud-opentelemetry.readthedocs.io/
+"""
+
+from .tracing import add_gcp_telemetry
+
+__all__ = ['add_gcp_telemetry']

genkit/plugins/google_cloud/telemetry/action.py

@@ -0,0 +1,124 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Action telemetry for GCP.
+
+This module logs input/output for tool and generate actions,
+matching the JavaScript implementation.
+
+Logging:
+    When log_input_and_output=True, logs action inputs and outputs to
+    Cloud Logging with structured attributes for correlation.
+
+Cross-Language Parity:
+    - JavaScript: js/plugins/google-cloud/src/telemetry/action.ts
+    - Go: go/plugins/googlecloud/action.go
+
+See Also:
+    - Cloud Logging: https://cloud.google.com/logging/docs
+    - Structured Logging: https://cloud.google.com/logging/docs/structured-logging
+"""
+
+from __future__ import annotations
+
+import structlog
+from opentelemetry.sdk.trace import ReadableSpan
+
+from .utils import (
+    create_common_log_attributes,
+    extract_outer_feature_name_from_path,
+    to_display_path,
+    truncate,
+    truncate_path,
+)
+
+logger = structlog.get_logger(__name__)
+
+
+class ActionTelemetry:
+    """Telemetry handler for Genkit actions (tools, generate)."""
+
+    def tick(
+        self,
+        span: ReadableSpan,
+        log_input_and_output: bool,
+        project_id: str | None = None,
+    ) -> None:
+        """Record telemetry for an action span.
+
+        Only logs input/output if log_input_and_output is True.
+
+        Args:
+            span: The span to record telemetry for.
+            log_input_and_output: Whether to log input/output.
+            project_id: Optional GCP project ID.
+        """
+        if not log_input_and_output:
+            return
+
+        attrs = span.attributes or {}
+        action_name = str(attrs.get('genkit:name', '')) or '<unknown>'
+        subtype = str(attrs.get('genkit:metadata:subtype', ''))
+
+        # Only log for tools and generate actions
+        if subtype != 'tool' and action_name != 'generate':
+            return
+
+        path = str(attrs.get('genkit:path', '')) or '<unknown>'
+        input_val = truncate(str(attrs.get('genkit:input', '')))
+        output_val = truncate(str(attrs.get('genkit:output', '')))
+        session_id = str(attrs.get('genkit:sessionId', '')) or None
+        thread_name = str(attrs.get('genkit:threadName', '')) or None
+
+        feature_name = extract_outer_feature_name_from_path(path)
+        if not feature_name or feature_name == '<unknown>':
+            feature_name = action_name
+
+        if input_val:
+            self._write_log(span, 'Input', feature_name, path, input_val, project_id, session_id, thread_name)
+        if output_val:
+            self._write_log(span, 'Output', feature_name, path, output_val, project_id, session_id, thread_name)
+
+    def _write_log(
+        self,
+        span: ReadableSpan,
+        tag: str,
+        feature_name: str,
+        qualified_path: str,
+        content: str,
+        project_id: str | None,
+        session_id: str | None,
+        thread_name: str | None,
+    ) -> None:
+        """Write a structured log entry."""
+        path = truncate_path(to_display_path(qualified_path))
+        metadata = {
+            **create_common_log_attributes(span, project_id),
+            'path': path,
+            'qualifiedPath': qualified_path,
+            'featureName': feature_name,
+            'content': content,
+        }
+        if session_id:
+            metadata['sessionId'] = session_id
+        if thread_name:
+            metadata['threadName'] = thread_name
+
+        logger.info(f'{tag}[{path}, {feature_name}]', **metadata)
+
+
+# Singleton instance
+action_telemetry = ActionTelemetry()

genkit/plugins/google_cloud/telemetry/engagement.py

@@ -0,0 +1,170 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Engagement telemetry for GCP.
+
+This module tracks user feedback and acceptance metrics,
+matching the JavaScript implementation.
+
+Metrics Recorded:
+    - genkit/engagement/feedback: Counter for user feedback events
+    - genkit/engagement/acceptance: Counter for user acceptance events
+
+Cross-Language Parity:
+    - JavaScript: js/plugins/google-cloud/src/telemetry/engagement.ts
+    - Go: go/plugins/googlecloud/engagement.go
+
+See Also:
+    - Cloud Monitoring Custom Metrics: https://cloud.google.com/monitoring/custom-metrics
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import structlog
+from opentelemetry import metrics
+from opentelemetry.sdk.trace import ReadableSpan
+
+from genkit.core import GENKIT_VERSION
+
+from .utils import create_common_log_attributes, truncate
+
+logger = structlog.get_logger(__name__)
+
+# Lazy-initialized metrics
+_feedback_counter: metrics.Counter | None = None
+_acceptance_counter: metrics.Counter | None = None
+
+
+def _get_feedback_counter() -> metrics.Counter:
+    """Get or create the user feedback counter."""
+    global _feedback_counter
+    if _feedback_counter is None:
+        meter = metrics.get_meter('genkit')
+        _feedback_counter = meter.create_counter(
+            'genkit/engagement/feedback',
+            description='Counts user feedback events.',
+            unit='1',
+        )
+    return _feedback_counter
+
+
+def _get_acceptance_counter() -> metrics.Counter:
+    """Get or create the user acceptance counter."""
+    global _acceptance_counter
+    if _acceptance_counter is None:
+        meter = metrics.get_meter('genkit')
+        _acceptance_counter = meter.create_counter(
+            'genkit/engagement/acceptance',
+            description='Tracks user acceptance events.',
+            unit='1',
+        )
+    return _acceptance_counter
+
+
+class EngagementTelemetry:
+    """Telemetry handler for user engagement (feedback, acceptance)."""
+
+    def tick(
+        self,
+        span: ReadableSpan,
+        log_input_and_output: bool,
+        project_id: str | None = None,
+    ) -> None:
+        """Record telemetry for a user engagement span.
+
+        Args:
+            span: The span to record telemetry for.
+            log_input_and_output: Whether to log input/output (unused here).
+            project_id: Optional GCP project ID.
+        """
+        attrs: dict[str, Any] = dict(span.attributes) if span.attributes else {}
+        subtype = str(attrs.get('genkit:metadata:subtype', ''))
+
+        if subtype == 'userFeedback':
+            self._write_user_feedback(span, attrs, project_id)
+        elif subtype == 'userAcceptance':
+            self._write_user_acceptance(span, attrs, project_id)
+        else:
+            logger.warning('Unknown user engagement subtype', subtype=subtype)
+
+    def _write_user_feedback(
+        self,
+        span: ReadableSpan,
+        attrs: dict[str, Any],
+        project_id: str | None,
+    ) -> None:
+        """Record user feedback metrics and logs."""
+        name = self._extract_trace_name(attrs)
+        feedback_value = attrs.get('genkit:metadata:feedbackValue')
+        text_feedback = attrs.get('genkit:metadata:textFeedback')
+
+        dimensions = {
+            'name': str(name)[:256],
+            'value': str(feedback_value)[:256] if feedback_value else '',
+            'hasText': str(bool(text_feedback)),
+            'source': 'py',
+            'sourceVersion': GENKIT_VERSION,
+        }
+        _get_feedback_counter().add(1, dimensions)
+
+        metadata: dict[str, Any] = {
+            **create_common_log_attributes(span, project_id),
+            'feedbackValue': feedback_value,
+        }
+        if text_feedback:
+            metadata['textFeedback'] = truncate(str(text_feedback))
+
+        logger.info(f'UserFeedback[{name}]', **metadata)
+
+    def _write_user_acceptance(
+        self,
+        span: ReadableSpan,
+        attrs: dict[str, Any],
+        project_id: str | None,
+    ) -> None:
+        """Record user acceptance metrics and logs."""
+        name = self._extract_trace_name(attrs)
+        acceptance_value = attrs.get('genkit:metadata:acceptanceValue')
+
+        dimensions = {
+            'name': str(name)[:256],
+            'value': str(acceptance_value)[:256] if acceptance_value else '',
+            'source': 'py',
+            'sourceVersion': GENKIT_VERSION,
+        }
+        _get_acceptance_counter().add(1, dimensions)
+
+        metadata = {
+            **create_common_log_attributes(span, project_id),
+            'acceptanceValue': acceptance_value,
+        }
+        logger.info(f'UserAcceptance[{name}]', **metadata)
+
+    def _extract_trace_name(self, attrs: dict[str, Any]) -> str:
+        """Extract the trace name from span attributes."""
+        path = str(attrs.get('genkit:path', ''))
+        if not path or path == '<unknown>':
+            return '<unknown>'
+
+        match = re.search(r'/{(.+)}', path)
+        return match.group(1) if match else '<unknown>'
+
+
+# Singleton instance
+engagement_telemetry = EngagementTelemetry()