src/pb/event.proto

// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";

package cobalt;

import "src/pb/observation.proto";

// An Event is the unit of data logged in Cobalt.
//
// Events are associated with a specific Metric. There is a different Event
// type for each Metric type. Events are also tagged with a day index indicating
// the day on which the event occurred.
message Event {
  // An Event has one of the following types. These types correspond to
  // the various Metric types defined in config/metric_definitions.proto.
  oneof type {
    // These event types are for Cobalt 1.0.
    // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
    EventOccurredEvent event_occurred_event = 1;
    EventCountEvent event_count_event = 2;
    ElapsedTimeEvent elapsed_time_event = 3;
    FrameRateEvent frame_rate_event = 4;
    MemoryUsageEvent memory_usage_event = 5;
    IntHistogramEvent int_histogram_event = 6;
    // The remaining event types are for Cobalt 1.1.
    OccurrenceEvent occurrence_event = 8;
    IntegerEvent integer_event = 9;
    IntegerHistogramEvent integer_histogram_event = 10;
    StringEvent string_event = 11;
    CustomEvent custom_event = 999;
  }

  // The three-part unique numerical identifier of the Metric that this
  // Event is associated with.
  uint32 customer_id = 1000;
  uint32 project_id = 1001;
  uint32 metric_id = 1002;

  // The index of the day on which this Event occurred.
  uint32 day_index = 1003;
  // The hour id for this Event.
  uint32 hour_id = 1005;

  reserved 7;
}

// Records that an event has occurred.
message EventOccurredEvent {
  // The event code for the event that occurred.
  uint32 event_code = 1;
}

// Records that an event occurred a number of times.
message EventCountEvent {
  // The event codes for the event that occurred. There must be one event code
  // given for each dimension specified in the metric definition.
  repeated uint32 event_code = 1;
  // The associated system component
  string component = 2;
  // Time over which the count was taken, in microseconds.
  int64 period_duration_micros = 3;
  // The number of times the event occurred.
  int64 count = 4;
}

// Records that an event occurred a number of times.
message ElapsedTimeEvent {
  // The event codes for the event that occurred. There must be one event code
  // given for each dimension specified in the metric definition.
  repeated uint32 event_code = 1;
  // The associated system component
  string component = 2;
  // The elapsed time in microseconds.
  int64 elapsed_micros = 3;
}

// Records a frame-rate.
message FrameRateEvent {
  // The event codes for the event that occurred. There must be one event code
  // given for each dimension specified in the metric definition.
  repeated uint32 event_code = 1;
  // The associated system component
  string component = 2;
  // round(frames-per-second * 1000)
  int64 frames_per_1000_seconds = 3;
}

// Records a memory-usage.
message MemoryUsageEvent {
  // The event codes for the event that occurred. There must be one event code
  // given for each dimension specified in the metric definition.
  repeated uint32 event_code = 1;
  // The associated system component
  string component = 2;
  // Memory usage in bytes.
  int64 bytes = 3;
}

// Records a histogram over a set of integer buckets. The semantics of the
// Metric must be specified in comments near the Metric definition. The
// numerical values of the buckets is specified in the |int_buckets|
// field of the MetricDefinition.
message IntHistogramEvent {
  // The event codes for the event that occurred. There must be one event code
  // given for each dimension specified in the metric definition.
  repeated uint32 event_code = 1;
  // The associated system component
  string component = 2;

  // The set of bucket indices and their corresponding counts.
  repeated HistogramBucket buckets = 3;
}

// Records that an event occurred a number of times.
message OccurrenceEvent {
  // The event codes for the event that occurred. There must be one event code
  // given for each dimension specified in the metric definition.
  repeated uint32 event_code = 1;
  // The number of times the event occurred.
  uint64 count = 2;
}

// Records that an event occurred a number of times.
message IntegerEvent {
  // The event codes for the event that occurred. There must be one event code
  // given for each dimension specified in the metric definition.
  repeated uint32 event_code = 1;
  // The elapsed time in microseconds.
  int64 value = 2;
}

// Records a frame-rate.
message StringEvent {
  // The event codes for the event that occurred. There must be one event code
  // given for each dimension specified in the metric definition.
  repeated uint32 event_code = 1;
  // The associated system component
  string string_value = 2;
}

// Records a histogram over a set of integer buckets. The semantics of the
// Metric must be specified in comments near the Metric definition. The
// numerical values of the buckets is specified in the |int_buckets|
// field of the MetricDefinition.
message IntegerHistogramEvent {
  // The event codes for the event that occurred. There must be one event code
  // given for each dimension specified in the metric definition.
  repeated uint32 event_code = 1;
  // The set of bucket indices and their corresponding counts.
  repeated HistogramBucket buckets = 3;
}

// Allows users of Cobalt to define custom Metrics with custom semantics.
// Each Custom event is either
//
// 1. a collection of CustomEventValues, each of which has a dimension name and a value associated
// with the event.
// 2. a serialized protocol buffer.
message CustomEvent {
  // The keys are the names of the metric dimensions to which each ValuePart
  // is associated.
  map<string, CustomDimensionValue> values = 1;

  // The serialized protocol buffer.
  bytes serialized_proto = 2;
}