opentelemetry-instrumentation-vertexai 0.47.3__py3-none-any.whl → 2.1b0__py3-none-any.whl

opentelemetry/instrumentation/vertexai/utils.py

@@ -1,43 +1,459 @@
+# 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.
+
+# type: ignore[reportUnknownDeprecated]
+
+from __future__ import annotations
+
 import logging
-import os
-import traceback
+import re
+from dataclasses import dataclass
+from os import environ
+from typing import (
+    TYPE_CHECKING,
+    Iterable,
+    Literal,
+    Mapping,
+    Sequence,
+    Union,
+    cast,
+    overload,
+)
+from urllib.parse import urlparse
 
-from opentelemetry import context as context_api
-from opentelemetry.instrumentation.vertexai.config import Config
+from google.protobuf import json_format
 
-TRACELOOP_TRACE_CONTENT = "TRACELOOP_TRACE_CONTENT"
+from opentelemetry._logs import LogRecord
+from opentelemetry.instrumentation._semconv import (
+    _StabilityMode,
+)
+from opentelemetry.instrumentation.vertexai.events import (
+    ChoiceMessage,
+    ChoiceToolCall,
+    assistant_event,
+    choice_event,
+    system_event,
+    tool_event,
+    user_event,
+)
+from opentelemetry.semconv._incubating.attributes import (
+    gen_ai_attributes as GenAIAttributes,
+)
+from opentelemetry.semconv.attributes import server_attributes
+from opentelemetry.util.genai.types import (
+    ContentCapturingMode,
+    FinishReason,
+    MessagePart,
+    Text,
+    ToolCall,
+    ToolCallResponse,
+)
+from opentelemetry.util.genai.utils import get_content_capturing_mode
+from opentelemetry.util.types import AnyValue, AttributeValue
 
+if TYPE_CHECKING:
+    from google.cloud.aiplatform_v1.types import (
+        content,
+        prediction_service,
+        tool,
+    )
+    from google.cloud.aiplatform_v1beta1.types import (
+        content as content_v1beta1,
+    )
+    from google.cloud.aiplatform_v1beta1.types import (
+        prediction_service as prediction_service_v1beta1,
+    )
+    from google.cloud.aiplatform_v1beta1.types import (
+        tool as tool_v1beta1,
+    )
 
-def should_send_prompts():
-    return (
-        os.getenv(TRACELOOP_TRACE_CONTENT) or "true"
-    ).lower() == "true" or context_api.get_value("override_enable_content_tracing")
 
+_MODEL = "model"
 
-def dont_throw(func):
-    """
-    A decorator that wraps the passed in function and logs exceptions instead of throwing them.
 
-    @param func: The function to wrap
-    @return: The wrapper function
+@dataclass(frozen=True)
+class GenerateContentParams:
+    model: str
+    contents: (
+        Sequence[content.Content] | Sequence[content_v1beta1.Content] | None
+    ) = None
+    system_instruction: content.Content | content_v1beta1.Content | None = None
+    tools: Sequence[tool.Tool] | Sequence[tool_v1beta1.Tool] | None = None
+    tool_config: tool.ToolConfig | tool_v1beta1.ToolConfig | None = None
+    labels: Mapping[str, str] | None = None
+    safety_settings: (
+        Sequence[content.SafetySetting]
+        | Sequence[content_v1beta1.SafetySetting]
+        | None
+    ) = None
+    generation_config: (
+        content.GenerationConfig | content_v1beta1.GenerationConfig | None
+    ) = None
+
+
+def get_server_attributes(
+    endpoint: str,
+) -> dict[str, AttributeValue]:
+    """Get server.* attributes from the endpoint, which is a hostname with optional port e.g.
+    - ``us-central1-aiplatform.googleapis.com``
+    - ``us-central1-aiplatform.googleapis.com:5431``
     """
-    # Obtain a logger specific to the function's module
-    logger = logging.getLogger(func.__module__)
+    parsed = urlparse(f"scheme://{endpoint}")
+
+    if not parsed.hostname:
+        return {}
+
+    return {
+        server_attributes.SERVER_ADDRESS: parsed.hostname,
+        server_attributes.SERVER_PORT: parsed.port or 443,
+    }
 
-    def wrapper(*args, **kwargs):
-        try:
-            return func(*args, **kwargs)
-        except Exception as e:
-            logger.debug(
-                "OpenLLMetry failed to trace in %s, error: %s",
-                func.__name__,
-                traceback.format_exc(),
+
+def get_genai_request_attributes(  # pylint: disable=too-many-branches
+    use_latest_semconvs: bool,
+    params: GenerateContentParams,
+    operation_name: GenAIAttributes.GenAiOperationNameValues = GenAIAttributes.GenAiOperationNameValues.CHAT,
+):
+    model = _get_model_name(params.model)
+    generation_config = params.generation_config
+    attributes: dict[str, AttributeValue] = {
+        GenAIAttributes.GEN_AI_OPERATION_NAME: operation_name.value,
+        GenAIAttributes.GEN_AI_REQUEST_MODEL: model,
+    }
+    if not use_latest_semconvs:
+        attributes[GenAIAttributes.GEN_AI_SYSTEM] = (
+            GenAIAttributes.GenAiSystemValues.VERTEX_AI.value
+        )
+
+    if not generation_config:
+        return attributes
+
+    # Check for optional fields
+    # https://proto-plus-python.readthedocs.io/en/stable/fields.html#optional-fields
+    if "temperature" in generation_config:
+        attributes[GenAIAttributes.GEN_AI_REQUEST_TEMPERATURE] = (
+            generation_config.temperature
+        )
+    if "top_p" in generation_config:
+        # There is also a top_k parameter ( The maximum number of tokens to consider when sampling.),
+        # but no semconv yet exists for it.
+        attributes[GenAIAttributes.GEN_AI_REQUEST_TOP_P] = (
+            generation_config.top_p
+        )
+    if "max_output_tokens" in generation_config:
+        attributes[GenAIAttributes.GEN_AI_REQUEST_MAX_TOKENS] = (
+            generation_config.max_output_tokens
+        )
+    if "presence_penalty" in generation_config:
+        attributes[GenAIAttributes.GEN_AI_REQUEST_PRESENCE_PENALTY] = (
+            generation_config.presence_penalty
+        )
+    if "frequency_penalty" in generation_config:
+        attributes[GenAIAttributes.GEN_AI_REQUEST_FREQUENCY_PENALTY] = (
+            generation_config.frequency_penalty
+        )
+    if "stop_sequences" in generation_config:
+        attributes[GenAIAttributes.GEN_AI_REQUEST_STOP_SEQUENCES] = (
+            generation_config.stop_sequences
+        )
+    if use_latest_semconvs:
+        if "seed" in generation_config:
+            attributes[GenAIAttributes.GEN_AI_REQUEST_SEED] = (
+                generation_config.seed
+            )
+        if "candidate_count" in generation_config:
+            attributes[GenAIAttributes.GEN_AI_REQUEST_CHOICE_COUNT] = (
+                generation_config.candidate_count
             )
-            if Config.exception_logger:
-                Config.exception_logger(e)
+        if "response_mime_type" in generation_config:
+            if generation_config.response_mime_type == "text/plain":
+                attributes[GenAIAttributes.GEN_AI_OUTPUT_TYPE] = "text"
+            elif generation_config.response_mime_type == "application/json":
+                attributes[GenAIAttributes.GEN_AI_OUTPUT_TYPE] = "json"
+            else:
+                attributes[GenAIAttributes.GEN_AI_OUTPUT_TYPE] = (
+                    generation_config.response_mime_type
+                )
+
+    return attributes
+
+
+def get_genai_response_attributes(
+    response: prediction_service.GenerateContentResponse
+    | prediction_service_v1beta1.GenerateContentResponse
+    | None,
+) -> dict[str, AttributeValue]:
+    if not response:
+        return {}
+    finish_reasons: list[str] = [
+        _map_finish_reason(candidate.finish_reason)
+        for candidate in response.candidates
+    ]
+    return {
+        GenAIAttributes.GEN_AI_RESPONSE_MODEL: response.model_version,
+        GenAIAttributes.GEN_AI_RESPONSE_FINISH_REASONS: finish_reasons,
+        GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS: response.usage_metadata.prompt_token_count,
+        GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS: response.usage_metadata.candidates_token_count,
+    }
+
+
+_MODEL_STRIP_RE = re.compile(
+    r"^projects/(.*)/locations/(.*)/publishers/google/models/"
+)
+
+
+def _get_model_name(model: str) -> str:
+    return _MODEL_STRIP_RE.sub("", model)
+
+
+OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT = (
+    "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
+)
+
+
+@overload
+def is_content_enabled(
+    mode: Literal[_StabilityMode.GEN_AI_LATEST_EXPERIMENTAL],
+) -> ContentCapturingMode: ...
+
+
+@overload
+def is_content_enabled(mode: Literal[_StabilityMode.DEFAULT]) -> bool: ...
+
+
+def is_content_enabled(
+    mode: Union[
+        Literal[_StabilityMode.DEFAULT],
+        Literal[_StabilityMode.GEN_AI_LATEST_EXPERIMENTAL],
+    ],
+) -> Union[bool, ContentCapturingMode]:
+    if mode == _StabilityMode.DEFAULT:
+        capture_content = environ.get(
+            OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT, "false"
+        )
+
+        return capture_content.lower() == "true"
+    return get_content_capturing_mode()
+
+
+def get_span_name(span_attributes: Mapping[str, AttributeValue]) -> str:
+    name = span_attributes[GenAIAttributes.GEN_AI_OPERATION_NAME]
+    model = span_attributes[GenAIAttributes.GEN_AI_REQUEST_MODEL]
+    if not model:
+        return f"{name}"
+    return f"{name} {model}"
+
+
+def request_to_events(
+    *, params: GenerateContentParams, capture_content: bool
+) -> Iterable[LogRecord]:
+    # System message
+    if params.system_instruction:
+        request_content = _parts_to_any_value(
+            capture_content=capture_content,
+            parts=params.system_instruction.parts,
+        )
+        yield system_event(
+            role=params.system_instruction.role, content=request_content
+        )
+
+    for content in params.contents or []:
+        # Assistant message
+        if content.role == _MODEL:
+            request_content = _parts_to_any_value(
+                capture_content=capture_content, parts=content.parts
+            )
+
+            yield assistant_event(role=content.role, content=request_content)
+            continue
+
+        # Tool event
+        #
+        # Function call results can be parts inside of a user Content or in a separate Content
+        # entry without a role. That may cause duplication in a user event, see
+        # https://github.com/open-telemetry/opentelemetry-python-contrib/issues/3280
+        function_responses = [
+            part.function_response
+            for part in content.parts
+            if "function_response" in part
+        ]
+        for idx, function_response in enumerate(function_responses):
+            yield tool_event(
+                id_=f"{function_response.name}_{idx}",
+                role=content.role,
+                content=json_format.MessageToDict(
+                    function_response._pb.response  # type: ignore[reportUnknownMemberType]
+                )
+                if capture_content
+                else None,
+            )
+
+        if len(function_responses) == len(content.parts):
+            # If the content only contained function responses, don't emit a user event
+            continue
+
+        request_content = _parts_to_any_value(
+            capture_content=capture_content, parts=content.parts
+        )
+        yield user_event(role=content.role, content=request_content)
+
+
+@dataclass
+class BlobPart:
+    data: bytes
+    mime_type: str
+    type: Literal["blob"] = "blob"
+
+
+@dataclass
+class FileDataPart:
+    mime_type: str
+    uri: str
+    type: Literal["file_data"] = "file_data"
+
+    class Config:
+        extra = "allow"
+
+
+def convert_content_to_message_parts(
+    content: content.Content | content_v1beta1.Content,
+) -> list[MessagePart]:
+    parts: MessagePart = []
+    for idx, part in enumerate(content.parts):
+        if "function_response" in part:
+            part = part.function_response
+            parts.append(
+                ToolCallResponse(
+                    id=f"{part.name}_{idx}",
+                    response=json_format.MessageToDict(part._pb.response),  # type: ignore[reportUnknownMemberType]
+                )
+            )
+        elif "function_call" in part:
+            part = part.function_call
+            parts.append(
+                ToolCall(
+                    id=f"{part.name}_{idx}",
+                    name=part.name,
+                    arguments=json_format.MessageToDict(
+                        part._pb.args,  # type: ignore[reportUnknownMemberType]
+                    ),
+                )
+            )
+        elif "text" in part:
+            parts.append(Text(content=part.text))
+        elif "inline_data" in part:
+            part = part.inline_data
+            parts.append(
+                BlobPart(mime_type=part.mime_type or "", data=part.data or b"")
+            )
+        elif "file_data" in part:
+            part = part.file_data
+            parts.append(
+                FileDataPart(
+                    mime_type=part.mime_type or "", uri=part.file_uri or ""
+                )
+            )
+        else:
+            logging.warning("Unknown part dropped from telemetry %s", part)
+    return parts
+
+
+def response_to_events(
+    *,
+    response: prediction_service.GenerateContentResponse
+    | prediction_service_v1beta1.GenerateContentResponse,
+    capture_content: bool,
+) -> Iterable[LogRecord]:
+    for candidate in response.candidates:
+        tool_calls = _extract_tool_calls(
+            candidate=candidate, capture_content=capture_content
+        )
+
+        # The original function_call Part is still duplicated in message, see
+        # https://github.com/open-telemetry/opentelemetry-python-contrib/issues/3280
+        yield choice_event(
+            finish_reason=_map_finish_reason(candidate.finish_reason),
+            index=candidate.index,
+            # default to "model" since Vertex uses that instead of assistant
+            message=ChoiceMessage(
+                role=candidate.content.role or _MODEL,
+                content=_parts_to_any_value(
+                    capture_content=capture_content,
+                    parts=candidate.content.parts,
+                ),
+            ),
+            tool_calls=tool_calls,
+        )
+
+
+def _extract_tool_calls(
+    *,
+    candidate: content.Candidate | content_v1beta1.Candidate,
+    capture_content: bool,
+) -> Iterable[ChoiceToolCall]:
+    for idx, part in enumerate(candidate.content.parts):
+        if "function_call" not in part:
+            continue
+
+        yield ChoiceToolCall(
+            # Make up an id with index since vertex expects the indices to line up instead of
+            # using ids.
+            id=f"{part.function_call.name}_{idx}",
+            function=ChoiceToolCall.Function(
+                name=part.function_call.name,
+                arguments=json_format.MessageToDict(
+                    part.function_call._pb.args  # type: ignore[reportUnknownMemberType]
+                )
+                if capture_content
+                else None,
+            ),
+        )
+
+
+def _parts_to_any_value(
+    *,
+    capture_content: bool,
+    parts: Sequence[content.Part] | Sequence[content_v1beta1.Part],
+) -> list[dict[str, AnyValue]] | None:
+    if not capture_content:
+        return None
+
+    return [
+        cast(
+            "dict[str, AnyValue]",
+            type(part).to_dict(  # type: ignore[reportUnknownMemberType]
+                part, always_print_fields_with_no_presence=False
+            ),
+        )
+        for part in parts
+    ]
 
-    return wrapper
 
+def _map_finish_reason(
+    finish_reason: content.Candidate.FinishReason
+    | content_v1beta1.Candidate.FinishReason,
+) -> FinishReason | str:
+    EnumType = type(finish_reason)  # pylint: disable=invalid-name
+    if (
+        finish_reason is EnumType.FINISH_REASON_UNSPECIFIED
+        or finish_reason is EnumType.OTHER
+    ):
+        return "error"
+    if finish_reason is EnumType.STOP:
+        return "stop"
+    if finish_reason is EnumType.MAX_TOKENS:
+        return "length"
 
-def should_emit_events():
-    return not Config.use_legacy_attributes
+    # If there is no 1:1 mapping to an OTel preferred enum value, use the exact vertex reason
+    return finish_reason.name

opentelemetry/instrumentation/vertexai/version.py

@@ -1 +1,15 @@
-__version__ = "0.47.3"
+# 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.
+
+__version__ = "2.1b0"

opentelemetry_instrumentation_vertexai-2.1b0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: opentelemetry-instrumentation-vertexai
+Version: 2.1b0
+Summary: OpenTelemetry Official VertexAI instrumentation
+Project-URL: Homepage, https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation-genai/opentelemetry-instrumentation-vertexai
+Project-URL: Repository, https://github.com/open-telemetry/opentelemetry-python-contrib
+Author-email: OpenTelemetry Authors <cncf-opentelemetry-contributors@lists.cncf.io>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: opentelemetry-api~=1.37
+Requires-Dist: opentelemetry-instrumentation~=0.58b0
+Requires-Dist: opentelemetry-semantic-conventions~=0.58b0
+Requires-Dist: opentelemetry-util-genai<0.3b0,>=0.2b0
+Provides-Extra: instruments
+Requires-Dist: google-cloud-aiplatform>=1.64; extra == 'instruments'
+Description-Content-Type: text/x-rst
+
+OpenTelemetry VertexAI Instrumentation
+======================================
+
+|pypi|
+
+.. |pypi| image:: https://badge.fury.io/py/opentelemetry-instrumentation-vertexai.svg
+   :target: https://pypi.org/project/opentelemetry-instrumentation-vertexai/
+
+This library allows tracing LLM requests and logging of messages made by the
+`VertexAI Python API library <https://pypi.org/project/google-cloud-aiplatform/>`_.
+
+
+Installation
+------------
+
+If your application is already instrumented with OpenTelemetry, add this
+package to your requirements.
+::
+
+    pip install opentelemetry-instrumentation-vertexai
+
+If you don't have an VertexAI application, yet, try our `examples <examples>`_.
+
+Check out `zero-code example <examples/zero-code>`_ for a quick start.
+
+Usage
+-----
+
+This section describes how to set up VertexAI instrumentation if you're setting OpenTelemetry up manually.
+Check out the `manual example <examples/manual>`_ for more details.
+
+Instrumenting all clients
+*************************
+
+When using the instrumentor, all clients will automatically trace VertexAI chat completion operations.
+You can also optionally capture prompts and completions as log events.
+
+Make sure to configure OpenTelemetry tracing, logging, and events to capture all telemetry emitted by the instrumentation.
+
+.. code-block:: python
+
+    from opentelemetry.instrumentation.vertexai import VertexAIInstrumentor
+    from vertexai.generative_models import GenerativeModel
+
+    VertexAIInstrumentor().instrument()
+
+
+    vertexai.init()
+    model = GenerativeModel("gemini-1.5-flash-002")
+    response = model.generate_content("Write a short poem on OpenTelemetry.")
+
+Enabling message content
+*************************
+
+Message content such as the contents of the prompt, completion, function arguments and return values
+are not captured by default. To capture message content as log events, set the environment variable
+`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` to `true`.
+
+Uninstrument
+************
+
+To uninstrument clients, call the uninstrument method:
+
+.. code-block:: python
+
+    from opentelemetry.instrumentation.vertexai import VertexAIInstrumentor
+
+    VertexAIInstrumentor().instrument()
+    # ...
+
+    # Uninstrument all clients
+    VertexAIInstrumentor().uninstrument()
+
+References
+----------
+* `OpenTelemetry VertexAI Instrumentation <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/vertexai/vertexai.html>`_
+* `OpenTelemetry Project <https://opentelemetry.io/>`_
+* `OpenTelemetry Python Examples <https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples>`_
+

opentelemetry_instrumentation_vertexai-2.1b0.dist-info/RECORD

@@ -0,0 +1,12 @@
+opentelemetry/instrumentation/vertexai/__init__.py,sha256=h2ikRd_hLXscLwbacyfCY5fdFYH76iMxkHHr8r1AeCU,6010
+opentelemetry/instrumentation/vertexai/events.py,sha256=EHp1uqJ-vMKJ5jVxRgHNyboN51JUYEPcXcT3yV5rcRE,5274
+opentelemetry/instrumentation/vertexai/package.py,sha256=CFLAAZb6L_fDNfJgpW-cXjhiQjwGLAuxhdAjMNt3jPM,638
+opentelemetry/instrumentation/vertexai/patch.py,sha256=_YZpMo14k-ccy8VcNbl9rG7VsztLorcS12an6e8wJx8,13543
+opentelemetry/instrumentation/vertexai/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+opentelemetry/instrumentation/vertexai/utils.py,sha256=CxOypyBGjpuaKX4lijomyGBupiViC_TpYHgiCTR2nGE,15001
+opentelemetry/instrumentation/vertexai/version.py,sha256=tlQVIB6SsAnJ7uZmREAk0QDaATSCgbgYwdtY4G8GX9M,607
+opentelemetry_instrumentation_vertexai-2.1b0.dist-info/METADATA,sha256=tXZDreIfz0gB64b5zYAdufFr3WdjRL6hB_1k4ynrrL4,3946
+opentelemetry_instrumentation_vertexai-2.1b0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+opentelemetry_instrumentation_vertexai-2.1b0.dist-info/entry_points.txt,sha256=aAbxWr7zIDuYms-m-ea5GEV2rqyx7xPT8FWr2umrCmU,100
+opentelemetry_instrumentation_vertexai-2.1b0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+opentelemetry_instrumentation_vertexai-2.1b0.dist-info/RECORD,,

{opentelemetry_instrumentation_vertexai-0.47.3.dist-info → opentelemetry_instrumentation_vertexai-2.1b0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.2.0
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any

opentelemetry_instrumentation_vertexai-2.1b0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[opentelemetry_instrumentor]
+vertexai = opentelemetry.instrumentation.vertexai:VertexAIInstrumentor