Merge branch 'main' into 4209

Author: iblancasa

.github/labeler.yml

@@ -0,0 +1,6 @@
+gen-ai:
+  - changed-files:
+      - any-glob-to-any-file:
+          - 'instrumentation-genai/**'
+          - 'util/opentelemetry-util-genai/**'
+          - 'docs/instrumentation-genai/**'

.github/workflows/labeler.yml

@@ -0,0 +1,18 @@
+name: PR Labeler
+
+on:
+  pull_request_target:
+
+permissions:
+  contents: read
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/labeler@v6
+        with:
+          sync-labels: false

CONTRIBUTING.md

@@ -206,7 +206,13 @@ git commit
 git push fork feature
 ```
 
-Open a pull request against the main `opentelemetry-python-contrib` repo.
+Open a pull request (PR) against the main `opentelemetry-python-contrib` repo.
+
+A descriptive PR title will help the community better triage and review your changes. Make sure to prefix with the name(s) of the package/subdirectory/domain that your PR updates. Following any of these examples will help:
+
+* "opentelemetry-instrumentation-dbapi: add client operation duration metrics"
+* "GenAI Utils: Add _BaseAgent base class and agent creation lifecycle"
+* "docs(google-genai): document config recording environment variables"
 
 ### How to Receive Comments
 

RELEASING.md

@@ -44,7 +44,15 @@ To keep the process lightweight, it's OK to approve the PRs you generate and mer
 
 ## Preparing a new patch release
 
-* Backport pull request(s) to the release branch.
+### Backporting
+
+Creating manual backports of pull request(s) requires the `backport` label to be added in order to have a green CI. Even if there where
+no changes on a repo the patch release preparation workflow requires an empty `## Unreleased` header in `CHANGELOG.md`.
+
+Backport of pull request(s) can be automated by a workflow only if there where no changes that will create conflicts in the release
+branch, unfortunately every `CHANGELOG.md` change will create one.
+
+To use the workflow to backport pull request(s) to the release branch:
   * Run the [Backport workflow](https://github.com/open-telemetry/opentelemetry-python-contrib/actions/workflows/backport.yml).
   * Press the "Run workflow" button, then select the release branch from the dropdown list,
     e.g. `release/v1.9.x`, then enter the pull request number that you want to backport,
@@ -54,6 +62,9 @@ To keep the process lightweight, it's OK to approve the PRs you generate and mer
   * Review and merge the backport pull request that it generates.
 * Merge a pull request to the release branch updating the `CHANGELOG.md`.
   * The heading for the unreleased entries should be `## Unreleased`.
+
+### Preparing a patch release
+
 * Run the [Prepare patch release workflow](https://github.com/open-telemetry/opentelemetry-python-contrib/actions/workflows/prepare-patch-release.yml).
   * Press the "Run workflow" button, then select the release branch from the dropdown list,
     e.g. `release/v1.9.x`, and click the "Run workflow" button below that.

instrumentation-genai/AGENTS.md

@@ -19,7 +19,32 @@ This layer is responsible only for:
 Everything else (span creation, metric recording, event emission, context propagation)
 belongs in `util/opentelemetry-util-genai`.
 
-## 2. Invocation Pattern
+## 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:
 
@@ -36,7 +61,7 @@ except Exception as exc:
     raise
 ```
 
-## 3. Semantic conventions
+## 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).
@@ -45,14 +70,14 @@ 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`.
 
-## 4. Tests
+## 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.
 
-## 5. Examples
+## 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.

instrumentation-genai/opentelemetry-instrumentation-anthropic/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- Update `opentelemetry-util-genai` dependency range to `>= 0.4b0.dev, <0.5b0`
+  ([#4520](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4520))
 - Fix compatibility with wrapt 2.x by using positional arguments in `wrap_function_wrapper()` calls
   ([#4445](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4445))
 

instrumentation-genai/opentelemetry-instrumentation-anthropic/pyproject.toml

@@ -28,7 +28,7 @@ dependencies = [
   "opentelemetry-api ~= 1.39",
   "opentelemetry-instrumentation ~= 0.60b0",
   "opentelemetry-semantic-conventions ~= 0.60b0",
-  "opentelemetry-util-genai >= 0.2b0, <0.4b0",
+  "opentelemetry-util-genai >= 0.4b0.dev, <0.5b0",
 ]
 
 [project.optional-dependencies]

instrumentation-genai/opentelemetry-instrumentation-anthropic/tests/requirements.oldest.txt

@@ -15,7 +15,7 @@
 # This variant of the requirements aims to test the system using
 # the oldest supported version of external dependencies.
 
--e util/opentelemetry-util-genai
+-e util/opentelemetry-util-genai # todo: update to 0.4b0 when it's released
 anthropic==0.51.0
 pytest==7.4.4
 pytest-vcr==1.0.2

instrumentation-genai/opentelemetry-instrumentation-claude-agent-sdk/CHANGELOG.md

@@ -7,5 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- Update `opentelemetry-util-genai` dependency range to `>= 0.4b0.dev, <0.5b0`
+  ([#4520](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4520))
+
 ### Added
 

instrumentation-genai/opentelemetry-instrumentation-claude-agent-sdk/pyproject.toml

@@ -27,7 +27,7 @@ dependencies = [
   "opentelemetry-api ~= 1.39",
   "opentelemetry-instrumentation ~= 0.60b0",
   "opentelemetry-semantic-conventions ~= 0.60b0",
-  "opentelemetry-util-genai >= 0.2b0, <0.4b0",
+  "opentelemetry-util-genai >= 0.2b0, <0.5b0",
 ]
 
 [project.optional-dependencies]