Merge branch 'main' into celery-allow-using-links-instead-of-child-spans

jlc-christie · web-flow · commit b87b7a091dab · 2025-09-25T10:08:47.000+01:00
diff --git a/.github/workflows/misc_0.yml b/.github/workflows/misc_0.yml
@@ -157,8 +157,8 @@ jobs:
       - name: Run tests
         run: tox -e shellcheck
 
-  ruff:
-    name: ruff
+  precommit:
+    name: precommit
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
@@ -174,7 +174,7 @@ jobs:
         run: pip install tox-uv
 
       - name: Run tests
-        run: tox -e ruff
+        run: tox -e precommit
 
   typecheck:
     name: typecheck
diff --git a/.github/workflows/package-prepare-patch-release.yml b/.github/workflows/package-prepare-patch-release.yml
@@ -11,6 +11,7 @@ on:
         - opentelemetry-instrumentation-openai-v2
         - opentelemetry-instrumentation-vertexai
         - opentelemetry-instrumentation-google-genai
+        - opentelemetry-util-genai
         description: 'Package to be released'
         required: true
 permissions:
@@ -48,7 +49,7 @@ jobs:
 
           version=$(./scripts/eachdist.py version --package ${{ inputs.package }})
 
-          version_file=$(find $path -type f -path "*version*.py")
+          version_file=$(find $path -type f -path "**/version.py")
           file_count=$(echo "$version_file" | wc -l)
 
           if [ "$file_count" -ne 1 ]; then
diff --git a/.github/workflows/package-prepare-release.yml b/.github/workflows/package-prepare-release.yml
@@ -11,6 +11,7 @@ on:
         - opentelemetry-instrumentation-openai-v2
         - opentelemetry-instrumentation-vertexai
         - opentelemetry-instrumentation-google-genai
+        - opentelemetry-util-genai
         description: 'Package to be released'
         required: true
 
@@ -60,7 +61,7 @@ jobs:
 
           version=${version_dev%.dev}
 
-          version_file=$(find $path -type f -path "*version*.py")
+          version_file=$(find $path -type f -path "**/version.py")
           file_count=$(echo "$version_file" | wc -l)
 
           if [ "$file_count" -ne 1 ]; then
diff --git a/.github/workflows/package-release.yml b/.github/workflows/package-release.yml
@@ -11,6 +11,7 @@ on:
         - opentelemetry-instrumentation-openai-v2
         - opentelemetry-instrumentation-vertexai
         - opentelemetry-instrumentation-google-genai
+        - opentelemetry-util-genai
         description: 'Package to be released'
         required: true
 permissions:
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -13,3 +13,9 @@ repos:
     rev: 0.6.0
     hooks:
       - id: uv-lock
+  - repo: https://github.com/rstcheck/rstcheck
+    rev: 77490ffa33bfc0928975ae3cf904219903db755d # frozen: v6.2.5
+    hooks:
+      - id: rstcheck
+        additional_dependencies: ['rstcheck[sphinx]']
+        args: ["--report-level", "warning"]
diff --git a/.rstcheck.cfg b/.rstcheck.cfg
@@ -0,0 +1,2 @@
+[rstcheck]
+ignore_directives = automodule
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,6 +21,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - `opentelemetry-instrumentation`: botocore: Add support for AWS Secrets Manager semantic convention attribute
   ([#3765](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3765))
+- Add `rstcheck` to pre-commit to stop introducing invalid RST
+  ([#3777](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3777))
+
 
 ## Version 1.37.0/0.58b0 (2025-09-11)
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -84,8 +84,9 @@ You can run `tox` with the following arguments:
 * `tox -e lint-some-package` to run lint checks on `some-package`
 * `tox -e generate-workflows` to run creation of new CI workflows if tox environments have been updated
 * `tox -e ruff` to run ruff linter and formatter checks against the entire codebase
+* `tox -e precommit` to run all `pre-commit` actions
 
-`ruff check` and `ruff format` are executed when `tox -e ruff` is run. We strongly recommend you to configure [pre-commit](https://pre-commit.com/) locally to run `ruff` automatically before each commit by installing it as git hooks. You just need to [install pre-commit](https://pre-commit.com/#install) in your environment:
+`ruff check` and `ruff format` are executed when `tox -e ruff` is run. We strongly recommend you to configure [pre-commit](https://pre-commit.com/) locally to run `ruff` and `rstcheck` automatically before each commit by installing it as git hooks. You just need to [install pre-commit](https://pre-commit.com/#install) in your environment:
 
 ```console
 pip install pre-commit -c dev-requirements.txt
diff --git a/_template/README.rst b/_template/README.rst
@@ -1,5 +1,5 @@
 OpenTelemetry <REPLACE ME> Instrumentation
-===========================
+==========================================
 
 |pypi|
 
@@ -20,5 +20,5 @@ Installation
 References
 ----------
 
-* `OpenTelemetry <REPLACE ME>/ Tracing <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/<REPLACE ME>/<REPLACE ME>.html>`_
+* `OpenTelemetry REPLACE ME/ Tracing <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/REPLACE ME/REPLACE ME.html>`_
 * `OpenTelemetry Project <https://opentelemetry.io/>`_
diff --git a/docs/instrumentation-genai/util.rst b/docs/instrumentation-genai/util.rst
@@ -21,7 +21,7 @@ OpenTelemetry Python - GenAI Util
     :undoc-members:
     :show-inheritance:
 
-.. automodule:: opentelemetry.util.genai.upload_hook
+.. automodule:: opentelemetry.util.genai.completion_hook
     :members:
     :undoc-members:
     :show-inheritance:
diff --git a/instrumentation-genai/opentelemetry-instrumentation-google-genai/examples/manual/README.rst b/instrumentation-genai/opentelemetry-instrumentation-google-genai/examples/manual/README.rst
@@ -1,5 +1,5 @@
 OpenTelemetry Google GenAI SDK Manual Instrumentation Example
-============================================
+=============================================================
 
 This is an example of how to instrument Google GenAI SDK calls when configuring
 OpenTelemetry SDK and Instrumentations manually.
diff --git a/instrumentation-genai/opentelemetry-instrumentation-google-genai/examples/zero-code/README.rst b/instrumentation-genai/opentelemetry-instrumentation-google-genai/examples/zero-code/README.rst
@@ -1,5 +1,5 @@
 OpenTelemetry Google GenAI SDK Manual Instrumentation Example
-============================================
+=============================================================
 
 This is an example of how to instrument Google GenAI SDK calls with zero code changes,
 using `opentelemetry-instrument`.
diff --git a/instrumentation-genai/opentelemetry-instrumentation-langchain/examples/manual/README.rst b/instrumentation-genai/opentelemetry-instrumentation-langchain/examples/manual/README.rst
@@ -1,20 +1,20 @@
 OpenTelemetry Langcahin Instrumentation Example
-============================================
+===============================================
 
 This is an example of how to instrument Langchain when configuring OpenTelemetry SDK and instrumentations manually.
 
-When :code:`main.py <main.py>`_ is run, it exports traces to an OTLP-compatible endpoint.
+When `main.py <main.py>`_ is run, it exports traces to an OTLP-compatible endpoint.
 Traces include details such as the span name and other attributes.
 
-Note: :code:`.env <.env>`_ file configures additional environment variables:
+Note: `.env <.env>`_ file configures additional environment variables:
 - :code:`OTEL_LOGS_EXPORTER=otlp` to specify exporter type.
 - :code:`OPENAI_API_KEY` open AI key for accessing the OpenAI API.
 - :code:`OTEL_EXPORTER_OTLP_ENDPOINT` to specify the endpoint for exporting traces (default is http://localhost:4317).
 
 Setup
 -----
 
-Minimally, update the :code:`.env <.env>`_ file with your :code:`OPENAI_API_KEY`.
+Minimally, update the `.env <.env>`_ file with your :code:`OPENAI_API_KEY`.
 An OTLP compatible endpoint should be listening for traces http://localhost:4317.
 If not, update :code:`OTEL_EXPORTER_OTLP_ENDPOINT` as well.
 
diff --git a/instrumentation-genai/opentelemetry-instrumentation-langchain/examples/zero-code/README.rst b/instrumentation-genai/opentelemetry-instrumentation-langchain/examples/zero-code/README.rst
@@ -1,21 +1,21 @@
 OpenTelemetry Langchain Zero-Code Instrumentation Example
-======================================================
+=========================================================
 
 This is an example of how to instrument Langchain with zero code changes,
 using `opentelemetry-instrument`.
 
-When :code:`main.py <main.py>`_ is run, it exports traces to an OTLP-compatible endpoint.
+When `main.py <main.py>`_ is run, it exports traces to an OTLP-compatible endpoint.
 Traces include details such as the span name and other attributes.
 
-Note: :code:`.env <.env>`_ file configures additional environment variables:
+Note: `.env <.env>`_ file configures additional environment variables:
 - :code:`OTEL_LOGS_EXPORTER=otlp` to specify exporter type.
 - :code:`OPENAI_API_KEY` open AI key for accessing the OpenAI API.
 - :code:`OTEL_EXPORTER_OTLP_ENDPOINT` to specify the endpoint for exporting traces (default is http://localhost:4317).
 
 Setup
 -----
 
-Minimally, update the :code:`.env <.env>`_ file with your :code:`OPENAI_API_KEY`.
+Minimally, update the `.env <.env>`_ file with your :code:`OPENAI_API_KEY`.
 An OTLP compatible endpoint should be listening for traces http://localhost:4317.
 If not, update :code:`OTEL_EXPORTER_OTLP_ENDPOINT` as well.
 
diff --git a/instrumentation-genai/opentelemetry-instrumentation-vertexai/examples/manual/README.rst b/instrumentation-genai/opentelemetry-instrumentation-vertexai/examples/manual/README.rst
@@ -1,5 +1,5 @@
 OpenTelemetry VertexAI Instrumentation Example
-============================================
+==============================================
 
 This is an example of how to instrument VertexAI calls when configuring OpenTelemetry SDK and Instrumentations manually.
 
@@ -12,8 +12,8 @@ your VertexAI requests.
 Note: `.env <.env>`_ file configures additional environment variables:
 
 - `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true` configures
-VertexAI instrumentation to capture prompt and completion contents on
-events.
+  VertexAI instrumentation to capture prompt and completion contents on
+  events.
 
 Setup
 -----
diff --git a/instrumentation-genai/opentelemetry-instrumentation-vertexai/examples/zero-code/README.rst b/instrumentation-genai/opentelemetry-instrumentation-vertexai/examples/zero-code/README.rst
@@ -1,5 +1,5 @@
 OpenTelemetry VertexAI Instrumentation Example
-============================================
+==============================================
 
 This is an example of how to instrument VertexAI calls with zero code changes,
 using `opentelemetry-instrument`.
diff --git a/instrumentation-genai/opentelemetry-instrumentation-vertexai/pyproject.toml b/instrumentation-genai/opentelemetry-instrumentation-vertexai/pyproject.toml
@@ -26,7 +26,9 @@ classifiers = [
 dependencies = [
   "opentelemetry-api ~= 1.28",
   "opentelemetry-instrumentation ~= 0.58b0",
-  "opentelemetry-util-genai == 0.1b0.dev",
+  # TODO https://github.com/open-telemetry/opentelemetry-python-contrib/issues/3786: restrict
+  # version after the first release
+  "opentelemetry-util-genai",
   "opentelemetry-semantic-conventions ~= 0.58b0",
 ]
 
diff --git a/instrumentation/opentelemetry-instrumentation-botocore/src/opentelemetry/instrumentation/botocore/extensions/bedrock_utils.py b/instrumentation/opentelemetry-instrumentation-botocore/src/opentelemetry/instrumentation/botocore/extensions/bedrock_utils.py
@@ -117,7 +117,7 @@ def _process_event(self, event):
                         self._content_block["toolUse"]["input"] = json.loads(
                             self._tool_json_input_buf
                         )
-                    except json.DecodeError:
+                    except json.JSONDecodeError:
                         self._content_block["toolUse"]["input"] = (
                             self._tool_json_input_buf
                         )
diff --git a/instrumentation/opentelemetry-instrumentation-urllib/README.rst b/instrumentation/opentelemetry-instrumentation-urllib/README.rst
@@ -37,7 +37,7 @@ The hooks can be configured as follows:
 
     # `request_obj` is an instance of urllib.request.Request
     # `response` is an instance of http.client.HTTPResponse
-    def response_hook(span, request_obj, response)
+    def response_hook(span, request_obj, response):
         pass
 
     URLLibInstrumentor().instrument(
diff --git a/tox.ini b/tox.ini
@@ -429,7 +429,7 @@ envlist =
     generate
     generate-workflows
     shellcheck
-    ruff
+    precommit
     typecheck
 
 [testenv]
@@ -1047,7 +1047,7 @@ commands_pre =
 commands =
   sh -c "find {toxinidir} -name \*.sh | xargs shellcheck --severity=warning"
 
-[testenv:ruff]
+[testenv:{precommit,ruff}]
 basepython: python3
 deps =
   -c {toxinidir}/dev-requirements.txt
diff --git a/util/opentelemetry-util-genai/CHANGELOG.md b/util/opentelemetry-util-genai/CHANGELOG.md
@@ -7,12 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
-- Add upload hook to genai utils to implement semconv v1.37.
+- Add completion hook to genai utils to implement semconv v1.37.
 
-  The hook uses [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) to support
-  various pluggable backends.
+  Includes a hook implementation using
+  [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) to support uploading to various
+  pluggable backends.
+
+  ([#3780](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3780))
   ([#3752](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3752))
-  ([#3759](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3752))
+  ([#3759](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3759))
   ([#3763](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3763))
 - Add a utility to parse the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` environment variable.
   Add `gen_ai_latest_experimental` as a new value to the Sem Conv stability flag ([#3716](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3716)).
diff --git a/util/opentelemetry-util-genai/pyproject.toml b/util/opentelemetry-util-genai/pyproject.toml
@@ -30,8 +30,8 @@ dependencies = [
   "opentelemetry-api>=1.31.0",
 ]
 
-[project.entry-points.opentelemetry_genai_upload_hook]
-fsspec = "opentelemetry.util.genai._fsspec_upload:fsspec_upload_hook"
+[project.entry-points.opentelemetry_genai_completion_hook]
+fsspec_upload = "opentelemetry.util.genai._fsspec_upload:fsspec_completion_upload_hook"
 
 [project.optional-dependencies]
 test = ["pytest>=7.0.0"]
diff --git a/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_fsspec_upload/__init__.py b/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_fsspec_upload/__init__.py
@@ -16,24 +16,27 @@
 
 from os import environ
 
+from opentelemetry.util.genai.completion_hook import (
+    CompletionHook,
+    _NoOpCompletionHook,
+)
 from opentelemetry.util.genai.environment_variables import (
     OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH,
 )
-from opentelemetry.util.genai.upload_hook import UploadHook, _NoOpUploadHook
 
 
-def fsspec_upload_hook() -> UploadHook:
+def fsspec_completion_upload_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.fsspec_hook import (
-            FsspecUploadHook,
+        from opentelemetry.util.genai._fsspec_upload.completion_hook import (
+            FsspecUploadCompletionHook,
         )
     except ImportError:
-        return _NoOpUploadHook()
+        return _NoOpCompletionHook()
 
     base_path = environ.get(OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH)
     if not base_path:
-        return _NoOpUploadHook()
+        return _NoOpCompletionHook()
 
-    return FsspecUploadHook(base_path=base_path)
+    return FsspecUploadCompletionHook(base_path=base_path)
diff --git a/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_fsspec_upload/completion_hook.py b/util/opentelemetry-util-genai/src/opentelemetry/util/genai/_fsspec_upload/completion_hook.py
@@ -34,7 +34,7 @@
 from opentelemetry.semconv._incubating.attributes import gen_ai_attributes
 from opentelemetry.trace import Span
 from opentelemetry.util.genai import types
-from opentelemetry.util.genai.upload_hook import UploadHook
+from opentelemetry.util.genai.completion_hook import CompletionHook
 
 GEN_AI_INPUT_MESSAGES_REF: Final = (
     gen_ai_attributes.GEN_AI_INPUT_MESSAGES + "_ref"
@@ -75,12 +75,12 @@ def fsspec_open(urlpath: str, mode: Literal["w"]) -> TextIO:
     return cast(TextIO, fsspec.open(urlpath, mode))  # pyright: ignore[reportUnknownMemberType]
 
 
-class FsspecUploadHook(UploadHook):
-    """An upload hook using ``fsspec`` to upload to external storage
+class FsspecUploadCompletionHook(CompletionHook):
+    """An completion hook using ``fsspec`` to upload to external storage
 
     This function can be used as the
-    :func:`~opentelemetry.util.genai.upload_hook.load_upload_hook` implementation by
-    setting :envvar:`OTEL_INSTRUMENTATION_GENAI_UPLOAD_HOOK` to ``fsspec``.
+    :func:`~opentelemetry.util.genai.completion_hook.load_completion_hook` implementation by
+    setting :envvar:`OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK` to ``fsspec_upload``.
     :envvar:`OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH` must be configured to specify the
     base path for uploads.
 
@@ -128,7 +128,7 @@ def done(future: Future[None]) -> None:
                 fut.add_done_callback(done)
             except RuntimeError:
                 _logger.info(
-                    "attempting to upload file after FsspecUploadHook.shutdown() was already called"
+                    "attempting to upload file after FsspecUploadCompletionHook.shutdown() was already called"
                 )
                 self._semaphore.release()
 
@@ -161,7 +161,7 @@ def _do_upload(
                 cls=Base64JsonEncoder,
             )
 
-    def upload(
+    def on_completion(
         self,
         *,
         inputs: list[types.InputMessage],
diff --git a/util/opentelemetry-util-genai/src/opentelemetry/util/genai/completion_hook.py b/util/opentelemetry-util-genai/src/opentelemetry/util/genai/completion_hook.py
diff --git a/util/opentelemetry-util-genai/src/opentelemetry/util/genai/environment_variables.py b/util/opentelemetry-util-genai/src/opentelemetry/util/genai/environment_variables.py
diff --git a/util/opentelemetry-util-genai/tests/test_completion_hook.py b/util/opentelemetry-util-genai/tests/test_completion_hook.py
diff --git a/util/opentelemetry-util-genai/tests/test_fsspec_upload.py b/util/opentelemetry-util-genai/tests/test_fsspec_upload.py
diff --git a/util/opentelemetry-util-genai/tests/test_upload_hook.py b/util/opentelemetry-util-genai/tests/test_upload_hook.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+[rstcheck]`
	`2`	`+ignore_directives = automodule`