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

genkit/plugins/google_cloud/telemetry/utils.py

@@ -0,0 +1,217 @@
+# 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
+
+"""Utility functions for GCP telemetry.
+
+This module provides utility functions used by the telemetry handlers,
+matching the JavaScript implementation in js/plugins/google-cloud/src/utils.ts.
+
+Functions:
+    - truncate(): Limit string length for log content
+    - truncate_path(): Limit Genkit path string length
+    - to_display_path(): Convert internal path to display format
+    - extract_outer_feature_name_from_path(): Get root feature from path
+    - create_common_log_attributes(): Build log attributes dict
+    - extract_error_*(): Error info extraction helpers
+
+See Also:
+    - Cloud Logging Limits: https://cloud.google.com/logging/quotas
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.trace import TraceFlags
+
+# Constants matching JS implementation
+MAX_LOG_CONTENT_CHARS = 128_000
+MAX_PATH_CHARS = 4096
+
+
+def truncate(text: str | None, limit: int = MAX_LOG_CONTENT_CHARS) -> str:
+    """Truncate text to a maximum length.
+
+    Args:
+        text: The text to truncate.
+        limit: Maximum length (default: 128,000 chars).
+
+    Returns:
+        The truncated text or empty string if None.
+    """
+    if not text:
+        return ''
+    return text[:limit]
+
+
+def truncate_path(path: str) -> str:
+    """Truncate a path to the maximum path length.
+
+    Args:
+        path: The path to truncate.
+
+    Returns:
+        The truncated path.
+    """
+    return truncate(path, MAX_PATH_CHARS)
+
+
+def extract_outer_flow_name_from_path(path: str) -> str:
+    """Extract the outer flow name from a Genkit path.
+
+    Args:
+        path: The Genkit path (e.g., '/{myFlow,t:flow}').
+
+    Returns:
+        The flow name or '<unknown>'.
+    """
+    if not path or path == '<unknown>':
+        return '<unknown>'
+
+    match = re.search(r'/{(.+),t:flow}', path)
+    return match.group(1) if match else '<unknown>'
+
+
+def extract_outer_feature_name_from_path(path: str) -> str:
+    """Extract the outer feature name from a Genkit path.
+
+    Extracts the first feature name from paths like:
+    '/{myFlow,t:flow}/{myStep,t:flowStep}/{googleai/gemini-pro,t:action,s:model}'
+    Returns 'myFlow'.
+
+    Args:
+        path: The Genkit path.
+
+    Returns:
+        The feature name or '<unknown>'.
+    """
+    if not path or path == '<unknown>':
+        return '<unknown>'
+
+    parts = path.split('/')
+    if len(parts) < 2:
+        return '<unknown>'
+
+    first = parts[1]
+    match = re.match(r'\{(.+),t:(flow|action|prompt|dotprompt|helper)', first)
+    return match.group(1) if match else '<unknown>'
+
+
+def extract_error_name(events: list[Any]) -> str | None:
+    """Extract the error name from span events.
+
+    Args:
+        events: List of span events.
+
+    Returns:
+        The error type name or None.
+    """
+    for event in events:
+        if event.name == 'exception':
+            attrs = event.attributes or {}
+            error_type = attrs.get('exception.type')
+            if error_type:
+                return truncate(str(error_type), 1024)
+    return None
+
+
+def extract_error_message(events: list[Any]) -> str | None:
+    """Extract the error message from span events.
+
+    Args:
+        events: List of span events.
+
+    Returns:
+        The error message or None.
+    """
+    for event in events:
+        if event.name == 'exception':
+            attrs = event.attributes or {}
+            error_msg = attrs.get('exception.message')
+            if error_msg:
+                return truncate(str(error_msg), 4096)
+    return None
+
+
+def extract_error_stack(events: list[Any]) -> str | None:
+    """Extract the error stack trace from span events.
+
+    Args:
+        events: List of span events.
+
+    Returns:
+        The stack trace or None.
+    """
+    for event in events:
+        if event.name == 'exception':
+            attrs = event.attributes or {}
+            stack = attrs.get('exception.stacktrace')
+            if stack:
+                return truncate(str(stack), 32_768)
+    return None
+
+
+def create_common_log_attributes(span: ReadableSpan, project_id: str | None = None) -> dict[str, Any]:
+    """Create common log attributes for GCP structured logging.
+
+    These attributes link logs to traces in Google Cloud.
+
+    Args:
+        span: The span to extract context from.
+        project_id: Optional GCP project ID.
+
+    Returns:
+        Dictionary with logging.googleapis.com attributes.
+    """
+    span_context = span.context
+    if span_context is None:
+        return {}
+    is_sampled = bool(span_context.trace_flags & TraceFlags.SAMPLED)
+
+    return {
+        'logging.googleapis.com/spanId': format(span_context.span_id, '016x'),
+        'logging.googleapis.com/trace': f'projects/{project_id}/traces/{format(span_context.trace_id, "032x")}',
+        'logging.googleapis.com/trace_sampled': '1' if is_sampled else '0',
+    }
+
+
+def to_display_path(qualified_path: str) -> str:
+    """Convert a qualified Genkit path to a display path.
+
+    Simplifies paths like '/{myFlow,t:flow}/{step,t:flowStep}' to 'myFlow/step'.
+
+    Args:
+        qualified_path: The full Genkit path.
+
+    Returns:
+        A simplified display path.
+    """
+    if not qualified_path:
+        return ''
+
+    # Extract names from path segments like '{name,t:type}'
+    parts = []
+    for segment in qualified_path.split('/'):
+        if segment.startswith('{'):
+            match = re.match(r'\{([^,}]+)', segment)
+            if match:
+                parts.append(match.group(1))
+        elif segment:
+            parts.append(segment)
+
+    return '/'.join(parts)

{genkit_plugin_google_cloud-0.4.0.dist-info → genkit_plugin_google_cloud-0.5.0.dist-info}/METADATA

@@ -1,10 +1,15 @@
 Metadata-Version: 2.4
 Name: genkit-plugin-google-cloud
-Version: 0.4.0
+Version: 0.5.0
 Summary: Genkit Google Cloud Plugin
+Project-URL: Bug Tracker, https://github.com/firebase/genkit/issues
+Project-URL: Documentation, https://firebase.google.com/docs/genkit
+Project-URL: Homepage, https://github.com/firebase/genkit
+Project-URL: Repository, https://github.com/firebase/genkit/tree/main/py
 Author: Google
-License: Apache-2.0
+License-Expression: Apache-2.0
 License-File: LICENSE
+Keywords: ai,artificial-intelligence,cloud-trace,gcp,generative-ai,genkit,google-cloud,llm,machine-learning,telemetry
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Environment :: Web Environment
@@ -17,10 +22,13 @@ 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: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: genkit
+Requires-Dist: opentelemetry-exporter-gcp-monitoring>=1.9.0
 Requires-Dist: opentelemetry-exporter-gcp-trace>=1.9.0
 Requires-Dist: strenum>=0.4.15; python_version < '3.11'
 Description-Content-Type: text/markdown

genkit_plugin_google_cloud-0.5.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+genkit/plugins/google_cloud/__init__.py,sha256=xGtaLGbJN3h3_M7j-puTVhBBt5tKwQNa_TzuZ35gYbU,13097
+genkit/plugins/google_cloud/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+genkit/plugins/google_cloud/telemetry/__init__.py,sha256=fHABRo0Wttj-1SxJyT0dESw7xo-42lop45OZQZsgrIA,3478
+genkit/plugins/google_cloud/telemetry/action.py,sha256=CTkw2wNPPHZ3Yx1IHqMbC5J1kHINqx3J3hKgI7XqAeM,4033
+genkit/plugins/google_cloud/telemetry/engagement.py,sha256=XUj3px7mpEWTYuaGP6LW63KbFVBVFiyIsFf6aG7BIoQ,5626
+genkit/plugins/google_cloud/telemetry/feature.py,sha256=M-ChpbFXaVrqj1NhpY8JrtPoJ3WtY2LxBVQv1RoDhTA,6126
+genkit/plugins/google_cloud/telemetry/generate.py,sha256=2Jihlip8zI2cTjJPvg02ddguQREYHjiYWSazSeEL7aQ,22800
+genkit/plugins/google_cloud/telemetry/metrics.py,sha256=b-WLbSDJ5kVpklcUVjmaA4roLui7FYn-jYViNpn144w,7554
+genkit/plugins/google_cloud/telemetry/path.py,sha256=pqR_imoFVqYa7d_l1kWCLrZkSXa8hDk5lmqUdDahwmE,5017
+genkit/plugins/google_cloud/telemetry/tracing.py,sha256=8fR1HB_qrbdLGNlDHTgGbzs6v6nV5pJfRcjwWDiTeJ0,44002
+genkit/plugins/google_cloud/telemetry/utils.py,sha256=z3q2czj_q4-la57KNAJG6PsoHpHwKEfcRrU_zay_hdw,6176
+genkit_plugin_google_cloud-0.5.0.dist-info/METADATA,sha256=_9pJFm5TMXOoWE5WDVTxNoWr_0VZd1-8q_OWhMUsvW0,1712
+genkit_plugin_google_cloud-0.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+genkit_plugin_google_cloud-0.5.0.dist-info/licenses/LICENSE,sha256=bsvE5_qSn_2LH2G-haMvT_AoIeINhX6fvzZTlyq2xJY,11340
+genkit_plugin_google_cloud-0.5.0.dist-info/RECORD,,

{genkit_plugin_google_cloud-0.4.0.dist-info → genkit_plugin_google_cloud-0.5.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

genkit_plugin_google_cloud-0.4.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-genkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-genkit/plugins/google_cloud/__init__.py,sha256=hslI9NDSXVZ2VpUblsGa1QBYPTQd0hVXF2sPfpSIpdk,886
-genkit/plugins/google_cloud/telemetry/tracing.py,sha256=we3m0a7mVK58swN6hE_JNNjLPZdh5ykPBp_Dynr7fMU,4046
-genkit/plugins/google_cloud/__init__.py,sha256=hslI9NDSXVZ2VpUblsGa1QBYPTQd0hVXF2sPfpSIpdk,886
-genkit/plugins/google_cloud/telemetry/tracing.py,sha256=we3m0a7mVK58swN6hE_JNNjLPZdh5ykPBp_Dynr7fMU,4046
-genkit_plugin_google_cloud-0.4.0.dist-info/METADATA,sha256=vPPyeS175AFtU2KliCwTf9GsQKWONLFklboNv-AEhCk,1177
-genkit_plugin_google_cloud-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-genkit_plugin_google_cloud-0.4.0.dist-info/licenses/LICENSE,sha256=bsvE5_qSn_2LH2G-haMvT_AoIeINhX6fvzZTlyq2xJY,11340
-genkit_plugin_google_cloud-0.4.0.dist-info/RECORD,,