feat(genai): add pre-authorized OSS uploader for multimodal content

[123liuziming]

What

Adds a presign multimodal uploader to opentelemetry-util-genai. Instead of holding OSS credentials, the SDK asks the server for a short-lived presigned URL (authenticated with a license key) and then writes the object straight to the server-owned bucket.

Objects are addressed as sls://{project}/{logstore}[/{prefix}]/{objectName}. That address is fully resolvable locally, so span attributes are rewritten before the upload is even issued — the span never has to wait on the network.

Why

The existing uploader requires the application to hold OSS credentials. This mode removes that requirement, which matters for the SDK-only (manual instrumentation) case where there is no agent in the process to supply anything.

Configuration

Variable	Purpose
OTEL_INSTRUMENTATION_GENAI_MULTIMODAL_UPLOADER=presign	selects this uploader
OTEL_INSTRUMENTATION_GENAI_MULTIMODAL_PRESIGN_ENDPOINT	where presigned URLs are requested
OTEL_INSTRUMENTATION_GENAI_MULTIMODAL_PRESIGN_LICENSE_KEY	presign auth; falls back to ARMS_LICENSE_KEY
OTEL_INSTRUMENTATION_GENAI_MULTIMODAL_PRESIGN_WORKSPACE	falls back to ARMS_WORKSPACE
APSARA_APM_COLLECTOR_MULTIMODAL_SLS_PROJECT / ..._SLS_LOGSTORE	object address
OTEL_INSTRUMENTATION_GENAI_MULTIMODAL_OSS_PATH_PREFIX	shared object path prefix (new)

The dedicated PRESIGN_* variables take precedence, with a fallback to the ARMS_* ones so a co-located agent keeps working with no extra configuration. ..._OSS_BUCKET is ignored here, since the server decides which bucket backs the objects.

Failure behavior

If project, endpoint or license key cannot be resolved, both the uploader and the pre-uploader return None and the whole multimodal path degrades to disabled. The original content stays in the span rather than being replaced by a URI pointing at an object that was never written.

Manual instrumentation

Also included: examples/multimodal_presign_manual.py plus docs/manual-instrumentation.md covering the SDK-only flow.

Two configuration requirements there are easy to miss because neither fails loudly:

• Content capturing needs both OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental and OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT. The latter takes a ContentCapturingMode enum name (SPAN_ONLY / SPAN_AND_EVENT) — passing true is an invalid value and silently falls back to NO_CONTENT, producing a span with no message content and no upload at all.
• The logstore must already exist; the default value will not.

The example validates its configuration up front so both surface as explicit errors instead of an empty span.

Testing

• 222 passed, 1 skipped in tests/_multimodal_upload/
• Verified end to end against a real presign endpoint: the presign request and the OSS PUT both returned 200, and the URI written to the span matched the uploaded object key segment for segment. Exercised through both with handler.llm(...) and the explicit start_llm / stop_llm APIs.
• Negative paths checked: missing project, missing opt-in, and an invalid CAPTURE_MESSAGE_CONTENT value are each rejected by the example's config check rather than degrading silently.

[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

Adds a new “presign” multimodal uploader that requests short-lived presigned URLs from an ARMS endpoint (authenticated via license key) and uploads directly to a server-owned OSS bucket, avoiding local OSS credentials.

Changes:

• Introduces MultimodalPresignClient + PresignUploader and wires them as entry points (presign) for uploader and pre-uploader.
• Extends runtime/env configuration to support presign endpoint, license/workspace fallback behavior, and a shared OSS path prefix.
• Adds comprehensive tests plus SDK-only manual instrumentation docs and an executable example.

Reviewed changes

Copilot reviewed 11 out of 11 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/_multimodal_upload/presign_client.py	New presign API client: endpoint resolution, payload construction, response parsing, error classification
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_multimodal_upload/presign_uploader.py	New uploader: bounded async queue, presign+PUT retry loop, optional download of source URIs
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_multimodal_upload/config.py	Adds presign hook support, env snapshot fields, SLS base-path formatting helper, prefix/bucket normalization
util/opentelemetry-util-genai/src/opentelemetry/util/genai/extended_environment_variables.py	Documents new env vars for presign endpoint/auth/timeout and shared object path prefix
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_multimodal_upload/init.py	Exposes presign hook constants/types in package exports
util/opentelemetry-util-genai/pyproject.toml	Registers presign as entry points for uploader + pre-uploader
util/opentelemetry-util-genai/tests/_multimodal_upload/test_presign_uploader.py	Adds presign-specific unit tests across client, uploader, hooks, and config normalization
util/opentelemetry-util-genai/examples/multimodal_presign_manual.py	Adds SDK-only runnable example that validates env/config before running
util/opentelemetry-util-genai/docs/manual-instrumentation.md	Adds manual instrumentation guide including presign mode wiring and pitfalls
util/opentelemetry-util-genai/README-loongsuite.rst	Documents presign mode behavior, env vars, and operational expectations

---

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

[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

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

[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

Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.

[Copilot]

🟡 Changes recommended

The new presign uploader path parsing/validation has a few concrete edge cases (invalid project and URI variants) that should be tightened to avoid accepting malformed sls:// addresses and endpoints.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_multimodal_upload/config.py:373

• presign_endpoint is read from the environment without trimming whitespace. This is inconsistent with _first_env (used for license key/workspace) and can make a seemingly-valid endpoint fail readiness checks or generate invalid request URLs.

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_multimodal_upload/presign_uploader.py:245

• When UploadItem.url uses an sls://... URI, _object_key_from_url currently ignores URL params/query/fragment and doesn't verify the parsed scheme; this can allow multiple textual variants of the same object key (or malformed URIs) to be treated as valid.

        if target.startswith("sls://"):
            parsed = urlparse(target)
            logstore, _, remainder = parsed.path.lstrip("/").partition("/")
            if parsed.netloc != self._project or logstore != self._logstore:
                raise PresignUploadConfigError(

• Files reviewed: 8/8 changed files
• Comments generated: 2
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

The new presign client/uploader have confirmed httpx response lifecycle issues (responses not closed on error/success paths) that can exhaust connection pools in production.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

Previously missed (3) — in code that hasn't changed since the last review.

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_multimodal_upload/config.py:364

• presign_endpoint is read from the environment without trimming whitespace. A value like ' https://example.com ' will be treated as non-empty but later produce invalid URLs; it should be normalized (at least .strip()) at snapshot creation time to match how other string fields are handled.
  util/opentelemetry-util-genai/src/opentelemetry/util/genai/_multimodal_upload/presign_client.py:352
• HTTPX responses should be closed to return the connection to the pool. In the current implementation, non-success presign responses raise without reading/closing the body, which can leak connections under load.
  util/opentelemetry-util-genai/src/opentelemetry/util/genai/_multimodal_upload/presign_uploader.py:522
• HTTPX responses should be closed to release the connection back to the pool. _put_presigned currently returns/raises without closing the response on both success and error paths, which can exhaust the connection pool under retries or high throughput.

• Files reviewed: 8/8 changed files
• Comments generated: 1
• Review effort level: Lite