1// Copyright 2019 The Chromium Authors 2// Use of this source code is governed by a BSD-style license that can be 3// found in the LICENSE file. 4 5syntax = "proto2"; 6 7option optimize_for = LITE_RUNTIME; 8option java_package = "org.chromium.components.metrics"; 9 10package metrics; 11 12// One structured metrics event, containing several hashed and unhashed metrics 13// related to a single event type. Structured metrics have hashing keys based on 14// the project. A project refers to a use-case of the framework (ie bluetooth, 15// event sequence). 16// 17// Structured metrics is currently only used for the CrOS platform, so some of 18// the fields are CrOS-specific (ie device_project_id, user_project_id). If 19// structured metrics were to expand to other platforms, these fields will need 20// to be revisited. 21// 22// Next tag: 9 23message StructuredEventProto { 24 // A per-client, per-profile, per-project ID that is used only for structured 25 // metrics. For projects recorded from Chrome OS's platform2 repository, this 26 // ID is device-wide, not per-profile. The ID is rotated at least every 90 27 // days. 28 // 29 // For events of type SEQUENCE, the ID will be rotated every 120 days. 30 optional fixed64 profile_event_id = 1; 31 32 // A per-profile, per-project ID used only for events of type SEQUENCE. A 33 // device may have multiple profiles and multiple projects (ie cros-events). 34 // 35 // This ID is generated by applying HMAC on a locally-generated GUID (which is 36 // never sent) with a per-profile, per-project key. The first 8 bytes of the 37 // resulting string will be emitted. 38 // 39 // For events recorded when a user is not logged in or for events recorded 40 // outside of Chrome, this field should be empty. 41 // 42 // Since the per-profile, per-project keys are rotated every 120 days, this 43 // means that the |user_project_id| will also change every N days. For more 44 // details on how keys are rotated, refer to go/structured-metrics. 45 optional fixed64 user_project_id = 7; 46 47 // A device-wide, per-project ID used only for events of type SEQUENCE. This 48 // ID is rotated every 120 days. 49 // 50 // This ID is generated by hashing a locally-generated GUID (which is never 51 // sent) with a per-device, per-project key. The first 8 bytes of thee 52 // resulting string will be emitted. 53 // 54 // Since the per-device, per-project keys are rotated every N (default 90) 55 // days, this means that the |device_project_id| will also change every N 56 // days. For more details on how keys are rotated, refer to 57 // go/structured-metrics. 58 // 59 // Note that an event may have both a |device_project_id| and 60 // |user_project_id|. 61 optional fixed64 device_project_id = 8; 62 63 // The first 8 bytes of the MD5 hash of the event's name as a string. Each 64 // name is defined in src/tools/metrics/structured/structured.xml, and this 65 // will be the hash of one of those. 66 optional fixed64 event_name_hash = 2; 67 68 // All metric values for this event. Each metric has two properties defined in 69 // structured.xml that determine what is recorded. 70 // 71 // 1. Metric name. This is a string, and the first 8 bytes of its MD5 hash is 72 // recorded as name_hash. 73 // 74 // 2. Kind. Each metric can store four kinds of values. 75 // 76 // - int64. The client supplies an int64 value for the metric, and that 77 // value is recorded as-is in value_int64. 78 // 79 // - string. The client supplies a string value for the metric, which is 80 // recorded as-is in value_string. This is sometimes referred to as a 81 // "raw string" to differentiate from the following. 82 // 83 // - hashed-string. The client supplies an arbitrary string for the metric. 84 // The string itself is not recorded, instead, value_hmac records the 85 // first 8 bytes of: 86 // 87 // HMAC_SHA256(concat(string, metric_name), event_key) 88 // 89 // - double. The client supplies a double value for the metric, which is 90 // recorded as-is in value_double. 91 // 92 // The event_key is a per-profile, per-client, per-project secret 32-byte 93 // key used only for signing hashed values for this event. Keys should 94 // never leave the device, and are rotated at least every 90 days. 95 message Metric { 96 optional fixed64 name_hash = 1; 97 oneof value { 98 fixed64 value_hmac = 2; 99 int64 value_int64 = 3; 100 string value_string = 4; 101 double value_double = 5; 102 } 103 } 104 repeated Metric metrics = 3; 105 106 // Type of this event, which determines which log source the event is saved 107 // into. An event should have type RAW_STRING if and only if the event may 108 // contain raw string metrics, ie. strings that have not been HMAC'd. The 109 // UNKNOWN value is considered an error and should never be sent. 110 // 111 // An event should be marked as a SEQUENCE if it contains temporal data. 112 enum EventType { 113 UNKNOWN = 0; 114 REGULAR = 1; 115 RAW_STRING = 2; 116 SEQUENCE = 3; 117 } 118 optional EventType event_type = 4; 119 120 // The project name hash is the first 8 bytes of the MD5 hash of the project 121 // name that is defined in src/tools/metrics/structured/structured.xml. 122 optional fixed64 project_name_hash = 5; 123 124 // Metadata associated with events for which relative order in which the 125 // events occur are of interest. 126 // 127 // Next tag: 4 128 message EventSequenceMetadata { 129 // GUIDs generated on the client to uniquely identify an event. These event 130 // IDs will be used to establish relationships between events on the client. 131 optional fixed64 event_unique_id = 1; 132 133 // Time elapsed since boot time. Note that system uptime includes duration a 134 // device has spent asleep. System uptime resets when a machine reboots. 135 // Granularity is in milliseconds. 136 optional int64 system_uptime = 2; 137 138 // Monotonically increasing number incremented every time a system reset is 139 // detected. This value will be reset to 0 in the event of a powerwash. 140 optional int64 reset_counter = 3; 141 } 142 143 // Metadata associated with event type SEQUENCE. This field will be stripped 144 // if the event is not of type SEQUENCE. 145 optional EventSequenceMetadata event_sequence_metadata = 6; 146} 147 148// The top-level proto for structured metrics. One StructuredDataProto is 149// uploaded per UMA upload containing structured metrics. Contains all 150// structured events for that upload, and any other metadata. 151message StructuredDataProto { 152 repeated StructuredEventProto events = 1; 153} 154