diff --git a/.github/instructions/instrumentation-genai.instructions.md b/.github/instructions/instrumentation-genai.instructions.md index b62bea94b4..7211ecbc8a 100644 --- a/.github/instructions/instrumentation-genai.instructions.md +++ b/.github/instructions/instrumentation-genai.instructions.md @@ -2,65 +2,14 @@ applyTo: "instrumentation-genai/**" --- -Review rules for PRs touching `instrumentation-genai/**`. Flag violations with a link to the rule. +Review rules for PRs touching `instrumentation-genai/**`. -These rules are additive to -[`instrumentation.instructions.md`](instrumentation.instructions.md), which applies to all -instrumentation packages. +GenAI instrumentations are no longer developed in this repository. They live in +[opentelemetry-python-genai](https://github.com/open-telemetry/opentelemetry-python-genai), +which is where new instrumentations, features, and bug fixes go. Everything left under +`instrumentation-genai/` is deprecated, receives security patches only, and will be removed from +this repository in the future. -## 1. Scope of `instrumentation-genai/` - -Only for: - -- Generative AI inference providers, -- Agentic frameworks, -- Libraries directly supporting the above (e.g., MCP, GenAI protocols). - -Database clients (including vector DBs used outside a GenAI-specific client) and CLI libs belong -in `instrumentation/`, not here. - -## 2. GenAI component ownership - -See [`CONTRIBUTING.md#guideline-for-genai-instrumentations`](../../CONTRIBUTING.md#guideline-for-genai-instrumentations) -for GenAI-specific maintenance expectations on top of the general -[instrumentation checklist](../../CONTRIBUTING.md#guideline-for-instrumentations). - -## 3. Telemetry and configuration via `opentelemetry-util-genai` - -- Spans, logs, metrics, and events must go through `opentelemetry-util-genai`. Direct use of - `Tracer`, `Meter`, `Logger`, or event APIs is not allowed. -- Content capture, hooks, and other cross-cutting configuration are owned by the util. - Instrumentations must not introduce their own env vars, settings, or hook interfaces. -- Message content, prompts, and tool call arguments must only be set through the util's content - capture path — never as unconditional span/log attributes. -- Adding attributes to invocations produced by the util is fine. -- If a capability is missing in `opentelemetry-util-genai`, land it in the util first. - -## 4. GenAI semantic conventions - -- Attributes, spans, events, and metrics must match the - [GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/gen-ai). -- `gen_ai.*` attribute names must come from - `opentelemetry.semconv._incubating.attributes.gen_ai_attributes`. -- For attributes with a well-known value set, use the generated enum from the same module - (e.g. `GenAiOutputTypeValues` for `gen_ai.output.type`) instead of string literals. - -## 5. Tests - -- Use recorded VCR cassettes for provider calls. No live-key-only tests; skipping on missing key - is not acceptable. -- Cover streaming and non-streaming variants when both exist. -- For error scenarios, at minimum include: provider error / endpoint unavailable, stream - interrupted by network, stream closed early by the caller. - -## 6. Examples - -New instrumentations must ship a minimal example under the package's `examples/`, with both a -`manual/` and a `zero-code/` (auto-instrumentation) variant. - -## 7. PR description - -- Cover which part of the GenAI semconv the change implements or follows (when applicable) and - how instrumentations should consume it. - -See also [AGENTS.md](../../AGENTS.md) for general repo rules. +Reject PRs that add new instrumentations here, add features, or fix non-security bugs, and point +the author to the `opentelemetry-python-genai` repo. See +[instrumentation-genai/AGENTS.md](../../instrumentation-genai/AGENTS.md). diff --git a/.github/instructions/instrumentation.instructions.md b/.github/instructions/instrumentation.instructions.md index 360f1cc797..bd7f1b7dcd 100644 --- a/.github/instructions/instrumentation.instructions.md +++ b/.github/instructions/instrumentation.instructions.md @@ -5,7 +5,18 @@ applyTo: "{instrumentation,instrumentation-genai}/**" Review rules for PRs touching `instrumentation/**` and `instrumentation-genai/**`. Flag violations with a link to the rule. -## 0. Reviewer mindset +## 0. GenAI instrumentations maintained elsewhere + +GenAI instrumentations are developed and released from the +[opentelemetry-python-genai](https://github.com/open-telemetry/opentelemetry-python-genai) +repository. Everything left under `instrumentation-genai/` here is deprecated, receives security +patches only, and will be removed from this repository in the future. + +Reject PRs that add features or fix non-security bugs in these packages and point the author to +the `opentelemetry-python-genai` repo. See +[instrumentation-genai/AGENTS.md](../../instrumentation-genai/AGENTS.md). + +## 1. Reviewer mindset Review as long-term maintainer. @@ -18,7 +29,7 @@ For new instrumentations, consult upstream library docs and judge: For changes to existing instrumentations: prefer back-compat. Break users only for a real reason; prefer opt-in or additive. Breaking changes need explicit justification in the PR. -## 1. Component ownership & maintenance commitment +## 2. Component ownership & maintenance commitment - New instrumentations must add an entry under the correct folder in [`component_owners.yml`](../component_owners.yml) in the same PR. Contributor must commit to @@ -26,7 +37,7 @@ prefer opt-in or additive. Breaking changes need explicit justification in the P [Expectations from contributors](../../CONTRIBUTING.md#expectations-from-contributors) and the general [instrumentation checklist](../../CONTRIBUTING.md#guideline-for-instrumentations). -## 2. Semantic conventions +## 3. Semantic conventions - Attribute names must come from the semconv attribute modules, not hardcoded strings. Use the module matching the namespace under `opentelemetry.semconv` (e.g. `server_attributes`, @@ -35,13 +46,13 @@ prefer opt-in or additive. Breaking changes need explicit justification in the P modules instead of string literals. - If a signal is not in semconv, wait until semconv lands. -## 3. Exception handling +## 4. Exception handling - When catching exceptions from the underlying library to record telemetry, always re-raise the original exception unmodified. - Do not raise **new** exceptions in instrumentation/telemetry code. -## 4. Tests +## 5. Tests - For every public API instrumented, cover sync/async variants when both exist. - Cover happy path and error scenarios. diff --git a/.github/workflows/package-prepare-release.yml b/.github/workflows/package-prepare-release.yml index 1606ad3369..d3d2b8da22 100644 --- a/.github/workflows/package-prepare-release.yml +++ b/.github/workflows/package-prepare-release.yml @@ -10,8 +10,6 @@ on: - opentelemetry-resource-detector-azure - opentelemetry-resourcedetector-gcp - opentelemetry-sdk-extension-aws - - opentelemetry-instrumentation-vertexai - - opentelemetry-instrumentation-google-genai - opentelemetry-util-genai description: 'Package to be released' required: true diff --git a/AGENTS.md b/AGENTS.md index be83c19619..261d794f19 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,7 +34,8 @@ comment - not in the PR description. ## Structure - `instrumentation/` - instrumentation packages (Flask, Django, FastAPI, gRPC, databases, etc.) -- `instrumentation-genai/` - GenAI instrumentations (OpenAI, Google GenAI, Vertex AI, etc.) +- `instrumentation-genai/` - GenAI instrumentations; deprecated and no longer developed here, see + [instrumentation-genai/AGENTS.md](instrumentation-genai/AGENTS.md) - `util/` - shared utilities (`util-http`, `util-genai`) - `exporter/` - custom exporters - `propagator/` - context propagators diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9e06e7dcd3..3d9b09b44b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,7 @@ If you are using AI agents to assist with contributions, please read [AGENTS.md] - [Guideline for instrumentations](#guideline-for-instrumentations) - [Update supported instrumentation package versions](#update-supported-instrumentation-package-versions) - [Guideline for GenAI instrumentations](#guideline-for-genai-instrumentations) - - [Get Involved](#get-involved) + - [Get Involved](#get-involved) - [Expectations from contributors](#expectations-from-contributors) - [Guidelines for native OpenTelemetry instrumentation](#guidelines-for-native-opentelemetry-instrumentation) - [Updating supported Python versions](#updating-supported-python-versions) @@ -428,15 +428,17 @@ Example PRs: [#2976](https://github.com/open-telemetry/opentelemetry-python-cont ## Guideline for GenAI instrumentations -Instrumentations that relate to [Generative AI](https://opentelemetry.io/docs/specs/semconv/gen-ai/) systems will be placed in the [instrumentation-genai](./instrumentation-genai) folder. This section covers contributions related to those instrumentations. Please note that the [guidelines for instrumentations](#guideline-for-instrumentations) and [expectations from contributors](#expectations-from-contributors) still apply. +[Generative AI](https://opentelemetry.io/docs/specs/semconv/gen-ai/) instrumentations are **no longer developed in this repository**. They live in the [opentelemetry-python-genai](https://github.com/open-telemetry/opentelemetry-python-genai) repository - please contribute new instrumentations, features, bug fixes, and issues there. -### Get Involved +The packages still present in the [instrumentation-genai](./instrumentation-genai) folder are deprecated, receive security patches only, and will be removed from this repository in the future. + +## Get Involved * Reviewing PRs: If you would like to be tagged as reviewer in new PRs related to these instrumentations, please submit a PR to add your GitHub handle to [component_owners.yml](https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/.github/component_owners.yml) under the corresponding instrumentation folder(s). * Approving PRs: If you would like to be able to approve PRs related to these instrumentations, you must join [opentelemetry-python-contrib-approvers](https://github.com/orgs/open-telemetry/teams/opentelemetry-python-contrib-approvers) team. Please ask one of the [Python contrib maintainers](https://github.com/orgs/open-telemetry/teams/opentelemetry-python-contrib-maintainers) to be accepted into the team. -* Tracking and Creating Issues: For tracking issues related to Generative AI, please filter or add the label [gen-ai](https://github.com/open-telemetry/opentelemetry-python-contrib/issues?q=is%3Aopen+is%3Aissue+label%3Agen-ai) when creating or searching issues. If you do not see an issue related to an instrumentation you would like to contribute to, please create a new tracking issue so the community is aware of its progress. +* Tracking and Creating Issues: If you do not see an issue related to an instrumentation you would like to contribute to, please create a new tracking issue so the community is aware of its progress. ## Expectations from contributors diff --git a/docs/index.rst b/docs/index.rst index 1ac7f8179c..b1951e7a46 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -50,7 +50,6 @@ install cd opentelemetry-python-contrib pip install -e ./instrumentation/opentelemetry-instrumentation-flask pip install -e ./instrumentation/opentelemetry-instrumentation-botocore - pip install -e ./instrumentation-genai/opentelemetry-instrumentation-openai-v2 pip install -e ./sdk-extension/opentelemetry-sdk-extension-aws pip install -e ./resource/opentelemetry-resource-detector-containerid diff --git a/instrumentation-genai/AGENTS.md b/instrumentation-genai/AGENTS.md index 9cde4973ad..1f43f84d7e 100644 --- a/instrumentation-genai/AGENTS.md +++ b/instrumentation-genai/AGENTS.md @@ -1,112 +1,12 @@ # GenAI Instrumentation — Agent and Contributor Guidelines -Instrumentation packages here wrap specific libraries (OpenAI, Google GenAI, etc.) and bridge -them to the shared telemetry layer in `util/opentelemetry-util-genai`. +**GenAI instrumentations are no longer developed in this repository.** They live in +[opentelemetry-python-genai](https://github.com/open-telemetry/opentelemetry-python-genai), +which is where new instrumentations, features, and bug fixes go. -These rules are additive to the shared instrumentation rules in the repo-root -[AGENTS.md](../AGENTS.md). +The packages still present under this directory are deprecated, receive security patches only, +and will be removed from this repository in the future. -## 0. Instrumentations Maintained Elsewhere - -Development and releases for these GenAI instrumentations have moved to the -[opentelemetry-python-genai](https://github.com/open-telemetry/opentelemetry-python-genai) -repository. Direct new development and fixes there, not here: - -- `opentelemetry-instrumentation-genai-anthropic` (anthropic) -- `opentelemetry-instrumentation-genai-claude-agent-sdk` (claude-agent-sdk) -- `opentelemetry-instrumentation-genai-langchain` (langchain) -- `opentelemetry-instrumentation-genai-weaviate-client` (weaviate-client) -- `opentelemetry-instrumentation-genai-openai` (openai; only security patches in this repo, as `opentelemetry-instrumentation-openai-v2`) -- `opentelemetry-instrumentation-genai-openai-agents` (openai-agents; only security patches in this repo, as `opentelemetry-instrumentation-openai-agents-v2`) - -Do not add, modify, or attempt to fix these instrumentations in this repository beyond security -patches for the packages that still live here. Direct any other changes to the -`opentelemetry-python-genai` repo instead. - -## 1. Instrumentation Layer Boundary - -Do not call OpenTelemetry APIs (`tracer`, `meter`, `span`, event APIs) directly. -Always go through `TelemetryHandler` and the invocation objects it returns. - -This layer is responsible only for: - -- Patching the library -- Parsing library-specific input/output into invocation fields - -Everything else (span creation, metric recording, event emission, context propagation) -belongs in `util/opentelemetry-util-genai`. - -For GenAI streaming wrappers, prefer the shared `SyncStreamWrapper` and `AsyncStreamWrapper` -helpers from `opentelemetry.util.genai.stream` instead of reimplementing iteration, -close/context-manager, and finalization behavior in provider packages. - -Put provider-specific chunk parsing and telemetry finalization in private hook methods or a -narrow mixin. Do not make async stream wrappers inherit from sync stream wrappers. - -## 2. TelemetryHandler Initialization - -Construct `TelemetryHandler` once inside `_instrument()`, passing all OTel providers and the -completion hook. Always prefer an explicitly injected hook (`kwargs.get("completion_hook")`) -over the entry-point hook loaded by `load_completion_hook()`, so test code can override the -hook without touching the environment. - -```python -from opentelemetry.util.genai.completion_hook import load_completion_hook -from opentelemetry.util.genai.handler import TelemetryHandler - -def _instrument(self, **kwargs): - tracer_provider = kwargs.get("tracer_provider") - meter_provider = kwargs.get("meter_provider") - logger_provider = kwargs.get("logger_provider") - - handler = TelemetryHandler( - tracer_provider=tracer_provider, - meter_provider=meter_provider, - logger_provider=logger_provider, - completion_hook=kwargs.get("completion_hook") or load_completion_hook(), - ) - # pass handler to each patch/wrapper function -``` - -## 3. Invocation Pattern - -Use `start_*()` and control span lifetime manually: - -```python -invocation = handler.start_inference(provider, request_model, server_address=..., server_port=...) -invocation.temperature = ... -try: - response = client.call(...) - invocation.response_model_name = response.model - invocation.finish_reasons = response.finish_reasons - invocation.stop() -except Exception as exc: - invocation.fail(exc) - raise -``` - -Content capture decisions must come from the shared handler, not from instrumentation-local -environment checks or duplicated helper logic. Evaluate the handler's content-capture API once -when creating wrappers (for example, `capture_content = handler.should_capture_content()`) and -pass that value through invocation/request helpers. - -## 4. Semantic conventions - -Attributes, spans, events, and metrics follow the -[GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/gen-ai). -Do not emit signals that are not covered by semconv. - -`gen_ai.*` attribute names and the enums for well-known values (e.g. `GenAiOutputTypeValues` for -`gen_ai.output.type`) live in `opentelemetry.semconv._incubating.attributes.gen_ai_attributes`. - -## 5. Tests - -- Use VCR cassettes for provider calls. Do not skip tests when an API key is missing. -- Cover streaming and non-streaming variants when both exist. -- Cover error scenarios, at minimum: provider error / endpoint unavailable, stream interrupted by - network, stream closed early by the caller. - -## 6. Examples - -New instrumentations ship a minimal example under the package's `examples/` directory, with -both a `manual/` setup and a `zero-code/` (auto-instrumentation) variant. +Do not add instrumentations here, and do not fix bugs or add features to the ones that remain. +Send any such change to the `opentelemetry-python-genai` repo instead. Security patches are the +only changes accepted in this directory. diff --git a/instrumentation-genai/README.md b/instrumentation-genai/README.md index cd601570c4..c6c5c47780 100644 --- a/instrumentation-genai/README.md +++ b/instrumentation-genai/README.md @@ -1,16 +1,16 @@ > [!WARNING] -> GenAI instrumentations are moving to the +> GenAI instrumentations have been moved to the > [opentelemetry-python-genai](https://github.com/open-telemetry/opentelemetry-python-genai) -> repository, which is now their home for new development and releases. The -> instrumentations that still live in this repository only receive security -> patches and will be removed from here in the future. +> repository, which is now their home for new development and releases. The copies that +> still live in this directory only receive security patches and will be removed from +> here in the future. | Instrumentation | Supported Packages | Metrics support | Semconv status | | --------------- | ------------------ | --------------- | -------------- | | [opentelemetry-instrumentation-genai-anthropic](https://github.com/open-telemetry/opentelemetry-python-genai/tree/main/instrumentation/opentelemetry-instrumentation-genai-anthropic) | anthropic >= 0.16.0 | Yes | development | [opentelemetry-instrumentation-genai-claude-agent-sdk](https://github.com/open-telemetry/opentelemetry-python-genai/tree/main/instrumentation/opentelemetry-instrumentation-genai-claude-agent-sdk) | claude-agent-sdk >= 0.1.14 | No | development -| [opentelemetry-instrumentation-google-genai](./opentelemetry-instrumentation-google-genai) | google-genai >= 1.32.0 | No | development +| [opentelemetry-instrumentation-google-genai](https://github.com/open-telemetry/opentelemetry-python-genai/tree/main/instrumentation/opentelemetry-instrumentation-google-genai) | google-genai >= 1.32.0 | No | development | [opentelemetry-instrumentation-genai-langchain](https://github.com/open-telemetry/opentelemetry-python-genai/tree/main/instrumentation/opentelemetry-instrumentation-genai-langchain) | langchain >= 0.3.21 | Yes | development | [opentelemetry-instrumentation-genai-openai-agents](https://github.com/open-telemetry/opentelemetry-python-genai/tree/main/instrumentation/opentelemetry-instrumentation-genai-openai-agents) | openai-agents >= 0.3.3 | No | development | [opentelemetry-instrumentation-genai-openai](https://github.com/open-telemetry/opentelemetry-python-genai/tree/main/instrumentation/opentelemetry-instrumentation-genai-openai) | openai >= 1.26.0 | Yes | development diff --git a/instrumentation-genai/opentelemetry-instrumentation-google-genai/CHANGELOG.md b/instrumentation-genai/opentelemetry-instrumentation-google-genai/CHANGELOG.md index ea5ffc6d37..4a16944d24 100644 --- a/instrumentation-genai/opentelemetry-instrumentation-google-genai/CHANGELOG.md +++ b/instrumentation-genai/opentelemetry-instrumentation-google-genai/CHANGELOG.md @@ -1,15 +1,18 @@ # Changelog +> [!WARNING] +> This copy of the instrumentation is deprecated and only receives security patches. +> `opentelemetry-instrumentation-google-genai` keeps its name, but is developed and released from the +> [opentelemetry-python-genai](https://github.com/open-telemetry/opentelemetry-python-genai/tree/main/instrumentation/opentelemetry-instrumentation-google-genai) +> repository starting with version `1.0b0`, which contains breaking changes. See its +> [CHANGELOG](https://github.com/open-telemetry/opentelemetry-python-genai/blob/main/instrumentation/opentelemetry-instrumentation-google-genai/CHANGELOG.md) +> for later releases. + All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## Unreleased - --Add `gen_ai.usage.reasoning.output_tokens` attribute to capture thinking tokens on spans/events when the experimental sem conv flag is set. Add thinking tokens to output tokens. ([#4313](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4313)) --Add `gen_ai.usage.cache_read.input_tokens` attribute to capture cached tokens on spans/events when the experimental sem conv flag is set. ([#4313](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4313)) - ## Version 0.7b1 (2026-05-19) ## Version 0.7b0 (2026-02-20) - Fix bug in how tokens are counted when using the streaming `generateContent` method. ([#4152](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4152)). diff --git a/instrumentation-genai/opentelemetry-instrumentation-google-genai/README.rst b/instrumentation-genai/opentelemetry-instrumentation-google-genai/README.rst index cbe2fa4571..45b2872954 100644 --- a/instrumentation-genai/opentelemetry-instrumentation-google-genai/README.rst +++ b/instrumentation-genai/opentelemetry-instrumentation-google-genai/README.rst @@ -1,11 +1,23 @@ OpenTelemetry Google GenAI SDK Instrumentation ============================================== -.. note:: +.. warning:: - This package is being migrated as ``opentelemetry-instrumentation-google-genai`` to + **This copy of the instrumentation is deprecated.** The package keeps its name, + `opentelemetry-instrumentation-google-genai `_, + but is now developed and released from `opentelemetry-python-genai/instrumentation/opentelemetry-instrumentation-google-genai `_. - Future development will happen there. + Versions ``1.0b0`` and later come from that repository; the copy here only + receives security patches. Upgrade with: + + .. code-block:: console + + pip install --upgrade "opentelemetry-instrumentation-google-genai>=1.0b0" + + Version ``1.0b0`` contains **breaking changes** to the emitted telemetry and + to the configuration API relative to the ``0.x`` releases. Review the + `CHANGELOG `_ + before upgrading. |pypi| diff --git a/instrumentation-genai/opentelemetry-instrumentation-vertexai/CHANGELOG.md b/instrumentation-genai/opentelemetry-instrumentation-vertexai/CHANGELOG.md index f4e0e707a1..968d34c802 100644 --- a/instrumentation-genai/opentelemetry-instrumentation-vertexai/CHANGELOG.md +++ b/instrumentation-genai/opentelemetry-instrumentation-vertexai/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +> [!WARNING] +> This package is deprecated and will not be replaced — it only receives security patches and will be removed in the future. +> Google [deprecated the generative AI modules of the Vertex AI SDK](https://cloud.google.com/vertex-ai/generative-ai/docs/deprecations/genai-vertexai-sdk) +> that this package instruments. + All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),