feat: Add ListHotTablets API method and protobufs

protos/google/bigtable/admin/v2/bigtable_instance_admin.proto

@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -274,6 +274,15 @@ service BigtableInstanceAdmin {
     };
     option (google.api.method_signature) = "resource,permissions";
   }
+
+  // Lists hot tablets in a cluster, within the time range provided. Hot
+  // tablets are ordered based on CPU usage.
+  rpc ListHotTablets(ListHotTabletsRequest) returns (ListHotTabletsResponse) {
+    option (google.api.http) = {
+      get: "/v2/{parent=projects/*/instances/*/clusters/*}/hotTablets"
+    };
+    option (google.api.method_signature) = "parent";
+  }
 }
 
 // Request message for BigtableInstanceAdmin.CreateInstance.
@@ -634,3 +643,56 @@ message DeleteAppProfileRequest {
 message UpdateAppProfileMetadata {
 
 }
+
+// Request message for BigtableInstanceAdmin.ListHotTablets.
+message ListHotTabletsRequest {
+  // Required. The cluster name to list hot tablets.
+  // Value is in the following form:
+  // `projects/{project}/instances/{instance}/clusters/{cluster}`.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "bigtableadmin.googleapis.com/Cluster"
+    }
+  ];
+
+  // The start time to list hot tablets. The hot tablets in the response will
+  // have start times between the requested start time and end time. Start time
+  // defaults to Now if it is unset, and end time defaults to Now - 24 hours if
+  // it is unset. The start time should be less than the end time, and the
+  // maximum allowed time range between start time and end time is 48 hours.
+  // Start time and end time should have values between Now and Now - 14 days.
+  google.protobuf.Timestamp start_time = 2;
+
+  // The end time to list hot tablets.
+  google.protobuf.Timestamp end_time = 3;
+
+  // Maximum number of results per page.
+  //
+  // A page_size that is empty or zero lets the server choose the number of
+  // items to return. A page_size which is strictly positive will return at most
+  // that many items. A negative page_size will cause an error.
+  //
+  // Following the first request, subsequent paginated calls do not need a
+  // page_size field. If a page_size is set in subsequent calls, it must match
+  // the page_size given in the first request.
+  int32 page_size = 4;
+
+  // The value of `next_page_token` returned by a previous call.
+  string page_token = 5;
+}
+
+// Response message for BigtableInstanceAdmin.ListHotTablets.
+message ListHotTabletsResponse {
+  // List of hot tablets in the tables of the requested cluster that fall
+  // within the requested time range. Hot tablets are ordered by node cpu usage
+  // percent. If there are multiple hot tablets that correspond to the same
+  // tablet within a 15-minute interval, only the hot tablet with the highest
+  // node cpu usage will be included in the response.
+  repeated HotTablet hot_tablets = 1;
+
+  // Set if not all hot tablets could be returned in a single response.
+  // Pass this value to `page_token` in another request to get the next
+  // page of results.
+  string next_page_token = 2;
+}

protos/google/bigtable/admin/v2/instance.proto

@@ -1,4 +1,4 @@
-// Copyright 2021 Google LLC
+// Copyright 2022 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -291,3 +291,43 @@ message AppProfile {
     SingleClusterRouting single_cluster_routing = 6;
   }
 }
+
+// A tablet is a defined by a start and end key and is explained in
+// https://cloud.google.com/bigtable/docs/overview#architecture and
+// https://cloud.google.com/bigtable/docs/performance#optimization.
+// A Hot tablet is a tablet that exhibits high average cpu usage during the time
+// interval from start time to end time.
+message HotTablet {
+  option (google.api.resource) = {
+    type: "bigtableadmin.googleapis.com/HotTablet"
+    pattern: "projects/{project}/instances/{instance}/clusters/{cluster}/hotTablets/{hot_tablet}"
+  };
+
+  // The unique name of the hot tablet. Values are of the form
+  // `projects/{project}/instances/{instance}/clusters/{cluster}/hotTablets/[a-zA-Z0-9_-]*`.
+  string name = 1;
+
+  // Name of the table that contains the tablet. Values are of the form
+  // `projects/{project}/instances/{instance}/tables/[_a-zA-Z0-9][-_.a-zA-Z0-9]*`.
+  string table_name = 2 [(google.api.resource_reference) = {
+                           type: "bigtableadmin.googleapis.com/Table"
+                         }];
+
+  // Output only. The start time of the hot tablet.
+  google.protobuf.Timestamp start_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The end time of the hot tablet.
+  google.protobuf.Timestamp end_time = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Tablet Start Key (inclusive).
+  string start_key = 5;
+
+  // Tablet End Key (inclusive).
+  string end_key = 6;
+
+  // Output only. The average CPU usage spent by a node on this tablet over the start_time to
+  // end_time time range. The percentage is the amount of CPU used by the node
+  // to serve the tablet, from 0% (tablet was not interacted with) to 100% (the
+  // node spent all cycles serving the hot tablet).
+  float node_cpu_usage_percent = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
+}