1// Copyright 2022 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.cloud.recommender.v1;
18
19import "google/api/resource.proto";
20import "google/protobuf/duration.proto";
21import "google/protobuf/struct.proto";
22import "google/protobuf/timestamp.proto";
23
24option csharp_namespace = "Google.Cloud.Recommender.V1";
25option go_package = "cloud.google.com/go/recommender/apiv1/recommenderpb;recommenderpb";
26option java_multiple_files = true;
27option java_outer_classname = "InsightProto";
28option java_package = "com.google.cloud.recommender.v1";
29option objc_class_prefix = "CREC";
30option (google.api.resource_definition) = {
31  type: "recommender.googleapis.com/InsightType"
32  pattern: "projects/{project}/locations/{location}/insightTypes/{insight_type}"
33  pattern: "billingAccounts/{billing_account}/locations/{location}/insightTypes/{insight_type}"
34  pattern: "folders/{folder}/locations/{location}/insightTypes/{insight_type}"
35  pattern: "organizations/{organization}/locations/{location}/insightTypes/{insight_type}"
36};
37
38// An insight along with the information used to derive the insight. The insight
39// may have associated recomendations as well.
40message Insight {
41  option (google.api.resource) = {
42    type: "recommender.googleapis.com/Insight"
43    pattern: "projects/{project}/locations/{location}/insightTypes/{insight_type}/insights/{insight}"
44    pattern: "billingAccounts/{billing_account}/locations/{location}/insightTypes/{insight_type}/insights/{insight}"
45    pattern: "folders/{folder}/locations/{location}/insightTypes/{insight_type}/insights/{insight}"
46    pattern: "organizations/{organization}/locations/{location}/insightTypes/{insight_type}/insights/{insight}"
47  };
48
49  // Insight category.
50  enum Category {
51    // Unspecified category.
52    CATEGORY_UNSPECIFIED = 0;
53
54    // The insight is related to cost.
55    COST = 1;
56
57    // The insight is related to security.
58    SECURITY = 2;
59
60    // The insight is related to performance.
61    PERFORMANCE = 3;
62
63    // This insight is related to manageability.
64    MANAGEABILITY = 4;
65  }
66
67  // Insight severity levels.
68  enum Severity {
69    // Insight has unspecified severity.
70    SEVERITY_UNSPECIFIED = 0;
71
72    // Insight has low severity.
73    LOW = 1;
74
75    // Insight has medium severity.
76    MEDIUM = 2;
77
78    // Insight has high severity.
79    HIGH = 3;
80
81    // Insight has critical severity.
82    CRITICAL = 4;
83  }
84
85  // Reference to an associated recommendation.
86  message RecommendationReference {
87    // Recommendation resource name, e.g.
88    // projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/recommendations/[RECOMMENDATION_ID]
89    string recommendation = 1;
90  }
91
92  // Name of the insight.
93  string name = 1;
94
95  // Free-form human readable summary in English. The maximum length is 500
96  // characters.
97  string description = 2;
98
99  // Fully qualified resource names that this insight is targeting.
100  repeated string target_resources = 9;
101
102  // Insight subtype. Insight content schema will be stable for a given subtype.
103  string insight_subtype = 10;
104
105  // A struct of custom fields to explain the insight.
106  // Example: "grantedPermissionsCount": "1000"
107  google.protobuf.Struct content = 3;
108
109  // Timestamp of the latest data used to generate the insight.
110  google.protobuf.Timestamp last_refresh_time = 4;
111
112  // Observation period that led to the insight. The source data used to
113  // generate the insight ends at last_refresh_time and begins at
114  // (last_refresh_time - observation_period).
115  google.protobuf.Duration observation_period = 5;
116
117  // Information state and metadata.
118  InsightStateInfo state_info = 6;
119
120  // Category being targeted by the insight.
121  Category category = 7;
122
123  // Insight's severity.
124  Severity severity = 15;
125
126  // Fingerprint of the Insight. Provides optimistic locking when updating
127  // states.
128  string etag = 11;
129
130  // Recommendations derived from this insight.
131  repeated RecommendationReference associated_recommendations = 8;
132}
133
134// Information related to insight state.
135message InsightStateInfo {
136  // Represents insight state.
137  enum State {
138    // Unspecified state.
139    STATE_UNSPECIFIED = 0;
140
141    // Insight is active. Content for ACTIVE insights can be updated by Google.
142    // ACTIVE insights can be marked DISMISSED OR ACCEPTED.
143    ACTIVE = 1;
144
145    // Some action has been taken based on this insight. Insights become
146    // accepted when a recommendation derived from the insight has been marked
147    // CLAIMED, SUCCEEDED, or FAILED. ACTIVE insights can also be marked
148    // ACCEPTED explicitly. Content for ACCEPTED insights is immutable. ACCEPTED
149    // insights can only be marked ACCEPTED (which may update state metadata).
150    ACCEPTED = 2;
151
152    // Insight is dismissed. Content for DISMISSED insights can be updated by
153    // Google. DISMISSED insights can be marked as ACTIVE.
154    DISMISSED = 3;
155  }
156
157  // Insight state.
158  State state = 1;
159
160  // A map of metadata for the state, provided by user or automations systems.
161  map<string, string> state_metadata = 2;
162}
163