Add Usage API (#41)

* usage

* proto

* Update comment - for incomplete field

* nit: comment

* nit2: comment

temporal/api/cloud/cloudservice/v1/request_response.proto

@@ -9,11 +9,14 @@ option java_outer_classname = "RequestResponseProto";
 option ruby_package = "Temporalio::Api::Cloud::CloudService::V1";
 option csharp_namespace = "Temporalio.Api.Cloud.CloudService.V1";
 
+import "google/protobuf/timestamp.proto";
+
 import "temporal/api/cloud/operation/v1/message.proto";
 import "temporal/api/cloud/identity/v1/message.proto";
 import "temporal/api/cloud/namespace/v1/message.proto";
 import "temporal/api/cloud/nexus/v1/message.proto";
 import "temporal/api/cloud/region/v1/message.proto";
+import "temporal/api/cloud/usage/v1/message.proto";
 
 message GetUsersRequest {
     // The requested size of the page to retrieve - optional.
@@ -619,3 +622,33 @@ message DeleteServiceAccountResponse {
     // The async operation.
     temporal.api.cloud.operation.v1.AsyncOperation async_operation = 1;
 }
+
+message GetUsageRequest {
+    // Filter for UTC time >= - optional.
+    // Defaults to: start of the current month.
+    // Must be: within the last 90 days from the current date.
+    // Must be: midnight UTC time.
+    google.protobuf.Timestamp start_time_inclusive = 1;
+
+    // Filter for UTC time < - optional.
+    // Defaults to: start of the next UTC day.
+    // Must be: within the last 90 days from the current date.
+    // Must be: midnight UTC time.
+    google.protobuf.Timestamp end_time_exclusive = 2;
+
+    // The requested size of the page to retrieve - optional.
+    // Each count corresponds to a single object - per day per namespace
+    // Cannot exceed 1000. Defaults to 100.
+    int32 page_size = 3;
+
+    // The page token if this is continuing from another response - optional.
+    string page_token = 4;
+}
+
+message GetUsageResponse {
+    // The list of data based on granularity (per Day for now)
+    // Ordered by: time range in ascending order
+    repeated temporal.api.cloud.usage.v1.Summary summaries = 1;
+    // The next page's token.
+    string next_page_token = 2;
+}

temporal/api/cloud/cloudservice/v1/service.proto

@@ -297,4 +297,12 @@ service CloudService {
             delete: "/cloud/service-accounts/{service_account_id}",
         };
     }
+
+    // WARNING: Pre-Release Feature
+    // Get usage data across namespaces
+    rpc GetUsage(GetUsageRequest) returns (GetUsageResponse) {
+        option (google.api.http) = {
+            get: "/cloud/usage",
+        };
+    }
 }

temporal/api/cloud/usage/v1/message.proto

@@ -0,0 +1,59 @@
+syntax = "proto3";
+
+package temporal.api.cloud.usage.v1;
+
+option go_package = "go.temporal.io/api/cloud/usage/v1;usage";
+option java_package = "io.temporal.api.cloud.usage.v1";
+option java_multiple_files = true;
+option java_outer_classname = "MessageProto";
+option ruby_package = "Temporalio::Api::Cloud::Usage::V1";
+option csharp_namespace = "Temporalio.Api.Cloud.Usage.V1";
+
+import "google/protobuf/timestamp.proto";
+
+message Summary {
+    // Start of UTC day for now (inclusive)
+    google.protobuf.Timestamp start_time = 1;
+    // End of UTC day for now (exclusive)
+    google.protobuf.Timestamp end_time = 2;
+    // Records grouped by namespace
+    repeated RecordGroup record_groups = 3;
+    // True if data for given time window is not fully available yet (e.g. delays)
+    // When true, records for the given time range could still be added/updated in the future (until false) 
+    bool incomplete = 4;
+}
+
+message RecordGroup {
+    // GroupBy keys and their values for this record group. Multiple fields are combined with logical AND.
+    repeated GroupBy group_bys = 1;
+    repeated Record records = 2;
+}
+
+message GroupBy {
+    GroupByKey key = 1;
+    string value = 2;
+}
+
+message Record {
+    RecordType type = 1;
+    RecordUnit unit = 2;
+    double value = 3;
+}
+
+enum RecordType {
+    RECORD_TYPE_UNSPECIFIED = 0;
+    RECORD_TYPE_ACTIONS = 1;
+    RECORD_TYPE_ACTIVE_STORAGE = 2;
+    RECORD_TYPE_RETAINED_STORAGE = 3;
+}
+
+enum RecordUnit {
+    RECORD_UNIT_UNSPECIFIED = 0;
+    RECORD_UNIT_NUMBER = 1;
+    RECORD_UNIT_BYTE_SECONDS = 2;
+}
+
+enum GroupByKey {
+    GROUP_BY_KEY_UNSPECIFIED = 0;
+    GROUP_BY_KEY_NAMESPACE = 1;
+}