Remove remaining usage/references to deprecated functions in opentelemetry-util-genai.

[DylanRussell]

Description

Remove from instrumentation libraries the last usages of and references to deprecated functions in opentelemetry-util-genai. Also do some minor code cleanup in opentelemetry-instrumentation-google-genai.

It's critical that (after merging this) we first do a release of opentelemetry-util-genai, then update the pyproject.toml of the following instrumentations to require (>=) the new version of opentelemetry-util-genai: opentelemetry-instrumentation-langchain, opentelemetry-instrumentation-google-genai, opentelemetry-instrumentation-openai-v2, opentelemetry-instrumentation-anthropic

Question for the release pipeline: is there a nice way to handle this intra-repo package dependency ? The process right now feels kind of clunky: we have to do a utils release, then remember to bump all the instrumentation .toml files to use it and then do a release of the instrumentation packages...

Type of change

• [x ] Bug fix (non-breaking change which fixes an issue)

How has this been tested?

Unit tests

Checklist

See CONTRIBUTING.md
for the style guide, changelog guidance, and more.

• [ x] Followed the style guidelines of this project
• [ x] Changelog updated if the change requires an entry
• [ x] Unit tests added
• [ x] Documentation updated

[Copilot]

Pull request overview

This PR updates GenAI instrumentations to use the non-deprecated TelemetryHandler APIs from opentelemetry-util-genai, and removes deprecated handler entry points from the util package. The largest functional refactor is in the Google GenAI instrumentation, which now routes tool-call spans and (experimental) inference spans through the shared util invocation types.

Changes:

• Removed deprecated TelemetryHandler.start_* / start_llm / stop_llm / fail_llm APIs from opentelemetry-util-genai.
• Migrated select instrumentations (OpenAI v2, Anthropic, Google GenAI) from deprecated handler APIs to handler.inference() / handler.tool() etc.
• Refactored Google GenAI tool wrapping + experimental inference path and updated related tests/deps.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py	Removes deprecated handler APIs, leaving only the newer inference/embedding/tool/workflow/agent factories.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/completion_hook.py	Simplifies entry-point loading and typing around completion hook discovery.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_tool_invocation.py	Updates constructor docstring to point to non-deprecated handler API.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_invocation.py	Updates base invocation docstring to reference non-deprecated handler factories.
tox.ini	Adds OTLP exporter deps to tox test dependencies.
instrumentation/opentelemetry-instrumentation-openai-v2/src/opentelemetry/instrumentation/openai_v2/utils.py	Migrates from handler.start_inference() to handler.inference().
instrumentation/opentelemetry-instrumentation-openai-v2/src/opentelemetry/instrumentation/openai_v2/patch_responses.py	Migrates from handler.start_inference() to handler.inference().
instrumentation/opentelemetry-instrumentation-google-genai/src/opentelemetry/instrumentation/google_genai/tool_call_wrapper.py	Reimplements tool wrapping using util TelemetryHandler.tool() and GenAI semconv attributes.
instrumentation/opentelemetry-instrumentation-google-genai/src/opentelemetry/instrumentation/google_genai/instrumentor.py	Instantiates and wires a TelemetryHandler into Google GenAI instrumentation.
instrumentation/opentelemetry-instrumentation-google-genai/src/opentelemetry/instrumentation/google_genai/generate_content.py	Routes experimental-mode inference spans through util invocations; adjusts tool wrapping and env handling.
instrumentation/opentelemetry-instrumentation-google-genai/tests/utils/test_tool_call_wrapper.py	Updates tool wrapper tests to validate util-based tool invocation behavior.
instrumentation/opentelemetry-instrumentation-google-genai/tests/requirements.oldest.txt	Switches oldest test deps to use editable local opentelemetry-util-genai.
instrumentation/opentelemetry-instrumentation-google-genai/tests/generate_content/nonstreaming_base.py	Adds assertions for provider name in experimental semconv span tests.
instrumentation/opentelemetry-instrumentation-google-genai/tests/generate_content/test_tool_call_instrumentation.py	Removes prior tool-call instrumentation tests file.
instrumentation/opentelemetry-instrumentation-google-genai/.changelog/10.changed	Changelog entry for the Google GenAI refactor/semconv changes.
instrumentation/opentelemetry-instrumentation-anthropic/tests/requirements.oldest.txt	Switches oldest test deps to use editable local opentelemetry-util-genai.
instrumentation/opentelemetry-instrumentation-anthropic/src/opentelemetry/instrumentation/anthropic/patch.py	Migrates from handler.start_inference() to handler.inference().

Comments suppressed due to low confidence (2)

util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py:146

• The deprecated TelemetryHandler APIs (start_inference/start_llm/start_tool/stop_llm/fail_llm/etc.) were removed, but the util package version is still "0.5b0.dev" and the removed methods were marked deprecated starting in 0.5b0. This creates a breaking change without a deprecation window, and it currently breaks in-repo callers (e.g. langchain instrumentation still calls start_llm/stop_llm/fail_llm). Consider keeping these methods for at least one released version (delegating to the new APIs), or bumping the util version/compat policy and migrating all in-repo instrumentations before removal.

    # New-style factory methods: construct + start in one call, handler stored on invocation

    def inference(
        self,
        provider: str,
        *,
        request_model: str | None = None,
        server_address: str | None = None,
        server_port: int | None = None,
        operation_name: str | None = None,
    ) -> InferenceInvocation:
        """Returns an Inference invocation. Starts span when called.

instrumentation/opentelemetry-instrumentation-google-genai/src/opentelemetry/instrumentation/google_genai/tool_call_wrapper.py:105

• Same as the async branch: serialize/set tool_invocation.arguments before calling the tool so failures still capture args, and gate the json serialization behind tool_invocation.should_capture_content_on_span to avoid unnecessary work when content capture is disabled.

            with telemetry_handler.tool(
                tool_function.__name__, tool_description=tool_function.__doc__
            ) as tool_invocation:
                result = tool_function(*args, **kwargs)
                tool_invocation.arguments = json.dumps(
                    _get_function_args(tool_function, args, kwargs)
                )
                tool_invocation.tool_result = json.dumps(
                    _to_otel_value(result)
                )

[lmolkova]

I'd prefer us not to remove public things from genai-utils until we deprecate old versions of libs in python-contrib. We should give people some grace period to update to new versions of everything.

Other than removals of public methods from genai utils this looks great!

[DylanRussell]

Ok i've reverted the function deletions

[lzchen]

Was the plan to remove the deprecated functions from all instrumentations in this pr or just google genai? Like here

[DylanRussell]

All instrumentations !

[lzchen]

All instrumentations !

Was this missed?

[DylanRussell]

I don't think so ?? I removed that reference in this PR