feat: client side metrics data model

google/cloud/bigtable/data/_async/client.py

@@ -79,6 +79,8 @@
 from google.cloud.bigtable.data.row_filters import CellsRowLimitFilter
 from google.cloud.bigtable.data.row_filters import RowFilterChain
 
+from google.cloud.bigtable.data._metrics import BigtableClientSideMetricsController
+
 
 if TYPE_CHECKING:
     from google.cloud.bigtable.data._helpers import RowKeySamples
@@ -529,6 +531,13 @@ def __init__(
         )
         self.default_mutate_rows_attempt_timeout = default_mutate_rows_attempt_timeout
 
+        self._metrics = BigtableClientSideMetricsController(
+            project_id=self.client.project,
+            instance_id=instance_id,
+            table_id=table_id,
+            app_profile_id=app_profile_id,
+        )
+
         self.default_read_rows_retryable_errors = (
             default_read_rows_retryable_errors or ()
         )

google/cloud/bigtable/data/_helpers.py

@@ -23,6 +23,7 @@
 from google.cloud.bigtable.data.read_rows_query import ReadRowsQuery
 
 from google.api_core import exceptions as core_exceptions
+from google.api_core.retry import exponential_sleep_generator
 from google.api_core.retry import RetryFailureReason
 from google.cloud.bigtable.data.exceptions import RetryExceptionGroup
 
@@ -97,6 +98,34 @@ def _attempt_timeout_generator(
         yield max(0, min(per_request_timeout, deadline - time.monotonic()))
 
 
+class BackoffGenerator:
+    """
+    Generator class for exponential backoff sleep times.
+
+    This implementation builds on top of api_core.retries.exponential_sleep_generator,
+    adding the ability to retrieve previous values using get_attempt_backoff(idx).
+    This is used by the Metrics class to track the sleep times used for each attempt.
+    """
+
+    def __init__(self, initial=0.01, multiplier=2, maximum=60):
+        self.history = []
+        self.subgenerator = exponential_sleep_generator(initial, multiplier, maximum)
+
+    def __iter__(self):
+        return self
+
+    def __next__(self) -> float:
+        next_backoff = next(self.subgenerator)
+        self.history.append(next_backoff)
+        return next_backoff
+
+    def get_attempt_backoff(self, attempt_idx) -> float:
+        """
+        returns the backoff time for a specific attempt index, starting at 0.
+        """
+        return self.history[attempt_idx]
+
+
 def _retry_exception_factory(
     exc_list: list[Exception],
     reason: RetryFailureReason,

google/cloud/bigtable/data/_metrics/__init__.py

@@ -0,0 +1,25 @@
+# Copyright 2023 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.
+from google.cloud.bigtable.data._metrics.metrics_controller import (
+    BigtableClientSideMetricsController,
+)
+
+from google.cloud.bigtable.data._metrics.data_model import OperationType
+from google.cloud.bigtable.data._metrics.data_model import ActiveOperationMetric
+
+__all__ = (
+    "BigtableClientSideMetricsController",
+    "OperationType",
+    "ActiveOperationMetric",
+)