Merge branch 'main' into revise-patch-release-instrunctions

Author: lzchen

.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

CHANGELOG.md

@@ -44,6 +44,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Enabled the flake8-tidy-import plugins rules for the ruff linter. These rules throw warnings for relative imports in the modules.
+([#4395](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4395))
 - `opentelemetry-instrumentation-asgi`: Respect `suppress_http_instrumentation` context in ASGI middleware to skip server span creation when HTTP instrumentation is suppressed
   ([#4375](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4375))
 - `opentelemetry-instrumentation-confluent-kafka`: Loosen confluent-kafka upper bound to <3.0.0

CONTRIBUTING.md

@@ -17,6 +17,8 @@ Before you can contribute, you will need to sign the [Contributor License Agreem
 
 Please also read the [OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/guides/contributor/README.md).
 
+If you are using AI agents to assist with contributions, please read [AGENTS.md](AGENTS.md) for guidance on how to use them responsibly in this project.
+
 ## Index
 
 - [Contributing to opentelemetry-python-contrib](#contributing-to-opentelemetry-python-contrib)
@@ -204,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
 

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]