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

google/cloud/spanner_v1/_opentelemetry_tracing.py

@@ -0,0 +1,165 @@
+# Copyright 2020 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.
+
+"""Manages OpenTelemetry trace creation and handling"""
+
+from contextlib import contextmanager
+from datetime import datetime
+import os
+
+from google.cloud.spanner_v1 import SpannerClient
+from google.cloud.spanner_v1 import gapic_version
+from google.cloud.spanner_v1._helpers import (
+    _metadata_with_span_context,
+)
+
+try:
+    from opentelemetry import trace
+    from opentelemetry.trace.status import Status, StatusCode
+    from opentelemetry.semconv.attributes.otel_attributes import (
+        OTEL_SCOPE_NAME,
+        OTEL_SCOPE_VERSION,
+    )
+
+    HAS_OPENTELEMETRY_INSTALLED = True
+except ImportError:
+    HAS_OPENTELEMETRY_INSTALLED = False
+
+from google.cloud.spanner_v1.metrics.metrics_capture import MetricsCapture
+
+TRACER_NAME = "cloud.google.com/python/spanner"
+TRACER_VERSION = gapic_version.__version__
+extended_tracing_globally_disabled = (
+    os.getenv("SPANNER_ENABLE_EXTENDED_TRACING", "").lower() == "false"
+)
+end_to_end_tracing_globally_enabled = (
+    os.getenv("SPANNER_ENABLE_END_TO_END_TRACING", "").lower() == "true"
+)
+
+
+def get_tracer(tracer_provider=None):
+    """
+    get_tracer is a utility to unify and simplify retrieval of the tracer, without
+    leaking implementation details given that retrieving a tracer requires providing
+    the full qualified library name and version.
+    When the tracer_provider is set, it'll retrieve the tracer from it, otherwise
+    it'll fall back to the global tracer provider and use this library's specific semantics.
+    """
+    if not tracer_provider:
+        # Acquire the global tracer provider.
+        tracer_provider = trace.get_tracer_provider()
+
+    return tracer_provider.get_tracer(TRACER_NAME, TRACER_VERSION)
+
+
+@contextmanager
+def trace_call(
+    name, session=None, extra_attributes=None, observability_options=None, metadata=None
+):
+    if session:
+        session._last_use_time = datetime.now()
+
+    if not (HAS_OPENTELEMETRY_INSTALLED and name):
+        # Empty context manager. Users will have to check if the generated value is None or a span
+        yield None
+        return
+
+    tracer_provider = None
+
+    # By default enable_extended_tracing=True because in a bid to minimize
+    # breaking changes and preserve legacy behavior, we are keeping it turned
+    # on by default.
+    enable_extended_tracing = True
+
+    enable_end_to_end_tracing = False
+
+    db_name = ""
+    if session and getattr(session, "_database", None):
+        db_name = session._database.name
+
+    if isinstance(observability_options, dict):  # Avoid false positives with mock.Mock
+        tracer_provider = observability_options.get("tracer_provider", None)
+        enable_extended_tracing = observability_options.get(
+            "enable_extended_tracing", enable_extended_tracing
+        )
+        enable_end_to_end_tracing = observability_options.get(
+            "enable_end_to_end_tracing", enable_end_to_end_tracing
+        )
+        db_name = observability_options.get("db_name", db_name)
+
+    tracer = get_tracer(tracer_provider)
+
+    # Set base attributes that we know for every trace created
+    attributes = {
+        "db.type": "spanner",
+        "db.url": SpannerClient.DEFAULT_ENDPOINT,
+        "db.instance": db_name,
+        "net.host.name": SpannerClient.DEFAULT_ENDPOINT,
+        OTEL_SCOPE_NAME: TRACER_NAME,
+        OTEL_SCOPE_VERSION: TRACER_VERSION,
+        # Standard GCP attributes for OTel, attributes are used for internal purpose and are subjected to change
+        "gcp.client.service": "spanner",
+        "gcp.client.version": TRACER_VERSION,
+        "gcp.client.repo": "googleapis/python-spanner",
+    }
+
+    if extra_attributes:
+        attributes.update(extra_attributes)
+
+    if extended_tracing_globally_disabled:
+        enable_extended_tracing = False
+
+    if not enable_extended_tracing:
+        attributes.pop("db.statement", False)
+
+    if end_to_end_tracing_globally_enabled:
+        enable_end_to_end_tracing = True
+
+    with tracer.start_as_current_span(
+        name, kind=trace.SpanKind.CLIENT, attributes=attributes
+    ) as span:
+        with MetricsCapture():
+            try:
+                if enable_end_to_end_tracing:
+                    _metadata_with_span_context(metadata)
+                yield span
+            except Exception as error:
+                span.set_status(Status(StatusCode.ERROR, str(error)))
+                # OpenTelemetry-Python imposes invoking span.record_exception on __exit__
+                # on any exception. We should file a bug later on with them to only
+                # invoke .record_exception if not already invoked, hence we should not
+                # invoke .record_exception on our own else we shall have 2 exceptions.
+                raise
+            else:
+                # All spans still have set_status available even if for example
+                # NonRecordingSpan doesn't have "_status".
+                absent_span_status = getattr(span, "_status", None) is None
+                if absent_span_status or span._status.status_code == StatusCode.UNSET:
+                    # OpenTelemetry-Python only allows a status change
+                    # if the current code is UNSET or ERROR. At the end
+                    # of the generator's consumption, only set it to OK
+                    # it wasn't previously set otherwise.
+                    # https://github.com/googleapis/python-spanner/issues/1246
+                    span.set_status(Status(StatusCode.OK))
+
+
+def get_current_span():
+    if not HAS_OPENTELEMETRY_INSTALLED:
+        return None
+    return trace.get_current_span()
+
+
+def add_span_event(span, event_name, event_attributes=None):
+    if span:
+        span.add_event(event_name, event_attributes)

google/cloud/spanner_v1/backup.py

@@ -0,0 +1,397 @@
+# Copyright 2020 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.
+
+"""User friendly container for Cloud Spanner Backup."""
+
+import re
+
+from google.cloud.exceptions import NotFound
+
+from google.cloud.spanner_admin_database_v1 import Backup as BackupPB
+from google.cloud.spanner_admin_database_v1 import CreateBackupEncryptionConfig
+from google.cloud.spanner_admin_database_v1 import CreateBackupRequest
+from google.cloud.spanner_admin_database_v1 import CopyBackupEncryptionConfig
+from google.cloud.spanner_admin_database_v1 import CopyBackupRequest
+from google.cloud.spanner_v1._helpers import _metadata_with_prefix
+
+_BACKUP_NAME_RE = re.compile(
+    r"^projects/(?P<project>[^/]+)/"
+    r"instances/(?P<instance_id>[a-z][-a-z0-9]*)/"
+    r"backups/(?P<backup_id>[a-z][a-z0-9_\-]*[a-z0-9])$"
+)
+
+
+class Backup(object):
+    """Representation of a Cloud Spanner Backup.
+
+    We can use a :class`Backup` to:
+
+    * :meth:`create` the backup
+    * :meth:`update` the backup
+    * :meth:`delete` the backup
+
+    :type backup_id: str
+    :param backup_id: The ID of the backup.
+
+    :type instance: :class:`~google.cloud.spanner_v1.instance.Instance`
+    :param instance: The instance that owns the backup.
+
+    :type database: str
+    :param database: (Optional) The URI of the database that the backup is
+                     for. Required if the create method needs to be called.
+
+    :type expire_time: :class:`datetime.datetime`
+    :param expire_time: (Optional) The expire time that will be used to
+                        create the backup. Required if the create method
+                        needs to be called.
+
+    :type version_time: :class:`datetime.datetime`
+    :param version_time: (Optional) The version time that was specified for
+                        the externally consistent copy of the database. If
+                        not present, it is the same as the `create_time` of
+                        the backup.
+
+    :type encryption_config:
+        :class:`~google.cloud.spanner_admin_database_v1.types.CreateBackupEncryptionConfig`
+        or :class:`dict`
+    :param encryption_config:
+        (Optional) Encryption configuration for the backup.
+        If a dict is provided, it must be of the same form as the protobuf
+        message :class:`~google.cloud.spanner_admin_database_v1.types.CreateBackupEncryptionConfig`
+    """
+
+    def __init__(
+        self,
+        backup_id,
+        instance,
+        database="",
+        expire_time=None,
+        version_time=None,
+        encryption_config=None,
+        source_backup=None,
+    ):
+        self.backup_id = backup_id
+        self._instance = instance
+        self._database = database
+        self._source_backup = source_backup
+        self._expire_time = expire_time
+        self._create_time = None
+        self._version_time = version_time
+        self._size_bytes = None
+        self._state = None
+        self._referencing_databases = None
+        self._encryption_info = None
+        self._max_expire_time = None
+        self._referencing_backups = None
+        self._database_dialect = None
+        if type(encryption_config) is dict:
+            if source_backup:
+                self._encryption_config = CopyBackupEncryptionConfig(
+                    **encryption_config
+                )
+            else:
+                self._encryption_config = CreateBackupEncryptionConfig(
+                    **encryption_config
+                )
+        else:
+            self._encryption_config = encryption_config
+
+    @property
+    def name(self):
+        """Backup name used in requests.
+
+        The backup name is of the form
+
+            ``"projects/../instances/../backups/{backup_id}"``
+
+        :rtype: str
+        :returns: The backup name.
+        """
+        return self._instance.name + "/backups/" + self.backup_id
+
+    @property
+    def database(self):
+        """Database name used in requests.
+
+        The database name is of the form
+
+            ``"projects/../instances/../backups/{backup_id}"``
+
+        :rtype: str
+        :returns: The database name.
+        """
+        return self._database
+
+    @property
+    def expire_time(self):
+        """Expire time used in creation requests.
+
+        :rtype: :class:`datetime.datetime`
+        :returns: a datetime object representing the expire time of
+            this backup
+        """
+        return self._expire_time
+
+    @property
+    def create_time(self):
+        """Create time of this backup.
+
+        :rtype: :class:`datetime.datetime`
+        :returns: a datetime object representing the create time of
+            this backup
+        """
+        return self._create_time
+
+    @property
+    def version_time(self):
+        """Version time of this backup.
+
+        :rtype: :class:`datetime.datetime`
+        :returns: a datetime object representing the version time of
+            this backup
+        """
+        return self._version_time
+
+    @property
+    def size_bytes(self):
+        """Size of this backup in bytes.
+
+        :rtype: int
+        :returns: the number size of this backup measured in bytes
+        """
+        return self._size_bytes
+
+    @property
+    def state(self):
+        """State of this backup.
+
+        :rtype: :class:`~google.cloud.spanner_admin_database_v1.types.Backup.State`
+        :returns: an enum describing the state of the backup
+        """
+        return self._state
+
+    @property
+    def referencing_databases(self):
+        """List of databases referencing this backup.
+
+        :rtype: list of strings
+        :returns: a list of database path strings which specify the databases still
+            referencing this backup
+        """
+        return self._referencing_databases
+
+    @property
+    def encryption_info(self):
+        """Encryption info for this backup.
+        :rtype: :class:`~google.cloud.spanner_admin_database_v1.types.EncryptionInfo`
+        :returns: a class representing the encryption info
+        """
+        return self._encryption_info
+
+    @property
+    def max_expire_time(self):
+        """The max allowed expiration time of the backup.
+        :rtype: :class:`datetime.datetime`
+        :returns: a datetime object representing the max expire time of
+            this backup
+        """
+        return self._max_expire_time
+
+    @property
+    def referencing_backups(self):
+        """The names of the destination backups being created by copying this source backup.
+        :rtype: list of strings
+        :returns: a list of backup path strings which specify the backups that are
+            referencing this copy backup
+        """
+        return self._referencing_backups
+
+    def database_dialect(self):
+        """Database Dialect for this backup.
+        :rtype: :class:`~google.cloud.spanner_admin_database_v1.types.DatabaseDialect`
+        :returns: a class representing the dialect of this backup's database
+        """
+        return self._database_dialect
+
+    @classmethod
+    def from_pb(cls, backup_pb, instance):
+        """Create an instance of this class from a protobuf message.
+
+        :type backup_pb: :class:`~google.cloud.spanner_admin_database_v1.types.Backup`
+        :param backup_pb: A backup protobuf object.
+
+        :type instance: :class:`~google.cloud.spanner_v1.instance.Instance`
+        :param instance: The instance that owns the backup.
+
+        :rtype: :class:`Backup`
+        :returns: The backup parsed from the protobuf response.
+        :raises ValueError:
+            if the backup name does not match the expected format or if
+            the parsed project ID does not match the project ID on the
+            instance's client, or if the parsed instance ID does not match
+            the instance's ID.
+        """
+        match = _BACKUP_NAME_RE.match(backup_pb.name)
+        if match is None:
+            raise ValueError(
+                "Backup protobuf name was not in the expected format.", backup_pb.name
+            )
+        if match.group("project") != instance._client.project:
+            raise ValueError(
+                "Project ID on backup does not match the project ID"
+                "on the instance's client"
+            )
+        instance_id = match.group("instance_id")
+        if instance_id != instance.instance_id:
+            raise ValueError(
+                "Instance ID on database does not match the instance ID"
+                "on the instance"
+            )
+        backup_id = match.group("backup_id")
+        return cls(backup_id, instance)
+
+    def create(self):
+        """Create this backup or backup copy within its instance.
+
+        :rtype: :class:`~google.api_core.operation.Operation`
+        :returns: a future used to poll the status of the create request
+        :raises Conflict: if the backup already exists
+        :raises NotFound: if the instance owning the backup does not exist
+        :raises BadRequest: if the database or expire_time values are invalid
+                            or expire_time is not set
+        """
+        if not self._expire_time:
+            raise ValueError("expire_time not set")
+
+        if not self._database and not self._source_backup:
+            raise ValueError("database and source backup both not set")
+
+        if (
+            (
+                self._encryption_config
+                and self._encryption_config.kms_key_name
+                and self._encryption_config.encryption_type
+                != CreateBackupEncryptionConfig.EncryptionType.CUSTOMER_MANAGED_ENCRYPTION
+            )
+            and self._encryption_config
+            and self._encryption_config.kms_key_name
+            and self._encryption_config.encryption_type
+            != CopyBackupEncryptionConfig.EncryptionType.CUSTOMER_MANAGED_ENCRYPTION
+        ):
+            raise ValueError("kms_key_name only used with CUSTOMER_MANAGED_ENCRYPTION")
+
+        api = self._instance._client.database_admin_api
+        metadata = _metadata_with_prefix(self.name)
+
+        if self._source_backup:
+            request = CopyBackupRequest(
+                parent=self._instance.name,
+                backup_id=self.backup_id,
+                source_backup=self._source_backup,
+                expire_time=self._expire_time,
+                encryption_config=self._encryption_config,
+            )
+
+            future = api.copy_backup(
+                request=request,
+                metadata=metadata,
+            )
+            return future
+
+        backup = BackupPB(
+            database=self._database,
+            expire_time=self.expire_time,
+            version_time=self.version_time,
+        )
+
+        request = CreateBackupRequest(
+            parent=self._instance.name,
+            backup_id=self.backup_id,
+            backup=backup,
+            encryption_config=self._encryption_config,
+        )
+
+        future = api.create_backup(
+            request=request,
+            metadata=metadata,
+        )
+        return future
+
+    def exists(self):
+        """Test whether this backup exists.
+
+        :rtype: bool
+        :returns: True if the backup exists, else False.
+        """
+        api = self._instance._client.database_admin_api
+        metadata = _metadata_with_prefix(self.name)
+
+        try:
+            api.get_backup(name=self.name, metadata=metadata)
+        except NotFound:
+            return False
+        return True
+
+    def reload(self):
+        """Reload this backup.
+
+        Refresh the stored backup properties.
+
+        :raises NotFound: if the backup does not exist
+        """
+        api = self._instance._client.database_admin_api
+        metadata = _metadata_with_prefix(self.name)
+        pb = api.get_backup(name=self.name, metadata=metadata)
+        self._database = pb.database
+        self._expire_time = pb.expire_time
+        self._create_time = pb.create_time
+        self._version_time = pb.version_time
+        self._size_bytes = pb.size_bytes
+        self._state = BackupPB.State(pb.state)
+        self._referencing_databases = pb.referencing_databases
+        self._encryption_info = pb.encryption_info
+        self._max_expire_time = pb.max_expire_time
+        self._referencing_backups = pb.referencing_backups
+
+    def update_expire_time(self, new_expire_time):
+        """Update the expire time of this backup.
+
+        :type new_expire_time: :class:`datetime.datetime`
+        :param new_expire_time: the new expire time timestamp
+        """
+        api = self._instance._client.database_admin_api
+        metadata = _metadata_with_prefix(self.name)
+        backup_update = BackupPB(
+            name=self.name,
+            expire_time=new_expire_time,
+        )
+        update_mask = {"paths": ["expire_time"]}
+        api.update_backup(
+            backup=backup_update, update_mask=update_mask, metadata=metadata
+        )
+        self._expire_time = new_expire_time
+
+    def is_ready(self):
+        """Test whether this backup is ready for use.
+
+        :rtype: bool
+        :returns: True if the backup state is READY, else False.
+        """
+        return self.state == BackupPB.State.READY
+
+    def delete(self):
+        """Delete this backup."""
+        api = self._instance._client.database_admin_api
+        metadata = _metadata_with_prefix(self.name)
+        api.delete_backup(name=self.name, metadata=metadata)