1/* 2 * Copyright (C) 2023 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 21import "protos/perfetto/config/trace_config.proto"; 22 23// Rule that triggers scenario events (e.g. start, stop). 24message TriggerRule { 25 // Rule unique name. 26 optional string name = 1; 27 28 // A value between 0 and 1 which encodes the probability this rule is 29 // triggered. 30 optional float trigger_chance = 2; 31 32 // Additional delay *after* the trigger below. This is mostly useful 33 // to trace beyond a triggered event in upload rules. Other triggers 34 // can still be serviced during this period. 35 optional uint64 delay_ms = 3; 36 37 // Delay *before* which the rule is activated. Trigger events during this 38 // period are ignored by this rule. This is mostly useful to trace for a 39 // minimum duration before watching trigger events. 40 optional uint64 activation_delay_ms = 8; 41 42 // Triggers when a value within the specified bounds [min_value, 43 // max_value] is emitted into a Chrome histogram. 44 message HistogramTrigger { 45 optional string histogram_name = 1; 46 optional int64 min_value = 2; 47 optional int64 max_value = 3; 48 } 49 // Triggers on a repeating interval, every `period_ms` milliseconds if 50 // `randomized` is false, and at random time within a `period_ms` window 51 // otherwise, thus ticking with an average period of `period_ms` milliseconds. 52 message RepeatingInterval { 53 optional uint64 period_ms = 1; 54 optional bool randomized = 2; 55 } 56 oneof trigger { 57 // Triggers when the associated named trigger is manually emitted in Chrome 58 // client code. 59 string manual_trigger_name = 4; 60 HistogramTrigger histogram = 5; 61 RepeatingInterval repeating_interval = 6; 62 } 63} 64 65// Chrome field tracing defines a set of scenarios, each associated with 66// specific tracing configs, and nested scenarios that can cover interesting 67// tracing regions within a parent scenario. Both scenarios and nested scenarios 68// are enrolled by clients based on a set of start and stop rules that 69// delimitate a meaningful tracing interval, usually covering a user journey or 70// a guardian metric (e.g. FirstContentfulPaint). Collected traces may be saved 71// and uploaded based on upload rules. Scenario enrollment and trace uploads may 72// also be affected by client side scenario and upload limits. 73 74// Start rules from all scenarios in the config are observed by default (when no 75// scenario is active). Once enrolled in a specific scenario, other scenarios 76// are ignored until the active one is exited. Start rules for nested scenarios 77// are only observed once the parent scenario becomes active. 78 79message NestedScenarioConfig { 80 // Nested scenario name, unique within the parent scenario. 81 optional string scenario_name = 1; 82 83 // When triggered, this scenario becomes active. This activates `upload_rules` 84 // and `stop_rules`. 85 repeated TriggerRule start_rules = 2; 86 // When triggered, exits the scenario. This reverts back to the parent 87 // scenario. All nested scenarios within the parent scenario will be observed 88 // again. 89 repeated TriggerRule stop_rules = 3; 90 // When triggered, exits both this scenario and the parent scenario, stops the 91 // tracing session, and attempts to upload the trace. All scenarios are 92 // observed again. 93 repeated TriggerRule upload_rules = 4; 94} 95 96message ScenarioConfig { 97 // Scenario name, unique within the whole field tracing config. 98 optional string scenario_name = 1; 99 100 // When triggered, this scenario becomes active. Initializes a tracing session 101 // and starts recording data sources. This activates `upload_rules` and 102 // `stop_rules`. 103 repeated TriggerRule start_rules = 2; 104 // When triggered, exits the scenario. This stops the tracing session and 105 // discards the trace. All scenarios will be observed again. 106 repeated TriggerRule stop_rules = 3; 107 // When triggered, exits the scenario, stops the tracing session, and attempts 108 // to upload the trace. All scenarios will be observed again. 109 repeated TriggerRule upload_rules = 4; 110 // When triggered, this scenario becomes active. Initializes a tracing 111 // session, without recording data sources, and waits for a `start_rules` or 112 // to enter a `nested_scenarios`, which would start recording. This also 113 // activates `stop_rules`. 114 repeated TriggerRule setup_rules = 5; 115 116 optional TraceConfig trace_config = 6; 117 118 repeated NestedScenarioConfig nested_scenarios = 7; 119 120 // When set to true, this scenario initiates a tracing session using the 121 // system backend instead of the default in-browser custom backend. 122 optional bool use_system_backend = 8; 123} 124 125message ChromeFieldTracingConfig { 126 repeated ScenarioConfig scenarios = 1; 127} 128 129message TracingTriggerRulesConfig { 130 repeated TriggerRule rules = 1; 131}