// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto2";

option optimize_for = LITE_RUNTIME;

option java_outer_classname = "CallStackProfileProtos";
option java_package = "org.chromium.components.metrics";

package metrics;

import "execution_context.proto";

// Call stack sample data for a given profiling session.
// Next tag: 11
message CallStackProfile {
  // Uniquely identifies a module.
  message ModuleIdentifier {
    // A hash that uniquely identifies a particular program version with high
    // probability. This is parsed from headers of the loaded module.
    // For binaries generated by GNU tools:
    //   Contents of the .note.gnu.build-id field.
    // On Windows:
    //   GUID + AGE in the debug image headers of a module.
    optional string build_id = 1;

    // MD5Sum Prefix of the module name. This is the same hashing scheme as used
    // to hash UMA histogram names.
    optional fixed64 name_md5_prefix = 2;
  }

  // Describes a location within executable code.
  message Location {
    // Instruction pointer subtracted by module base.
    optional uint64 address = 1;

    // Index to the module identifier in |module_ids| of CallStackProfile.
    optional int32 module_id_index = 2;
  }

  // The sampled call stack.
  message Stack {
    // The frames in the callstack. The frame[0] entry represents the call on
    // the top of the stack.
    repeated Location frame = 1;
  }

  // An item of metadata associated with either the entire profile or a single
  // sample.
  message MetadataItem {
    // Index of the hash of the metadata name.
    optional int32 name_hash_index = 1;

    // Value for the item. An absent value indicates the metadata has become
    // unset since the previous StackSample.
    optional sint64 value = 2;
  }

  // Backtrace of locations of async execution requests (e.g. task postings, IPC
  // message sending, requests over mojo) that led to the current task
  // execution. Note that these are saved in a fixed length buffer on the client
  // which as of 2018/08/14 includes only the most recent four entries.
  message AsyncBacktrace {
    // The locations saved in the backtrace, with the most recent in
    // location[0]. Empty if the work was not tied to an async execution request
    // -- for example, handling a mouse event.
    repeated Location location = 1;
  }

  // Deprecated version of a sample consisting of one or more callstacks with
  // the same stack frames and instruction pointers. Deprecated as of
  // 2018/08/14.
  message Sample {
    // The callstack. Sample.frame[0] represents the call on the top of the
    // stack.
    repeated Location frame = 1;

    // Number of times this stack signature occurs.
    optional int64 count = 2;

    // This repeating field indicates the current phase of the system such as
    // whether it is in startup, general operation, or shutdown. The first
    // Sample of a CallStackProfile will list all phases that have been reached;
    // later samples will list only the new phases that occurred since the
    // previous one.
    repeated ProcessPhase process_phase = 3;
  }

  // A sampled stack, along with associated metadata.
  message StackSample {
    // Index into the profile's repeated |stack| field for the stack
    // corresponding to this sample.
    optional int32 stack_index = 1;

    // Sample time relative to the first sample.
    optional int32 sample_time_offset_ms = 2;

    // True if this sample is executing the same item of work (task, event) as
    // the last sample.
    optional bool continued_work = 3;

    // Index of the backtrace in the profile of posted task locations that led
    // to this task execution.
    optional int32 async_backtrace_index = 4;

    // Metadata items associated with the sample. To minimize memory usage,
    // metadata items are specified only when their values change from the
    // previous sample. Items are not guaranteed to be in a particular order.
    repeated MetadataItem metadata = 5;

    // Weight of the sample. When omitted the sample is presumed to have
    // a weight of 1.
    // Not currently used for CPU profiles.
    // For heap profiles it represents the total number of bytes associated with
    // the StackSample record.
    optional int64 weight = 6;

    // Number of events associated with the sample. When omitted the default
    // value of 1 should be used.
    // Not currently used for CPU profiles.
    // For heap profiles it represents the number of allocations associated with
    // the StackSample record. The following relation holds:
    //   allocation_size * count == weight.
    optional int64 count = 7 [default = 1];
  }

  // The previous sample encoding. Deprecated 2018/08/04 in favor of
  // stack_sample.
  repeated Sample DEPRECATED_sample = 1 [deprecated = true];

  // List of module ids found in this sample.
  repeated ModuleIdentifier module_id = 2;

  // Metadata name hashes used in this profile. Recorded global to the profile
  // to minimize per-sample memory usage.
  repeated fixed64 metadata_name_hash = 5;

  // Metadata global to the profile.
  repeated MetadataItem profile_metadata = 6;

  // The distinct async backtraces for the samples.
  repeated AsyncBacktrace async_backtrace = 7;

  // The distinct stacks for the samples.
  repeated Stack stack = 8;

  // The stack samples collected for this profile.
  repeated StackSample stack_sample = 9;

  // Time of the first sample relative to Chrome start. This value may be
  // imprecise or wrong for Windows clients without high-resolution
  // TimeTicks. TODO(wittman): Clarify the actual properties of this value for
  // clients without high-resolution TimeTicks once we understand what they are.
  optional int64 profile_start_time_offset_ms = 10;

  // Duration of this profile.
  optional int32 profile_duration_ms = 3;

  // Time between samples.
  optional int32 sampling_period_ms = 4;
}