1// Copyright 2023 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.monitoring.dashboard.v1; 18 19import "google/api/field_behavior.proto"; 20import "google/monitoring/dashboard/v1/metrics.proto"; 21import "google/protobuf/duration.proto"; 22import "google/protobuf/empty.proto"; 23 24option csharp_namespace = "Google.Cloud.Monitoring.Dashboard.V1"; 25option go_package = "cloud.google.com/go/monitoring/dashboard/apiv1/dashboardpb;dashboardpb"; 26option java_multiple_files = true; 27option java_outer_classname = "ScorecardProto"; 28option java_package = "com.google.monitoring.dashboard.v1"; 29option php_namespace = "Google\\Cloud\\Monitoring\\Dashboard\\V1"; 30option ruby_package = "Google::Cloud::Monitoring::Dashboard::V1"; 31 32// A widget showing the latest value of a metric, and how this value relates to 33// one or more thresholds. 34message Scorecard { 35 // A gauge chart shows where the current value sits within a pre-defined 36 // range. The upper and lower bounds should define the possible range of 37 // values for the scorecard's query (inclusive). 38 message GaugeView { 39 // The lower bound for this gauge chart. The value of the chart should 40 // always be greater than or equal to this. 41 double lower_bound = 1; 42 43 // The upper bound for this gauge chart. The value of the chart should 44 // always be less than or equal to this. 45 double upper_bound = 2; 46 } 47 48 // A sparkChart is a small chart suitable for inclusion in a table-cell or 49 // inline in text. This message contains the configuration for a sparkChart 50 // to show up on a Scorecard, showing recent trends of the scorecard's 51 // timeseries. 52 message SparkChartView { 53 // Required. The type of sparkchart to show in this chartView. 54 SparkChartType spark_chart_type = 1 55 [(google.api.field_behavior) = REQUIRED]; 56 57 // The lower bound on data point frequency in the chart implemented by 58 // specifying the minimum alignment period to use in a time series query. 59 // For example, if the data is published once every 10 minutes it would not 60 // make sense to fetch and align data at one minute intervals. This field is 61 // optional and exists only as a hint. 62 google.protobuf.Duration min_alignment_period = 2; 63 } 64 65 // Required. Fields for querying time series data from the 66 // Stackdriver metrics API. 67 TimeSeriesQuery time_series_query = 1 68 [(google.api.field_behavior) = REQUIRED]; 69 70 // Defines the optional additional chart shown on the scorecard. If 71 // neither is included - then a default scorecard is shown. 72 oneof data_view { 73 // Will cause the scorecard to show a gauge chart. 74 GaugeView gauge_view = 4; 75 76 // Will cause the scorecard to show a spark chart. 77 SparkChartView spark_chart_view = 5; 78 79 // Will cause the `Scorecard` to show only the value, with no indicator to 80 // its value relative to its thresholds. 81 google.protobuf.Empty blank_view = 7; 82 } 83 84 // The thresholds used to determine the state of the scorecard given the 85 // time series' current value. For an actual value x, the scorecard is in a 86 // danger state if x is less than or equal to a danger threshold that triggers 87 // below, or greater than or equal to a danger threshold that triggers above. 88 // Similarly, if x is above/below a warning threshold that triggers 89 // above/below, then the scorecard is in a warning state - unless x also puts 90 // it in a danger state. (Danger trumps warning.) 91 // 92 // As an example, consider a scorecard with the following four thresholds: 93 // 94 // ``` 95 // { 96 // value: 90, 97 // category: 'DANGER', 98 // trigger: 'ABOVE', 99 // }, 100 // { 101 // value: 70, 102 // category: 'WARNING', 103 // trigger: 'ABOVE', 104 // }, 105 // { 106 // value: 10, 107 // category: 'DANGER', 108 // trigger: 'BELOW', 109 // }, 110 // { 111 // value: 20, 112 // category: 'WARNING', 113 // trigger: 'BELOW', 114 // } 115 // ``` 116 // 117 // Then: values less than or equal to 10 would put the scorecard in a DANGER 118 // state, values greater than 10 but less than or equal to 20 a WARNING state, 119 // values strictly between 20 and 70 an OK state, values greater than or equal 120 // to 70 but less than 90 a WARNING state, and values greater than or equal to 121 // 90 a DANGER state. 122 repeated Threshold thresholds = 6; 123} 124