protos/perfetto/trace/trace_packet.proto

/*
 * Copyright (C) 2017 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";
option optimize_for = LITE_RUNTIME;

import "perfetto/common/trace_stats.proto";
import "perfetto/config/trace_config.proto";
import "perfetto/trace/android/android_log.proto";
import "perfetto/trace/android/packages_list.proto";
import "perfetto/trace/chrome/chrome_trace_event.proto";
import "perfetto/trace/clock_snapshot.proto";
import "perfetto/trace/filesystem/inode_file_map.proto";
import "perfetto/trace/ftrace/ftrace_event_bundle.proto";
import "perfetto/trace/ftrace/ftrace_stats.proto";
import "perfetto/trace/interned_data/interned_data.proto";
import "perfetto/trace/power/battery_counters.proto";
import "perfetto/trace/power/power_rails.proto";
import "perfetto/trace/profiling/profile_packet.proto";
import "perfetto/trace/ps/process_stats.proto";
import "perfetto/trace/ps/process_tree.proto";
import "perfetto/trace/sys_stats/sys_stats.proto";
import "perfetto/trace/system_info.proto";
import "perfetto/trace/track_event/process_descriptor.proto";
import "perfetto/trace/track_event/thread_descriptor.proto";
import "perfetto/trace/track_event/track_event.proto";
import "perfetto/trace/trigger.proto";
import "perfetto/trace/test_event.proto";

package perfetto.protos;

// The root object emitted by Perfetto. A perfetto trace is just a stream of
// TracePacket(s).
//
// Next reserved id: 13 (up to 15).
// Next id: 47.
message TracePacket {
  // TODO(primiano): in future we should add a timestamp_clock_domain field to
  // allow mixing timestamps from different clock domains.
  optional uint64 timestamp = 8;  // Timestamp [ns].

  oneof data {
    FtraceEventBundle ftrace_events = 1;
    ProcessTree process_tree = 2;
    ProcessStats process_stats = 9;
    InodeFileMap inode_file_map = 4;
    ChromeEventBundle chrome_events = 5;
    ClockSnapshot clock_snapshot = 6;
    SysStats sys_stats = 7;
    TrackEvent track_event = 11;

    // IDs up to 15 are reserved. They take only one byte to encode their
    // preamble so should be used for freqeuent events.

    TraceConfig trace_config = 33;
    FtraceStats ftrace_stats = 34;
    TraceStats trace_stats = 35;
    ProfilePacket profile_packet = 37;
    BatteryCounters battery = 38;
    PowerRails power_rails = 40;
    AndroidLogPacket android_log = 39;
    SystemInfo system_info = 45;
    Trigger trigger = 46;
    PackagesList packages_list = 47;

    // Only used by TrackEvent.
    ProcessDescriptor process_descriptor = 43;
    ThreadDescriptor thread_descriptor = 44;

    // This field is emitted at periodic intervals (~10s) and
    // contains always the binary representation of the UUID
    // {82477a76-b28d-42ba-81dc-33326d57a079}. This is used to be able to
    // efficiently partition long traces without having to fully parse them.
    bytes synchronization_marker = 36;

    // This field is only used for testing.
    TestEvent for_testing = 268435455;  // 2^28 - 1, max field id for protos.
  }

  // Trusted user id of the producer which generated this packet. Keep in sync
  // with TrustedPacket.trusted_uid.
  //
  // TODO(eseckler): Emit this field in a PacketSequenceDescriptor message
  // instead.
  oneof optional_trusted_uid { int32 trusted_uid = 3; };

  // Service-assigned identifier of the packet sequence this packet belongs to.
  // Uniquely identifies a producer + writer pair within the tracing session. A
  // value of zero denotes an invalid ID. Keep in sync with
  // TrustedPacket.trusted_packet_sequence_id.
  oneof optional_trusted_packet_sequence_id {
    uint32 trusted_packet_sequence_id = 10;
  }

  // Incrementally emitted interned data, valid only on the packet's sequence
  // (packets with the same |trusted_packet_sequence_id|). The writer will
  // usually emit new interned data in the same TracePacket that first refers to
  // it (since the last reset of interning state). It may also be emitted
  // proactively in advance of referring to them in later packets.
  optional InternedData interned_data = 12;

  // Set to true by the writer to indicate that it will re-emit any incremental
  // data for the packet's sequence before referring to it again. This includes
  // interned data as well as periodically emitted data like
  // Process/ThreadDescriptors. This flag only affects the current packet
  // sequence (see |trusted_packet_sequence_id|).
  //
  // When set to true, this TracePacket and subsequent TracePackets on the same
  // sequence will not refer to any incremental data emitted before this
  // TracePacket. For example, previously emitted interned data will be
  // re-emitted if it is referred to again.
  //
  // When the reader detects packet loss (|previous_packet_dropped|), it needs
  // to skip packets in the sequence until the next one with this flag set, to
  // ensure intact incremental data.
  optional bool incremental_state_cleared = 41;

  // Flag set by the service if, for the current packet sequence (see
  // |trusted_packet_sequence_id|), either:
  // * this is the first packet, or
  // * one or multiple packets were dropped since the last packet that the
  //   consumer read from the sequence. This can happen if chunks in the trace
  //   buffer are overridden before the consumer could read them when the trace
  //   is configured in ring buffer mode.
  //
  // When packet loss occurs, incrementally emitted data (including interned
  // data) on the sequence should be considered invalid up until the next packet
  // with |incremental_state_cleared| set.
  optional bool previous_packet_dropped = 42;
}