config/metrics.proto

// Copyright 2016 The Fuchsia Authors
//
// 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.
syntax = "proto3";

package cobalt;

option go_package = "config";

// A |Metric| is composed of one or more |MetricParts|. A |MetricPart| has a
// name which is specified as the key in the |parts| field of |Metric|, a
// description and a data type which specifies the type of a |ValuePart| that
// should be encoded for this MetricPart.
message MetricPart {
  enum DataType {
    // Values for this MetricPart are human-readable strings. Cobalt may
    // display the strings in generated reports. A |ValuePart| for this
    // MetricPart must have its |string_value| set.
    STRING = 0;

    // Values for this MetricPart are integers. A |ValuePart| encoded for this
    // MetricPart must have its |int_value| set.
    INT = 1;

    // Values for this MetricPart are uninterpreted sequences of bytes. Cobalt
    // will not try to interpret or display these values. A |ValuePart| encoded
    // for this MetricPart must have its |blob_value| set.
    BLOB = 2;
  }

  // A human-readable description of this MetricPart. This should include
  // a specification of the "semantic type" of this part. For example the
  // description might include the phrase "This is an eTLD+1."
  string description = 1;

  // The data-type for this MetricPart.
  DataType data_type = 2;
}

// A Metric represents a real-world value to be observed and reported by Cobalt.
// For example "Fuchsia Usage Hour-of-the-day" might be a metric that measures
// Fuchsia system usage as a function of the hour of the day.
// Each Observation from the Encoder is for a particular metric.
// Each Observation for the metric "Fuchsia Usage Hour-of-the-day" would
// report the hour of the day for a paticular usage of Fuchsia.
// A Metric has one or more named parts and each Observation sent by the Encoder
// must contain ObservationParts corresponding to these Metric parts.
// For example the Metric described above might have only one part named
// "hour" and so each Observation for this metric should have a single
// ObservationPart named "hour". On the other hand the Metric "Fuchsia Usage
// City-and-Rating" might have two parts called "City" and "Rating".
message Metric {
  // These three numbers form this Metric's unique ID in the Cobalt Config
  // DB.
  uint32 customer_id = 1;
  uint32 project_id = 2;
  uint32 id = 3;

  string name = 4;
  string description = 5;

  // The keys are the names of the part.
  map<string, MetricPart> parts = 6;

  // A TimeZonePolicy specifies how the day_index of an Observation should
  // be computed based on the actual time of encoding.
  enum TimeZonePolicy {
    // There is no default. Either LOCAL or UTC must be specified.
    UNSET = 0;

    // Use the local date at encoding time to compute the day_index.
    LOCAL = 1;

    // Use the date in UTC at encoding time to compute the day_index.
    UTC = 2;
  }

  // Which TimeZonePolicy should Encoders use when encoding Observations for
  // this metric?
  TimeZonePolicy time_zone_policy = 7;
}

// Constains the list of all Metrics that are registered in the
// Cobalt system. An instance of RegisteredMetrics is deserialized
// from a text file.
message RegisteredMetrics {
  repeated Metric element = 1;
}