genkit-plugin-google-cloud 0.4.0__tar.gz → 0.5.0__tar.gz

genkit_plugin_google_cloud-0.5.0/PARITY_ANALYSIS.md

@@ -0,0 +1,344 @@
+# GCP Telemetry Parity Analysis
+
+This document provides a comprehensive cross-language parity analysis of the Genkit GCP telemetry implementations across JavaScript, Go, and Python, verified against official Google Cloud documentation.
+
+## Summary
+
+| Category | JS | Go | Python | Status |
+|----------|----|----|--------|--------|
+| Configuration Options | ✅ | ✅ | ✅ | **PARITY** |
+| Metrics (names, types) | ✅ | ✅ | ✅ | **PARITY** |
+| Metric Dimensions | ✅ | ✅ | ✅ | **PARITY** (fixed) |
+| Log Formats | ✅ | ✅ | ✅ | **PARITY** |
+| Span Attributes | ✅ | ✅ | ✅ | **PARITY** |
+| Error Handling | ✅ | ✅ | ✅ | **PARITY** |
+| Constants/Limits | ✅ | ✅ | ✅ | **PARITY** (fixed) |
+
+***
+
+## 1. Configuration Options Comparison
+
+### Main Configuration
+
+| Option | JS | Go | Python | GCP Docs | Notes |
+|--------|----|----|--------|----------|-------|
+| `projectId` | ✅ | ✅ | ✅ | ✅ | All support auto-detection |
+| `credentials` | ✅ | ✅ | ✅ | ✅ | ADC fallback |
+| `sampler` | ✅ | ✅ | ✅ | ✅ | OpenTelemetry sampler |
+| `disableMetrics` | ✅ | ✅ | ✅ | N/A | - |
+| `disableTraces` | ✅ | ✅ | ✅ | N/A | - |
+| `disableLoggingInputAndOutput` | ✅ (inverted) | ✅ (inverted) | ✅ (`log_input_and_output`) | N/A | Python uses positive flag |
+| `forceDevExport` | ✅ | ✅ | ✅ | N/A | - |
+| `metricExportIntervalMillis` | ✅ | ✅ | ✅ | ✅ (min 5s) | All enforce 5000ms min |
+| `metricExportTimeoutMillis` | ✅ | ✅ | ✅ | N/A | - |
+| `autoInstrumentation` | ✅ | ❌ | ❌ | N/A | JS-specific |
+| `instrumentations` | ✅ | ❌ | ❌ | N/A | JS-specific |
+
+### Project ID Resolution Order
+
+| Priority | JS | Go | Python | Notes |
+|----------|----|----|--------|-------|
+| 1 | Explicit param | Explicit param | Explicit param | ✅ All match |
+| 2 | - | `FIREBASE_PROJECT_ID` | `FIREBASE_PROJECT_ID` | ⚠️ JS missing |
+| 3 | - | `GOOGLE_CLOUD_PROJECT` | `GOOGLE_CLOUD_PROJECT` | ⚠️ JS missing |
+| 4 | - | `GCLOUD_PROJECT` | `GCLOUD_PROJECT` | ⚠️ JS missing |
+| 5 | ADC | Credentials | Credentials dict | ✅ All match |
+
+**Action Required:** JS should add env var resolution to match Go/Python.
+
+***
+
+## 2. Metrics Comparison
+
+### Generate Metrics
+
+| Metric | JS | Go | Python | GCP Docs |
+|--------|----|----|--------|----------|
+| `genkit/ai/generate/requests` | ✅ Counter | ✅ Counter | ✅ Counter | ✅ |
+| `genkit/ai/generate/latency` | ✅ Histogram | ✅ Histogram | ✅ Histogram | ✅ |
+| `genkit/ai/generate/input/tokens` | ✅ Counter | ✅ Counter | ✅ Counter | ✅ |
+| `genkit/ai/generate/input/characters` | ✅ Counter | ✅ Counter | ✅ Counter | ✅ |
+| `genkit/ai/generate/input/images` | ✅ Counter | ✅ Counter | ✅ Counter | ✅ |
+| `genkit/ai/generate/input/videos` | ❌ | ✅ Counter | ✅ Counter | ✅ |
+| `genkit/ai/generate/input/audio` | ❌ | ✅ Counter | ✅ Counter | ✅ |
+| `genkit/ai/generate/output/tokens` | ✅ Counter | ✅ Counter | ✅ Counter | ✅ |
+| `genkit/ai/generate/output/characters` | ✅ Counter | ✅ Counter | ✅ Counter | ✅ |
+| `genkit/ai/generate/output/images` | ✅ Counter | ✅ Counter | ✅ Counter | ✅ |
+| `genkit/ai/generate/output/videos` | ❌ | ✅ Counter | ✅ Counter | ✅ |
+| `genkit/ai/generate/output/audio` | ❌ | ✅ Counter | ✅ Counter | ✅ |
+| `genkit/ai/generate/thinking/tokens` | ✅ Counter | ✅ Counter | ✅ Counter | ✅ |
+
+**Gap Found:** JS is missing video and audio metrics that Go and Python have.
+
+### Feature Metrics
+
+| Metric | JS | Go | Python | Status |
+|--------|----|----|--------|--------|
+| `genkit/feature/requests` | ✅ Counter | ✅ Counter | ✅ Counter | ✅ PARITY |
+| `genkit/feature/latency` | ✅ Histogram | ✅ Histogram | ✅ Histogram | ✅ PARITY |
+
+### Path Metrics
+
+| Metric | JS | Go | Python | Status |
+|--------|----|----|--------|--------|
+| `genkit/feature/path/requests` | ✅ Counter | ✅ Counter | ✅ Counter | ✅ PARITY |
+| `genkit/feature/path/latency` | ✅ Histogram | ✅ Histogram | ✅ Histogram | ✅ PARITY |
+
+### Engagement Metrics
+
+| Metric | JS | Go | Python | Status |
+|--------|----|----|--------|--------|
+| `genkit/engagement/feedback` | ✅ Counter | ✅ Counter | ✅ Counter | ✅ PARITY |
+| `genkit/engagement/acceptance` | ✅ Counter | ✅ Counter | ✅ Counter | ✅ PARITY |
+
+***
+
+## 3. Metric Dimensions Comparison
+
+### Generate Metric Dimensions
+
+| Dimension | JS | Go | Python | Notes |
+|-----------|----|----|--------|-------|
+| `modelName` | ✅ (1024 chars) | ✅ (1024 chars) | ✅ (1024 chars) | ✅ PARITY (fixed) |
+| `featureName` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `path` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `status` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `error` | ✅ (on failure) | ✅ (on failure) | ✅ (on failure) | ✅ PARITY |
+| `source` | `"ts"` | `"go"` | `"py"` | ✅ Correctly different |
+| `sourceVersion` | ✅ | ✅ | ✅ | ✅ PARITY |
+
+### Feature Metric Dimensions
+
+| Dimension | JS | Go | Python | Notes |
+|-----------|----|----|--------|-------|
+| `name` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `status` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `error` | ✅ (on failure) | ✅ (on failure) | ✅ (on failure) | ✅ PARITY |
+| `source` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `sourceVersion` | ✅ | ✅ | ✅ | ✅ PARITY |
+
+### Path Metric Dimensions
+
+| Dimension | JS | Go | Python | Notes |
+|-----------|----|----|--------|-------|
+| `featureName` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `status` | ✅ (always "failure") | ✅ | ✅ | ✅ PARITY |
+| `error` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `path` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `source` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `sourceVersion` | ✅ | ✅ | ✅ | ✅ PARITY |
+
+### Engagement Dimensions
+
+| Dimension | JS | Go | Python | Notes |
+|-----------|----|----|--------|-------|
+| `name` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `value` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `hasText` (feedback) | ✅ | ✅ | ✅ | ✅ PARITY |
+| `source` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `sourceVersion` | ✅ | ✅ | ✅ | ✅ PARITY |
+
+***
+
+## 4. Constants and Limits Comparison
+
+### Content Limits
+
+| Constant | JS | Go | Python | GCP Docs | Notes |
+|----------|----|----|--------|----------|-------|
+| Max log content | 128,000 | 128,000 | 128,000 | N/A | ✅ PARITY |
+| Max path length | 4,096 | 4,096 | 4,096 | N/A | ✅ PARITY |
+| Error name truncation | 1,024 | - | 1,024 | N/A | ✅ PARITY |
+| Error message truncation | 4,096 | - | 4,096 | N/A | ✅ PARITY |
+| Error stack truncation | 32,768 | - | 32,768 | N/A | ✅ PARITY |
+| Metric dimension max | 256 | - | 256 | ✅ (256) | ✅ PARITY |
+| Model name truncation | 1,024 | 1,024 | 256 | N/A | ⚠️ Python shorter |
+
+### Timing Constants
+
+| Constant | JS | Go | Python | GCP Docs | Notes |
+|----------|----|----|--------|----------|-------|
+| Min metric interval | 5,000ms | 5,000ms | 5,000ms | ✅ 5,000ms | ✅ PARITY |
+| Dev metric interval | 5,000ms | 5,000ms | 5,000ms | N/A | ✅ PARITY |
+| Prod metric interval | - | 300,000ms | 300,000ms | N/A | JS uses custom |
+| Default metric interval | - | - | 60,000ms | N/A | Python specific |
+| Start time adjustment | 1ms | - | 1ms | N/A | ✅ PARITY |
+
+***
+
+## 5. Span Attributes Comparison
+
+### Input Attributes (Read)
+
+| Attribute | JS | Go | Python | Notes |
+|-----------|----|----|--------|-------|
+| `genkit:type` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:metadata:subtype` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:isRoot` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:name` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:path` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:input` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:output` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:state` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:isFailureSource` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:sessionId` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:threadName` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:metadata:flow:name` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:metadata:feedbackValue` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:metadata:textFeedback` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:metadata:acceptanceValue` | ✅ | ✅ | ✅ | ✅ PARITY |
+
+### Output Attributes (Written)
+
+| Attribute | JS | Go | Python | Notes |
+|-----------|----|----|--------|-------|
+| `genkit:input` → `<redacted>` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:output` → `<redacted>` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `/http/status_code` = "599" | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:failedSpan` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:failedPath` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:feature` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:model` | ✅ | ✅ | ✅ | ✅ PARITY |
+| `genkit:rootState` | ✅ | ✅ | ✅ | ✅ PARITY |
+| Label normalization (`:` → `/`) | ✅ | ✅ | ✅ | ✅ PARITY |
+
+***
+
+## 6. Log Message Format Comparison
+
+### Generate Logs
+
+| Log Type | JS Format | Go Format | Python Format | Status |
+|----------|-----------|-----------|---------------|--------|
+| Config | `Config[{path}, {model}]` | `[genkit] Config[{path}, {model}]` | `Config[{path}, {model}]` | ⚠️ Go prefix |
+| Input | `Input[{path}, {model}] (part X of Y in message M of N)` | Same | Same | ✅ PARITY |
+| Output | `Output[{path}, {model}] (part X of Y)` | Same | Same | ✅ PARITY |
+
+### Feature Logs
+
+| Log Type | JS Format | Go Format | Python Format | Status |
+|----------|-----------|-----------|---------------|--------|
+| Input | `Input[{path}, {name}]` | `[genkit] Input[...]` | `Input[{path}, {name}]` | ⚠️ Go prefix |
+| Output | `Output[{path}, {name}]` | `[genkit] Output[...]` | `Output[{path}, {name}]` | ⚠️ Go prefix |
+
+### Error Logs
+
+| Log Type | JS Format | Go Format | Python Format | Status |
+|----------|-----------|-----------|---------------|--------|
+| Error | `Error[{path}, {error}]` | `[genkit] Error[...]` | `Error[{path}, {error}]` | ⚠️ Go prefix |
+
+### Engagement Logs
+
+| Log Type | JS Format | Go Format | Python Format | Status |
+|----------|-----------|-----------|---------------|--------|
+| Feedback | `UserFeedback[{name}]` | `[genkit] UserFeedback[...]` | `UserFeedback[{name}]` | ⚠️ Go prefix |
+| Acceptance | `UserAcceptance[{name}]` | `[genkit] UserAcceptance[...]` | `UserAcceptance[{name}]` | ⚠️ Go prefix |
+
+**Note:** Go adds `[genkit]` prefix to all logs. This is acceptable variation for log filtering.
+
+***
+
+## 7. GCP Log Correlation Attributes
+
+Per [Cloud Logging documentation](https://cloud.google.com/logging/docs/structured-logging):
+
+| Attribute | JS | Go | Python | GCP Docs | Status |
+|-----------|----|----|--------|----------|--------|
+| `logging.googleapis.com/trace` | ✅ | ✅ | ✅ | ✅ Required | ✅ PARITY |
+| `logging.googleapis.com/spanId` | ✅ | ✅ | ✅ | ✅ Required | ✅ PARITY |
+| `logging.googleapis.com/trace_sampled` | ✅ | ✅ | ✅ | ✅ Required | ✅ PARITY |
+
+Format: `projects/{PROJECT_ID}/traces/{TRACE_ID}`
+
+***
+
+## 8. IAM Roles Required
+
+Per GCP documentation:
+
+| Service | Role | JS | Go | Python | GCP Docs |
+|---------|------|----|----|--------|----------|
+| Cloud Trace | `roles/cloudtrace.agent` | ✅ | ✅ | ✅ | ✅ |
+| Cloud Monitoring | `roles/monitoring.metricWriter` | ✅ | ✅ | ✅ | ✅ |
+| Cloud Monitoring | `roles/telemetry.metricsWriter` | - | - | ✅ | ✅ |
+| Cloud Logging | `roles/logging.logWriter` | ✅ | - | - | ✅ |
+
+***
+
+## 9. Telemetry Dispatch Logic Comparison
+
+| Condition | JS | Go | Python | Status |
+|-----------|----|----|--------|--------|
+| All genkit spans → paths.tick() | ✅ | ✅ | ✅ | ✅ PARITY |
+| isRoot → features.tick() | ✅ | ✅ | ✅ | ✅ PARITY |
+| isRoot → set rootState | ✅ | ✅ | ✅ | ✅ PARITY |
+| action + model (non-root) → generate.tick() | ✅ | ✅ | ✅ | ✅ PARITY |
+| action/flow/flowStep/util (non-root) → action.tick() | ✅ | ✅ | ✅ | ✅ PARITY |
+| userEngagement → engagement.tick() | ✅ | ✅ | ✅ | ✅ PARITY |
+
+***
+
+## 10. Issues Found and Recommendations
+
+### High Priority
+
+1. **~~Python: Model name truncation too short~~** ✅ FIXED
+   * \~~Current: 256 chars~~
+   * \~~Should be: 1024 chars (matching JS/Go)~~
+   * \~~File: `generate.py`~~
+   * **Status:** Fixed - now uses 1024 chars for modelName dimension
+
+### Medium Priority
+
+2. **JS: Missing video/audio metrics**
+   * Missing: `input/videos`, `input/audio`, `output/videos`, `output/audio`
+   * Go and Python have these metrics
+
+3. **JS: Missing env var project ID resolution**
+   * Should add: `FIREBASE_PROJECT_ID`, `GOOGLE_CLOUD_PROJECT`, `GCLOUD_PROJECT`
+
+### Low Priority (Acceptable Variations)
+
+4. **Go: Log message prefix**
+   * Go adds `[genkit]` prefix to all logs
+   * Acceptable for filtering purposes
+
+5. **Python: Positive flag for I/O logging**
+   * Python: `log_input_and_output=True` enables logging
+   * JS/Go: `disableLoggingInputAndOutput=False` enables logging
+   * Both achieve same result, Python's is more intuitive
+
+***
+
+## 11. GCP Documentation References
+
+* Cloud Trace Overview: https://cloud.google.com/trace/docs
+* Cloud Trace IAM: https://cloud.google.com/trace/docs/iam
+* Cloud Monitoring Overview: https://cloud.google.com/monitoring/docs
+* Cloud Monitoring Quotas: https://cloud.google.com/monitoring/quotas
+* Cloud Logging Structured: https://cloud.google.com/logging/docs/structured-logging
+* Log-Trace Correlation: https://cloud.google.com/trace/docs/trace-log-integration
+* Metric Naming: https://cloud.google.com/monitoring/api/v3/naming-conventions
+* Custom Metrics: https://cloud.google.com/monitoring/custom-metrics
+* OpenTelemetry GCP: https://google-cloud-opentelemetry.readthedocs.io/
+
+***
+
+## 12. Verification Checklist
+
+* \[x] All metric names match across implementations
+* \[x] All metric types (Counter/Histogram) match
+* \[x] Span attributes read/written match
+* \[x] Log correlation attributes follow GCP spec
+* \[x] Minimum metric interval enforced (5000ms)
+* \[x] PII redaction implemented
+* \[x] Error span marking (`/http/status_code: 599`)
+* \[x] Label normalization (`:` → `/`)
+* \[x] Start time adjustment for DELTA→CUMULATIVE
+* \[x] Model name truncation (Python fixed to 1024 chars)
+* \[ ] Video/audio metrics (JS needs addition - tracked separately)
+
+***
+
+*Last updated: 2026-01-28*
+*Analyzed versions: JS (latest), Go (latest), Python (latest)*

{genkit_plugin_google_cloud-0.4.0 → genkit_plugin_google_cloud-0.5.0}/PKG-INFO

@@ -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/pyproject.toml

@@ -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
+
+[project]
+authors = [{ name = "Google" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Environment :: Web Environment",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+  "License :: OSI Approved :: Apache Software License",
+]
+dependencies = [
+  "genkit",
+  "opentelemetry-exporter-gcp-trace>=1.9.0",
+  "opentelemetry-exporter-gcp-monitoring>=1.9.0",
+  "strenum>=0.4.15; python_version < '3.11'",
+]
+description = "Genkit Google Cloud Plugin"
+keywords = [
+  "genkit",
+  "ai",
+  "llm",
+  "machine-learning",
+  "artificial-intelligence",
+  "generative-ai",
+  "google-cloud",
+  "gcp",
+  "cloud-trace",
+  "telemetry",
+]
+license = "Apache-2.0"
+name = "genkit-plugin-google-cloud"
+readme = "README.md"
+requires-python = ">=3.10"
+version = "0.5.0"
+
+[project.urls]
+"Bug Tracker"   = "https://github.com/firebase/genkit/issues"
+"Documentation" = "https://firebase.google.com/docs/genkit"
+"Homepage"      = "https://github.com/firebase/genkit"
+"Repository"    = "https://github.com/firebase/genkit/tree/main/py"
+
+[build-system]
+build-backend = "hatchling.build"
+requires      = ["hatchling"]
+
+[tool.hatch.build.targets.wheel]
+only-include = ["src/genkit/plugins/google_cloud"]
+sources = ["src"]

genkit_plugin_google_cloud-0.5.0/src/genkit/plugins/google_cloud/__init__.py

@@ -0,0 +1,155 @@
+# 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 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:
+    """Get the package name for the Google Cloud plugin.
+
+    Returns:
+        The fully qualified package name as a string.
+    """
+    return 'genkit.plugins.google_cloud'
+
+
+__all__ = ['add_gcp_telemetry', 'package_name']