[opentelemetry-util-genai] Add should_capture_content to GenAIInvocation and deprecate should_capture_content_on_spans

[lmolkova]

What does this change do?

Adds a should_capture_content boolean property to GenAIInvocation initialized by TelemetryHandler, and switches invocations and tool wrappers to it. Deprecates should_capture_content_on_spans() in utils.py and should_capture_content_on_span on ToolInvocation.

Why?

Reading environment variables on every call is not awesome on the hot path. Env vars are harder to patch for tests and harder to migrate to declarative config in the future, so limiting number of times we read env vars is future-proof and makes things easier.

In addition, checking only spans does not make sense because we probably want to have events for each operation eventually.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

This PR introduces a cached per-handler content-capture flag (GenAIInvocation.should_capture_content) to avoid repeated environment-variable reads on hot paths, and deprecates older “span-only” capture helpers in favor of the new property.

Changes:

• Add should_capture_content to GenAIInvocation and plumb it through TelemetryHandler factories.
• Deprecate should_capture_content_on_spans() and ToolInvocation.should_capture_content_on_span.
• Update wrappers/tests to use the new flag and to set envvars in a handler-safe way.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_invocation.py	Adds should_capture_content property on the base invocation.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/handler.py	Passes cached handler capture flag into invocation constructors and updates docs.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_tool_invocation.py	Switches span attribute gating to should_capture_content; adds deprecated alias property.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_retrieval_invocation.py	Switches span content gating to should_capture_content.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_workflow_invocation.py	Switches span message gating to should_capture_content and removes envvar reads.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/utils.py	Deprecates should_capture_content_on_spans() with stronger warning about hot path usage.
util/opentelemetry-util-genai/tests/test_toolcall.py	Adds tests for default/enabled capture flag on tool invocations.
util/opentelemetry-util-genai/tests/test_handler_retrieval.py	Adjusts tests to construct handlers under envvar patches (due to caching).
instrumentation/opentelemetry-instrumentation-google-genai/src/.../tool_call_wrapper.py	Updates wrappers to check should_capture_content.
instrumentation//tests/	Updates tests to use monkeypatch.setenv and/or rebuild handlers.
util/opentelemetry-util-genai/.changelog/*	Adds changelog entries for the new property and deprecations.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on maintainers · refreshed 2026-09-04 06:20 UTC

Merge when ready.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[eternalcuriouslearner]

I am
Assuming we need not change anything in other instrumentations. Please correct me if I am wrong.

[lmolkova]

I am Assuming we need not change anything in other instrumentations. Please correct me if I am wrong.

no, you're right, it's exhaustive