1/* 2 * Copyright (C) 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17syntax = "proto2"; 18 19package perfetto.protos; 20 21// Defines properties of a counter track, e.g. for built-in counters (thread 22// time, instruction count, ..) or user-specified counters (e.g. memory usage of 23// a specific app component). 24// 25// Counter tracks only support TYPE_COUNTER track events, which specify new 26// values for the counter. For counters that require per-slice values, counter 27// values can instead be provided in a more efficient encoding via TrackEvent's 28// |extra_counter_track_uuids| and |extra_counter_values| fields. However, 29// slice-type events cannot be emitted onto a counter track. 30// 31// Values for counters that are only emitted on a single packet sequence can 32// optionally be delta-encoded, see |is_incremental|. 33// 34// Next id: 7. 35message CounterDescriptor { 36 // Built-in counters, usually with special meaning in the client library, 37 // trace processor, legacy JSON format, or UI. Trace processor will infer a 38 // track name from the enum value if none is provided in TrackDescriptor. 39 enum BuiltinCounterType { 40 COUNTER_UNSPECIFIED = 0; 41 42 // Thread-scoped counters. The thread's track should be specified via 43 // |parent_uuid| in the TrackDescriptor for such a counter. 44 45 // implies UNIT_TIME_NS. 46 COUNTER_THREAD_TIME_NS = 1; 47 48 // implies UNIT_COUNT. 49 COUNTER_THREAD_INSTRUCTION_COUNT = 2; 50 } 51 52 // Type of the values for the counters - to supply lower granularity units, 53 // see also |unit_multiplier|. 54 enum Unit { 55 UNIT_UNSPECIFIED = 0; 56 UNIT_TIME_NS = 1; 57 UNIT_COUNT = 2; 58 UNIT_SIZE_BYTES = 3; 59 // TODO(eseckler): Support more units as necessary. 60 } 61 62 // For built-in counters (e.g. thread time). Custom user-specified counters 63 // (e.g. those emitted by TRACE_COUNTER macros of the client library) 64 // shouldn't set this, and instead provide a counter name via TrackDescriptor. 65 optional BuiltinCounterType type = 1; 66 67 // Names of categories of the counter (usually for user-specified counters). 68 // In the client library, categories are a way to turn groups of individual 69 // counters (or events) on or off. 70 repeated string categories = 2; 71 72 // Type of the counter's values. Built-in counters imply a value for this 73 // field. 74 optional Unit unit = 3; 75 76 // In order to use a unit not defined as a part of |Unit|, a free-form unit 77 // name can be used instead. 78 optional string unit_name = 6; 79 80 // Multiplication factor of this counter's values, e.g. to supply 81 // COUNTER_THREAD_TIME_NS timestamps in microseconds instead. 82 optional int64 unit_multiplier = 4; 83 84 // Whether values for this counter are provided as delta values. Only 85 // supported for counters that are emitted on a single packet-sequence (e.g. 86 // thread time). Counter values in subsequent packets on the current packet 87 // sequence will be interpreted as delta values from the sequence's most 88 // recent value for the counter. When incremental state is cleared, the 89 // counter value is considered to be reset to 0. Thus, the first value after 90 // incremental state is cleared is effectively an absolute value. 91 optional bool is_incremental = 5; 92 93 // TODO(eseckler): Support arguments describing the counter (?). 94 // repeated DebugAnnotation debug_annotations; 95} 96