/*
 * Copyright (C) 2019 The Android Open Source Project
 *
 * 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 = "proto2";

import "protos/perfetto/trace/track_event/chrome_process_descriptor.proto";
import "protos/perfetto/trace/track_event/chrome_thread_descriptor.proto";
import "protos/perfetto/trace/track_event/process_descriptor.proto";
import "protos/perfetto/trace/track_event/thread_descriptor.proto";
import "protos/perfetto/trace/track_event/counter_descriptor.proto";

package perfetto.protos;

// Defines a track for TrackEvents. Slices and instant events on the same track
// will be nested based on their timestamps, see TrackEvent::Type.
//
// A TrackDescriptor only needs to be emitted by one trace writer / producer and
// is valid for the entirety of the trace. To ensure the descriptor isn't lost
// when the ring buffer wraps, it should be reemitted whenever incremental state
// is cleared.
//
// As a fallback, TrackEvents emitted without an explicit track association will
// be associated with an implicit trace-global track (uuid = 0), see also
// |TrackEvent::track_uuid|. It is possible but not necessary to emit a
// TrackDescriptor for this implicit track.
//
// Next id: 10.
message TrackDescriptor {
  // Unique ID that identifies this track. This ID is global to the whole trace.
  // Producers should ensure that it is unlikely to clash with IDs emitted by
  // other producers. A value of 0 denotes the implicit trace-global track.
  //
  // For example, legacy TRACE_EVENT macros may use a hash involving the async
  // event id + id_scope, pid, and/or tid to compute this ID.
  optional uint64 uuid = 1;

  // A parent track reference can be used to describe relationships between
  // tracks. For example, to define an asynchronous track which is scoped to a
  // specific process, specify the uuid for that process's process track here.
  // Similarly, to associate a COUNTER_THREAD_TIME_NS counter track with a
  // thread, specify the uuid for that thread's thread track here.
  optional uint64 parent_uuid = 5;

  // Name of the track. Optional - if unspecified, it may be derived from the
  // process/thread name (process/thread tracks), the first event's name (async
  // tracks), or counter name (counter tracks).
  optional string name = 2;

  // Associate the track with a process, making it the process-global track.
  // There should only be one such track per process (usually for instant
  // events; trace processor uses this fact to detect pid reuse). If you need
  // more (e.g. for asynchronous events), create child tracks using parent_uuid.
  //
  // Trace processor will merge events on a process track with slice-type events
  // from other sources (e.g. ftrace) for the same process into a single
  // timeline view.
  optional ProcessDescriptor process = 3;
  optional ChromeProcessDescriptor chrome_process = 6;

  // Associate the track with a thread, indicating that the track's events
  // describe synchronous code execution on the thread. There should only be one
  // such track per thread (trace processor uses this fact to detect tid reuse).
  //
  // Trace processor will merge events on a thread track with slice-type events
  // from other sources (e.g. ftrace) for the same thread into a single timeline
  // view.
  optional ThreadDescriptor thread = 4;
  optional ChromeThreadDescriptor chrome_thread = 7;

  // Descriptor for a counter track. If set, the track will only support
  // TYPE_COUNTER TrackEvents (and values provided via TrackEvent's
  // |extra_counter_values|).
  optional CounterDescriptor counter = 8;

  // If true, forces Trace Processor to use separate tracks for track events
  // and system events for the same thread.
  // Track events timestamps in Chrome have microsecond resolution, while
  // system events use nanoseconds. It results in broken event nesting when
  // track events and system events share a track.
  optional bool disallow_merging_with_system_tracks = 9;
}