Emit telemetry under the instrumentation's own scope (#632)

* fix instrumentation scope name and version, add tests

* Enforce the instrumentation scope with a shared test fixture

Replace the per-package instrumentation-scope tests with an autouse
fixture that checks every TelemetryHandler built by instrumentation code
during any test.

* Require util-genai 1.2b0.dev where the scope arguments are used

claude-agent-sdk, crewai and dspy declared older floors, so their oldest
envs resolved a util-genai without instrumentation_scope_name.

Assisted-by: Claude Opus 5

* Renumber changelog fragments to the PR number

* Apply suggestion from @lmolkova

* Keep the fallback scope name and version consistent

Assisted-by: Claude Opus 5

* Fix changelog wording

* Use package names for instrumentation scopes

Assisted-by: ChatGPT 5

* Apply scope test formatting

Author: lmolkova

.github/instructions/instrumentation.instructions.md

@@ -37,6 +37,11 @@ prefer opt-in or additive. Breaking changes need explicit justification in the P
 
 - Spans, logs, metrics, and events must go through `opentelemetry-util-genai`. Direct use of
   `Tracer`, `Meter`, `Logger`, or event APIs is not allowed.
+- `TelemetryHandler` must use the dotted instrumentation package path as
+  `instrumentation_scope_name` and its `__version__` as `instrumentation_scope_version` so spans,
+  metrics, and logs carry the instrumentation's own scope. `__package__` may be used when it
+  resolves to that exact path. The shared `TelemetryHandlerScopeTest` enforces both values. Flag
+  handlers built without them. `get_telemetry_handler()` is deprecated; flag new uses.
 - 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.
 - Completion hook wiring must follow the util's contract (reference:

AGENTS.md

@@ -191,6 +191,12 @@ Apply to packages under `instrumentation/`.
 - Spans, logs, metrics, and events should go through `opentelemetry-util-genai`. Do not call OTel
   `Tracer`/`Meter`/`Logger` directly, and import only its public surface — never an
   `opentelemetry.util.genai._*` module.
+- Construct the `TelemetryHandler` with the dotted instrumentation package path as
+  `instrumentation_scope_name` and the package's `__version__` as
+  `instrumentation_scope_version`. Use `__package__` when it resolves to that exact package path;
+  do not use a submodule's `__name__`. Import `__version__` from the package's `version` module.
+  Subclass `opentelemetry.test_util_genai.scope.TelemetryHandlerScopeTest` in each package to verify
+  its exact name and version on spans, metrics, and logs.
 - Content capture, hooks, and configuration are owned by the util. Don't add instrumentation-local
   env vars or settings.
 - Models describing complex attributes are owned by `opentelemetry.util.genai.types`. Land new type
@@ -208,8 +214,7 @@ as the reference:
 
 - In `_instrument(**kwargs)`, resolve the hook as
   `kwargs.get("completion_hook") or load_completion_hook()` and pass it to the handler
-  (`TelemetryHandler(..., completion_hook=...)` or
-  `get_telemetry_handler(..., completion_hook=...)`). `load_completion_hook()` returns the hook
+  (`TelemetryHandler(..., completion_hook=...)`). `load_completion_hook()` returns the hook
   named by `OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK` (e.g. `upload`) via its entry point, or a
   no-op. An explicit `instrument(completion_hook=…)` argument takes precedence over the env var.
 - Don't define your own hook interface, call `on_completion` yourself, or wrap it in `try/except` —

instrumentation/opentelemetry-instrumentation-genai-agno/.changelog/632.fixed

@@ -0,0 +1 @@
+Emit telemetry under the `opentelemetry.instrumentation.genai.agno` instrumentation scope instead of `opentelemetry.util.genai.handler`

instrumentation/opentelemetry-instrumentation-genai-agno/src/opentelemetry/instrumentation/genai/agno/__init__.py

@@ -40,6 +40,7 @@
     patch_agent,
     unpatch_agent,
 )
+from opentelemetry.instrumentation.genai.agno.version import __version__
 from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
 from opentelemetry.util.genai.completion_hook import load_completion_hook
 from opentelemetry.util.genai.handler import TelemetryHandler
@@ -75,6 +76,8 @@ def _instrument(self, **kwargs: Any) -> None:
             meter_provider=meter_provider,
             logger_provider=logger_provider,
             completion_hook=completion_hook,
+            instrumentation_scope_name=__package__,
+            instrumentation_scope_version=__version__,
         )
         patch_agent(handler)
 

instrumentation/opentelemetry-instrumentation-genai-agno/tests/test_instrumentation_scope.py

@@ -0,0 +1,12 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+from opentelemetry.instrumentation.genai.agno import AgnoInstrumentor
+from opentelemetry.instrumentation.genai.agno.version import __version__
+from opentelemetry.test_util_genai.scope import TelemetryHandlerScopeTest
+
+
+class TestInstrumentationScope(TelemetryHandlerScopeTest):
+    instrumentor_class = AgnoInstrumentor
+    instrumentation_scope_name = "opentelemetry.instrumentation.genai.agno"
+    instrumentation_scope_version = __version__

instrumentation/opentelemetry-instrumentation-genai-anthropic/.changelog/632.fixed

@@ -0,0 +1 @@
+Emit telemetry under the `opentelemetry.instrumentation.genai.anthropic` instrumentation scope instead of `opentelemetry.util.genai.handler`

instrumentation/opentelemetry-instrumentation-genai-anthropic/src/opentelemetry/instrumentation/genai/anthropic/__init__.py

@@ -43,6 +43,7 @@
 
 from wrapt import wrap_function_wrapper
 
+from opentelemetry.instrumentation.genai.anthropic.version import __version__
 from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
 from opentelemetry.instrumentation.utils import unwrap
 from opentelemetry.util.genai.completion_hook import load_completion_hook
@@ -114,6 +115,8 @@ def _instrument(self, **kwargs: Any) -> None:
             logger_provider=logger_provider,
             completion_hook=kwargs.get("completion_hook")
             or load_completion_hook(),
+            instrumentation_scope_name=__package__,
+            instrumentation_scope_version=__version__,
         )
 
         wrap_function_wrapper(

instrumentation/opentelemetry-instrumentation-genai-anthropic/tests/test_instrumentation_scope.py

@@ -0,0 +1,14 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+from opentelemetry.instrumentation.genai.anthropic import AnthropicInstrumentor
+from opentelemetry.instrumentation.genai.anthropic.version import __version__
+from opentelemetry.test_util_genai.scope import TelemetryHandlerScopeTest
+
+
+class TestInstrumentationScope(TelemetryHandlerScopeTest):
+    instrumentor_class = AnthropicInstrumentor
+    instrumentation_scope_name = (
+        "opentelemetry.instrumentation.genai.anthropic"
+    )
+    instrumentation_scope_version = __version__

instrumentation/opentelemetry-instrumentation-genai-bedrock/.changelog/632.fixed

@@ -0,0 +1 @@
+Emit telemetry under the `opentelemetry.instrumentation.genai.bedrock` instrumentation scope instead of `opentelemetry.util.genai.handler`

instrumentation/opentelemetry-instrumentation-genai-bedrock/src/opentelemetry/instrumentation/genai/bedrock/__init__.py

@@ -8,6 +8,7 @@
 from collections.abc import Collection
 from typing import Any
 
+from opentelemetry.instrumentation.genai.bedrock.version import __version__
 from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
 from opentelemetry.util.genai.completion_hook import load_completion_hook
 from opentelemetry.util.genai.handler import TelemetryHandler
@@ -36,6 +37,8 @@ def _instrument(self, **kwargs: Any) -> None:
             meter_provider=kwargs.get("meter_provider"),
             logger_provider=kwargs.get("logger_provider"),
             completion_hook=completion_hook,
+            instrumentation_scope_name=__package__,
+            instrumentation_scope_version=__version__,
         )
         patch_bedrock(self._handler)