google-cloud-spanner 3.55.0__py3-none-any.whl

google/cloud/spanner_v1/metrics/metrics_tracer_factory.py

@@ -0,0 +1,328 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
+"""Factory for creating MetricTracer instances, facilitating metrics collection and tracing."""
+
+from google.cloud.spanner_v1.metrics.metrics_tracer import MetricsTracer
+
+from google.cloud.spanner_v1.metrics.constants import (
+    METRIC_NAME_OPERATION_LATENCIES,
+    MONITORED_RES_LABEL_KEY_PROJECT,
+    METRIC_NAME_ATTEMPT_LATENCIES,
+    METRIC_NAME_OPERATION_COUNT,
+    METRIC_NAME_ATTEMPT_COUNT,
+    MONITORED_RES_LABEL_KEY_INSTANCE,
+    MONITORED_RES_LABEL_KEY_INSTANCE_CONFIG,
+    MONITORED_RES_LABEL_KEY_LOCATION,
+    MONITORED_RES_LABEL_KEY_CLIENT_HASH,
+    METRIC_LABEL_KEY_CLIENT_UID,
+    METRIC_LABEL_KEY_CLIENT_NAME,
+    METRIC_LABEL_KEY_DATABASE,
+    METRIC_LABEL_KEY_DIRECT_PATH_ENABLED,
+    BUILT_IN_METRICS_METER_NAME,
+    METRIC_NAME_GFE_LATENCY,
+    METRIC_NAME_GFE_MISSING_HEADER_COUNT,
+)
+
+from typing import Dict
+
+try:
+    from opentelemetry.metrics import Counter, Histogram, get_meter_provider
+
+    HAS_OPENTELEMETRY_INSTALLED = True
+except ImportError:  # pragma: NO COVER
+    HAS_OPENTELEMETRY_INSTALLED = False
+
+from google.cloud.spanner_v1 import __version__
+
+
+class MetricsTracerFactory:
+    """Factory class for creating MetricTracer instances. This class facilitates the creation of MetricTracer objects, which are responsible for collecting and tracing metrics."""
+
+    enabled: bool
+    gfe_enabled: bool
+    _instrument_attempt_latency: "Histogram"
+    _instrument_attempt_counter: "Counter"
+    _instrument_operation_latency: "Histogram"
+    _instrument_operation_counter: "Counter"
+    _instrument_gfe_latency: "Histogram"
+    _instrument_gfe_missing_header_count: "Counter"
+    _client_attributes: Dict[str, str]
+
+    @property
+    def instrument_attempt_latency(self) -> "Histogram":
+        return self._instrument_attempt_latency
+
+    @property
+    def instrument_attempt_counter(self) -> "Counter":
+        return self._instrument_attempt_counter
+
+    @property
+    def instrument_operation_latency(self) -> "Histogram":
+        return self._instrument_operation_latency
+
+    @property
+    def instrument_operation_counter(self) -> "Counter":
+        return self._instrument_operation_counter
+
+    def __init__(self, enabled: bool, service_name: str):
+        """Initialize a MetricsTracerFactory instance with the given parameters.
+
+        This constructor initializes a MetricsTracerFactory instance with the provided service name, project, instance, instance configuration, location, client hash, client UID, client name, and database. It sets up the necessary metric instruments and client attributes for metrics tracing.
+
+        Args:
+            service_name (str): The name of the service for which metrics are being traced.
+            project (str): The project ID for the monitored resource.
+        """
+        self.enabled = enabled
+        self._create_metric_instruments(service_name)
+        self._client_attributes = {}
+
+    @property
+    def client_attributes(self) -> Dict[str, str]:
+        """Return a dictionary of client attributes used for metrics tracing.
+
+        This property returns a dictionary containing client attributes such as project, instance,
+        instance configuration, location, client hash, client UID, client name, and database.
+        These attributes are used to provide context to the metrics being traced.
+
+        Returns:
+            dict[str, str]: A dictionary of client attributes.
+        """
+        return self._client_attributes
+
+    def set_project(self, project: str) -> "MetricsTracerFactory":
+        """Set the project attribute for metrics tracing.
+
+        This method updates the client attributes dictionary with the provided project name.
+        The project name is used to identify the project for which metrics are being traced
+        and is passed to the created MetricsTracer.
+
+        Args:
+            project (str): The name of the project for metrics tracing.
+
+        Returns:
+            MetricsTracerFactory: The current instance of MetricsTracerFactory to enable method chaining.
+        """
+        self._client_attributes[MONITORED_RES_LABEL_KEY_PROJECT] = project
+        return self
+
+    def set_instance(self, instance: str) -> "MetricsTracerFactory":
+        """Set the instance attribute for metrics tracing.
+
+        This method updates the client attributes dictionary with the provided instance name.
+        The instance name is used to identify the instance for which metrics are being traced
+        and is passed to the created MetricsTracer.
+
+        Args:
+            instance (str): The name of the instance for metrics tracing.
+
+        Returns:
+            MetricsTracerFactory: The current instance of MetricsTracerFactory to enable method chaining.
+        """
+        self._client_attributes[MONITORED_RES_LABEL_KEY_INSTANCE] = instance
+        return self
+
+    def set_instance_config(self, instance_config: str) -> "MetricsTracerFactory":
+        """Sets the instance configuration attribute for metrics tracing.
+
+        This method updates the client attributes dictionary with the provided instance configuration.
+        The instance configuration is used to identify the configuration of the instance for which
+        metrics are being traced and is passed to the created MetricsTracer.
+
+        Args:
+            instance_config (str): The configuration of the instance for metrics tracing.
+
+        Returns:
+            MetricsTracerFactory: The current instance of MetricsTracerFactory to enable method chaining.
+        """
+        self._client_attributes[
+            MONITORED_RES_LABEL_KEY_INSTANCE_CONFIG
+        ] = instance_config
+        return self
+
+    def set_location(self, location: str) -> "MetricsTracerFactory":
+        """Set the location attribute for metrics tracing.
+
+        This method updates the client attributes dictionary with the provided location.
+        The location is used to identify the location for which metrics are being traced
+        and is passed to the created MetricsTracer.
+
+        Args:
+            location (str): The location for metrics tracing.
+
+        Returns:
+            MetricsTracerFactory: The current instance of MetricsTracerFactory to enable method chaining.
+        """
+        self._client_attributes[MONITORED_RES_LABEL_KEY_LOCATION] = location
+        return self
+
+    def set_client_hash(self, hash: str) -> "MetricsTracerFactory":
+        """Set the client hash attribute for metrics tracing.
+
+        This method updates the client attributes dictionary with the provided client hash.
+        The client hash is used to identify the client for which metrics are being traced
+        and is passed to the created MetricsTracer.
+
+        Args:
+            hash (str): The hash of the client for metrics tracing.
+
+        Returns:
+            MetricsTracerFactory: The current instance of MetricsTracerFactory to enable method chaining.
+        """
+        self._client_attributes[MONITORED_RES_LABEL_KEY_CLIENT_HASH] = hash
+        return self
+
+    def set_client_uid(self, client_uid: str) -> "MetricsTracerFactory":
+        """Set the client UID attribute for metrics tracing.
+
+        This method updates the client attributes dictionary with the provided client UID.
+        The client UID is used to identify the client for which metrics are being traced
+        and is passed to the created MetricsTracer.
+
+        Args:
+            client_uid (str): The UID of the client for metrics tracing.
+
+        Returns:
+            MetricsTracerFactory: The current instance of MetricsTracerFactory to enable method chaining.
+        """
+        self._client_attributes[METRIC_LABEL_KEY_CLIENT_UID] = client_uid
+        return self
+
+    def set_client_name(self, client_name: str) -> "MetricsTracerFactory":
+        """Set the client name attribute for metrics tracing.
+
+        This method updates the client attributes dictionary with the provided client name.
+        The client name is used to identify the client for which metrics are being traced
+        and is passed to the created MetricsTracer.
+
+        Args:
+            client_name (str): The name of the client for metrics tracing.
+
+        Returns:
+            MetricsTracerFactory: The current instance of MetricsTracerFactory to enable method chaining.
+        """
+        self._client_attributes[METRIC_LABEL_KEY_CLIENT_NAME] = client_name
+        return self
+
+    def set_database(self, database: str) -> "MetricsTracerFactory":
+        """Set the database attribute for metrics tracing.
+
+        This method updates the client attributes dictionary with the provided database name.
+        The database name is used to identify the database for which metrics are being traced
+        and is passed to the created MetricsTracer.
+
+        Args:
+            database (str): The name of the database for metrics tracing.
+
+        Returns:
+            MetricsTracerFactory: The current instance of MetricsTracerFactory to enable method chaining.
+        """
+        self._client_attributes[METRIC_LABEL_KEY_DATABASE] = database
+        return self
+
+    def enable_direct_path(self, enable: bool = False) -> "MetricsTracerFactory":
+        """Enable or disable the direct path for metrics tracing.
+
+        This method updates the client attributes dictionary with the provided enable status.
+        The direct path enabled status is used to determine whether to use the direct path for metrics tracing
+        and is passed to the created MetricsTracer.
+
+        Args:
+            enable (bool, optional): Whether to enable the direct path for metrics tracing. Defaults to False.
+
+        Returns:
+            MetricsTracerFactory: The current instance of MetricsTracerFactory to enable method chaining.
+        """
+        self._client_attributes[METRIC_LABEL_KEY_DIRECT_PATH_ENABLED] = enable
+        return self
+
+    def create_metrics_tracer(self) -> MetricsTracer:
+        """
+        Create and return a MetricsTracer instance with default settings and client attributes.
+
+        This method initializes a MetricsTracer instance with default settings for metrics tracing,
+        including metrics tracing enabled if OpenTelemetry is installed and the direct path disabled by default.
+        It also sets the client attributes based on the factory's configuration.
+
+        Returns:
+            MetricsTracer: A MetricsTracer instance with default settings and client attributes.
+        """
+        if not HAS_OPENTELEMETRY_INSTALLED:
+            return None
+
+        metrics_tracer = MetricsTracer(
+            enabled=self.enabled and HAS_OPENTELEMETRY_INSTALLED,
+            instrument_attempt_latency=self._instrument_attempt_latency,
+            instrument_attempt_counter=self._instrument_attempt_counter,
+            instrument_operation_latency=self._instrument_operation_latency,
+            instrument_operation_counter=self._instrument_operation_counter,
+            client_attributes=self._client_attributes.copy(),
+        )
+        return metrics_tracer
+
+    def _create_metric_instruments(self, service_name: str) -> None:
+        """
+        Creates and sets up metric instruments for the given service name.
+
+        This method initializes and configures metric instruments for attempt latency, attempt counter,
+        operation latency, and operation counter. These instruments are used to measure and track
+        metrics related to attempts and operations within the service.
+
+        Args:
+            service_name (str): The name of the service for which metric instruments are being created.
+        """
+        if not HAS_OPENTELEMETRY_INSTALLED:  # pragma: NO COVER
+            return
+
+        meter_provider = get_meter_provider()
+        meter = meter_provider.get_meter(
+            name=BUILT_IN_METRICS_METER_NAME, version=__version__
+        )
+
+        self._instrument_attempt_latency = meter.create_histogram(
+            name=METRIC_NAME_ATTEMPT_LATENCIES,
+            unit="ms",
+            description="Time an individual attempt took.",
+        )
+
+        self._instrument_attempt_counter = meter.create_counter(
+            name=METRIC_NAME_ATTEMPT_COUNT,
+            unit="1",
+            description="Number of attempts.",
+        )
+
+        self._instrument_operation_latency = meter.create_histogram(
+            name=METRIC_NAME_OPERATION_LATENCIES,
+            unit="ms",
+            description="Total time until final operation success or failure, including retries and backoff.",
+        )
+
+        self._instrument_operation_counter = meter.create_counter(
+            name=METRIC_NAME_OPERATION_COUNT,
+            unit="1",
+            description="Number of operations.",
+        )
+
+        self._instrument_gfe_latency = meter.create_histogram(
+            name=METRIC_NAME_GFE_LATENCY,
+            unit="ms",
+            description="GFE Latency.",
+        )
+
+        self._instrument_gfe_missing_header_count = meter.create_counter(
+            name=METRIC_NAME_GFE_MISSING_HEADER_COUNT,
+            unit="1",
+            description="GFE missing header count.",
+        )

google/cloud/spanner_v1/metrics/spanner_metrics_tracer_factory.py

@@ -0,0 +1,172 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
+
+"""This module provides a singleton factory for creating SpannerMetricsTracer instances."""
+
+from .metrics_tracer_factory import MetricsTracerFactory
+import os
+from .constants import (
+    SPANNER_SERVICE_NAME,
+    GOOGLE_CLOUD_REGION_KEY,
+    GOOGLE_CLOUD_REGION_GLOBAL,
+)
+
+try:
+    from opentelemetry.resourcedetector import gcp_resource_detector
+
+    # Overwrite the requests timeout for the detector.
+    # This is necessary as the client will wait the full timeout if the
+    # code is not run in a GCP environment, with the location endpoints available.
+    gcp_resource_detector._TIMEOUT_SEC = 0.2
+
+    import mmh3
+
+    # Override Resource detector logging to not warn when GCP resources are not detected
+    import logging
+
+    logging.getLogger("opentelemetry.resourcedetector.gcp_resource_detector").setLevel(
+        logging.ERROR
+    )
+
+    HAS_OPENTELEMETRY_INSTALLED = True
+except ImportError:  # pragma: NO COVER
+    HAS_OPENTELEMETRY_INSTALLED = False
+
+from .metrics_tracer import MetricsTracer
+from google.cloud.spanner_v1 import __version__
+from uuid import uuid4
+
+
+class SpannerMetricsTracerFactory(MetricsTracerFactory):
+    """A factory for creating SpannerMetricsTracer instances."""
+
+    _metrics_tracer_factory: "SpannerMetricsTracerFactory" = None
+    current_metrics_tracer: MetricsTracer = None
+
+    def __new__(
+        cls, enabled: bool = True, gfe_enabled: bool = False
+    ) -> "SpannerMetricsTracerFactory":
+        """
+        Create a new instance of SpannerMetricsTracerFactory if it doesn't already exist.
+
+        This method implements the singleton pattern for the SpannerMetricsTracerFactory class.
+        It initializes the factory with the necessary client attributes and configuration settings
+        if it hasn't been created yet.
+
+        Args:
+            enabled (bool): A flag indicating whether metrics tracing is enabled. Defaults to True.
+            gfe_enabled (bool): A flag indicating whether GFE metrics are enabled. Defaults to False.
+
+        Returns:
+            SpannerMetricsTracerFactory: The singleton instance of SpannerMetricsTracerFactory.
+        """
+        if cls._metrics_tracer_factory is None:
+            cls._metrics_tracer_factory = MetricsTracerFactory(
+                enabled, SPANNER_SERVICE_NAME
+            )
+            if not HAS_OPENTELEMETRY_INSTALLED:
+                return cls._metrics_tracer_factory
+
+            client_uid = cls._generate_client_uid()
+            cls._metrics_tracer_factory.set_client_uid(client_uid)
+            cls._metrics_tracer_factory.set_instance_config(cls._get_instance_config())
+            cls._metrics_tracer_factory.set_client_name(cls._get_client_name())
+            cls._metrics_tracer_factory.set_client_hash(
+                cls._generate_client_hash(client_uid)
+            )
+            cls._metrics_tracer_factory.set_location(cls._get_location())
+            cls._metrics_tracer_factory.gfe_enabled = gfe_enabled
+
+            if cls._metrics_tracer_factory.enabled != enabled:
+                cls._metrics_tracer_factory.enabeld = enabled
+
+        return cls._metrics_tracer_factory
+
+    @staticmethod
+    def _generate_client_uid() -> str:
+        """Generate a client UID in the form of uuidv4@pid@hostname.
+
+        This method generates a unique client identifier (UID) by combining a UUID version 4,
+        the process ID (PID), and the hostname. The PID is limited to the first 10 characters.
+
+        Returns:
+            str: A string representing the client UID in the format uuidv4@pid@hostname.
+        """
+        try:
+            hostname = os.uname()[1]
+            pid = str(os.getpid())[0:10]  # Limit PID to 10 characters
+            uuid = uuid4()
+            return f"{uuid}@{pid}@{hostname}"
+        except Exception:
+            return ""
+
+    @staticmethod
+    def _get_instance_config() -> str:
+        """Get the instance configuration."""
+        # TODO: unknown until there's a good way to get it.
+        return "unknown"
+
+    @staticmethod
+    def _get_client_name() -> str:
+        """Get the client name."""
+        return f"{SPANNER_SERVICE_NAME}/{__version__}"
+
+    @staticmethod
+    def _generate_client_hash(client_uid: str) -> str:
+        """
+        Generate a 6-digit zero-padded lowercase hexadecimal hash using the 10 most significant bits of a 64-bit hash value.
+
+        The primary purpose of this function is to generate a hash value for the `client_hash`
+        resource label using `client_uid` metric field. The range of values is chosen to be small
+        enough to keep the cardinality of the Resource targets under control. Note: If at later time
+        the range needs to be increased, it can be done by increasing the value of `kPrefixLength` to
+        up to 24 bits without changing the format of the returned value.
+
+        Args:
+            client_uid (str): The client UID used to generate the hash.
+
+        Returns:
+            str: A 6-digit zero-padded lowercase hexadecimal hash.
+        """
+        if not client_uid:
+            return "000000"
+        hashed_client = mmh3.hash64(client_uid)
+
+        # Join the hashes back together since mmh3 splits into high and low 32bits
+        full_hash = (hashed_client[0] << 32) | (hashed_client[1] & 0xFFFFFFFF)
+        unsigned_hash = full_hash & 0xFFFFFFFFFFFFFFFF
+
+        k_prefix_length = 10
+        sig_figs = unsigned_hash >> (64 - k_prefix_length)
+
+        # Return as 6 digit zero padded hex string
+        return f"{sig_figs:06x}"
+
+    @staticmethod
+    def _get_location() -> str:
+        """Get the location of the resource.
+
+        Returns:
+            str: The location of the resource. If OpenTelemetry is not installed, returns a global region.
+        """
+        if not HAS_OPENTELEMETRY_INSTALLED:
+            return GOOGLE_CLOUD_REGION_GLOBAL
+        detector = gcp_resource_detector.GoogleCloudResourceDetector()
+        resources = detector.detect()
+
+        if GOOGLE_CLOUD_REGION_KEY not in resources.attributes:
+            return GOOGLE_CLOUD_REGION_GLOBAL
+        else:
+            return resources[GOOGLE_CLOUD_REGION_KEY]

google/cloud/spanner_v1/param_types.py

@@ -0,0 +1,110 @@
+# Copyright 2017 Google LLC All rights reserved.
+#
+# 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.
+
+"""Types exported from this package."""
+
+from google.cloud.spanner_v1 import Type
+from google.cloud.spanner_v1 import TypeAnnotationCode
+from google.cloud.spanner_v1 import TypeCode
+from google.cloud.spanner_v1 import StructType
+from google.protobuf.message import Message
+from google.protobuf.internal.enum_type_wrapper import EnumTypeWrapper
+
+
+# Scalar parameter types
+STRING = Type(code=TypeCode.STRING)
+BYTES = Type(code=TypeCode.BYTES)
+BOOL = Type(code=TypeCode.BOOL)
+INT64 = Type(code=TypeCode.INT64)
+FLOAT64 = Type(code=TypeCode.FLOAT64)
+FLOAT32 = Type(code=TypeCode.FLOAT32)
+DATE = Type(code=TypeCode.DATE)
+TIMESTAMP = Type(code=TypeCode.TIMESTAMP)
+NUMERIC = Type(code=TypeCode.NUMERIC)
+JSON = Type(code=TypeCode.JSON)
+PG_NUMERIC = Type(code=TypeCode.NUMERIC, type_annotation=TypeAnnotationCode.PG_NUMERIC)
+PG_JSONB = Type(code=TypeCode.JSON, type_annotation=TypeAnnotationCode.PG_JSONB)
+PG_OID = Type(code=TypeCode.INT64, type_annotation=TypeAnnotationCode.PG_OID)
+INTERVAL = Type(code=TypeCode.INTERVAL)
+
+
+def Array(element_type):
+    """Construct an array parameter type description protobuf.
+
+    :type element_type: :class:`~google.cloud.spanner_v1.types.Type`
+    :param element_type: the type of elements of the array
+
+    :rtype: :class:`google.cloud.spanner_v1.types.Type`
+    :returns: the appropriate array-type protobuf
+    """
+    return Type(code=TypeCode.ARRAY, array_element_type=element_type)
+
+
+def StructField(name, field_type):
+    """Construct a field description protobuf.
+
+    :type name: str
+    :param name: the name of the field
+
+    :type field_type: :class:`google.cloud.spanner_v1.types.Type`
+    :param field_type: the type of the field
+
+    :rtype: :class:`google.cloud.spanner_v1.types.StructType.Field`
+    :returns: the appropriate struct-field-type protobuf
+    """
+    return StructType.Field(name=name, type_=field_type)
+
+
+def Struct(fields):
+    """Construct a struct parameter type description protobuf.
+
+    :type fields: list of :class:`google.cloud.spanner_v1.types.StructType.Field`
+    :param fields: the fields of the struct
+
+    :rtype: :class:`type_pb2.Type`
+    :returns: the appropriate struct-type protobuf
+    """
+    return Type(code=TypeCode.STRUCT, struct_type=StructType(fields=fields))
+
+
+def ProtoMessage(proto_message_object):
+    """Construct a proto message type description protobuf.
+
+    :type proto_message_object: :class:`google.protobuf.message.Message`
+    :param proto_message_object: the proto message instance
+
+    :rtype: :class:`type_pb2.Type`
+    :returns: the appropriate proto-message-type protobuf
+    """
+    if not isinstance(proto_message_object, Message):
+        raise ValueError("Expected input object of type Proto Message.")
+    return Type(
+        code=TypeCode.PROTO, proto_type_fqn=proto_message_object.DESCRIPTOR.full_name
+    )
+
+
+def ProtoEnum(proto_enum_object):
+    """Construct a proto enum type description protobuf.
+
+    :type proto_enum_object: :class:`google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper`
+    :param proto_enum_object: the proto enum instance
+
+    :rtype: :class:`type_pb2.Type`
+    :returns: the appropriate proto-enum-type protobuf
+    """
+    if not isinstance(proto_enum_object, EnumTypeWrapper):
+        raise ValueError("Expected input object of type Proto Enum")
+    return Type(
+        code=TypeCode.ENUM, proto_type_fqn=proto_enum_object.DESCRIPTOR.full_name
+    )