Merge branch 'main' into main

Author: UltimatePlutoC

docs/instrumentation-genai/util.rst

@@ -26,6 +26,6 @@ OpenTelemetry Python - GenAI Util
     :undoc-members:
     :show-inheritance:
 
-.. automodule:: opentelemetry.util.genai._fsspec_upload
+.. automodule:: opentelemetry.util.genai._upload
     :members:
     :show-inheritance:

tox.ini

@@ -1072,7 +1072,7 @@ deps =
   {[testenv]test_deps}
   {toxinidir}/opentelemetry-instrumentation
   {toxinidir}/util/opentelemetry-util-http
-  {toxinidir}/util/opentelemetry-util-genai[fsspec]
+  {toxinidir}/util/opentelemetry-util-genai[upload]
   {toxinidir}/instrumentation-genai/opentelemetry-instrumentation-vertexai[instruments]
   {toxinidir}/instrumentation-genai/opentelemetry-instrumentation-google-genai[instruments]
   {toxinidir}/instrumentation/opentelemetry-instrumentation-aiokafka[instruments]

typings/fsspec/__init__.pyi

@@ -0,0 +1,31 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Handwritten stubs for fsspec usage in opentelemetry-util-genai"""
+
+from __future__ import annotations
+
+import io
+from typing import Any, Literal
+
+from fsspec.spec import (
+    AbstractFileSystem as RealAbstractFileSystem,
+)
+
+class AbstractFileSystem(RealAbstractFileSystem):
+    def open(
+        self, path: str, mode: Literal["w"], *args: Any, **kwargs: Any
+    ) -> io.TextIOWrapper: ...
+
+def url_to_fs(url: str) -> tuple[AbstractFileSystem, str]: ...

util/opentelemetry-util-genai/CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add jsonlines support to fsspec uploader
   ([https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3791](#3791))
+- Rename "fsspec_upload" entry point and classes to more generic "upload"
+  ([https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3798](#3798))
+- Record content-type and use canonical paths in fsspec genai uploader
+  ([https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3795](#3795))
 
 ## Version 0.1b0 (2025-09-24)
 

util/opentelemetry-util-genai/pyproject.toml

@@ -31,11 +31,11 @@ dependencies = [
 ]
 
 [project.entry-points.opentelemetry_genai_completion_hook]
-fsspec_upload = "opentelemetry.util.genai._fsspec_upload:fsspec_completion_upload_hook"
+upload = "opentelemetry.util.genai._upload:upload_completion_hook"
 
 [project.optional-dependencies]
 test = ["pytest>=7.0.0"]
-fsspec = ["fsspec>=2025.9.0"]
+upload = ["fsspec>=2025.9.0"]
 
 [project.urls]
 Homepage = "https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/util/opentelemetry-util-genai"

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_fsspec_upload/__init__.py renamed to util/opentelemetry-util-genai/src/opentelemetry/util/genai/_upload/__init__.py

@@ -25,12 +25,12 @@
 )
 
 
-def fsspec_completion_upload_hook() -> CompletionHook:
+def upload_completion_hook() -> CompletionHook:
     # If fsspec is not installed the hook will be a no-op.
     try:
         # pylint: disable=import-outside-toplevel
-        from opentelemetry.util.genai._fsspec_upload.completion_hook import (
-            FsspecUploadCompletionHook,
+        from opentelemetry.util.genai._upload.completion_hook import (
+            UploadCompletionHook,
         )
     except ImportError:
         return _NoOpCompletionHook()
@@ -39,4 +39,4 @@ def fsspec_completion_upload_hook() -> CompletionHook:
     if not base_path:
         return _NoOpCompletionHook()
 
-    return FsspecUploadCompletionHook(base_path=base_path)
+    return UploadCompletionHook(base_path=base_path)

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_fsspec_upload/completion_hook.py renamed to util/opentelemetry-util-genai/src/opentelemetry/util/genai/_upload/completion_hook.py

@@ -26,7 +26,7 @@
 from functools import partial
 from os import environ
 from time import time
-from typing import Any, Callable, Final, Literal, TextIO, cast
+from typing import Any, Callable, Final, Literal
 from uuid import uuid4
 
 import fsspec
@@ -78,22 +78,17 @@ class CompletionRefs:
 UploadData = dict[str, Callable[[], JsonEncodeable]]
 
 
-def fsspec_open(urlpath: str, mode: Literal["w"]) -> TextIO:
-    """typed wrapper around `fsspec.open`"""
-    return cast(TextIO, fsspec.open(urlpath, mode))  # pyright: ignore[reportUnknownMemberType]
-
-
-class FsspecUploadCompletionHook(CompletionHook):
+class UploadCompletionHook(CompletionHook):
     """An completion hook using ``fsspec`` to upload to external storage
 
     This function can be used as the
     :func:`~opentelemetry.util.genai.completion_hook.load_completion_hook` implementation by
-    setting :envvar:`OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK` to ``fsspec_upload``.
+    setting :envvar:`OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK` to ``upload``.
     :envvar:`OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH` must be configured to specify the
     base path for uploads.
 
     Both the ``fsspec`` and ``opentelemetry-sdk`` packages should be installed, or a no-op
-    implementation will be used instead. You can use ``opentelemetry-util-genai[fsspec]``
+    implementation will be used instead. You can use ``opentelemetry-util-genai[upload]``
     as a requirement to achieve this.
     """
 
@@ -104,8 +99,9 @@ def __init__(
         max_size: int = 20,
         upload_format: Format | None = None,
     ) -> None:
-        self._base_path = base_path
         self._max_size = max_size
+        self._fs, base_path = fsspec.url_to_fs(base_path)
+        self._base_path = self._fs.unstrip_protocol(base_path)
 
         if upload_format not in _FORMATS + (None,):
             raise ValueError(
@@ -133,15 +129,15 @@ def done(future: Future[None]) -> None:
             try:
                 future.result()
             except Exception:  # pylint: disable=broad-except
-                _logger.exception("fsspec uploader failed")
+                _logger.exception("uploader failed")
             finally:
                 self._semaphore.release()
 
         for path, json_encodeable in upload_data.items():
             # could not acquire, drop data
             if not self._semaphore.acquire(blocking=False):  # pylint: disable=consider-using-with
                 _logger.warning(
-                    "fsspec upload queue is full, dropping upload %s",
+                    "upload queue is full, dropping upload %s",
                     path,
                 )
                 continue
@@ -153,7 +149,7 @@ def done(future: Future[None]) -> None:
                 fut.add_done_callback(done)
             except RuntimeError:
                 _logger.info(
-                    "attempting to upload file after FsspecUploadCompletionHook.shutdown() was already called"
+                    "attempting to upload file after UploadCompletionHook.shutdown() was already called"
                 )
                 self._semaphore.release()
 
@@ -188,7 +184,13 @@ def _do_upload(
             for message_idx, line in enumerate(message_lines):
                 line[_MESSAGE_INDEX_KEY] = message_idx
 
-        with fsspec_open(path, "w") as file:
+        content_type = (
+            "application/json"
+            if self._format == "json"
+            else "application/jsonl"
+        )
+
+        with self._fs.open(path, "w", content_type=content_type) as file:
             for message in message_lines:
                 json.dump(
                     message,

util/opentelemetry-util-genai/src/opentelemetry/util/genai/environment_variables.py

@@ -39,9 +39,6 @@
 * `Configuration
   <https://filesystem-spec.readthedocs.io/en/latest/features.html#configuration>`_ for
   configuring a backend with environment variables.
-*  `URL Chaining
-   <https://filesystem-spec.readthedocs.io/en/latest/features.html#url-chaining>`_ for advanced
-   use cases.
 """
 
 OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT = (