/*
 * Copyright (C) 2018 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";

package perfetto.protos;

// Configuration for go/heapprofd.
// Next id: 28
message HeapprofdConfig {
  message ContinuousDumpConfig {
    // ms to wait before first dump.
    optional uint32 dump_phase_ms = 5;
    // ms to wait between following dumps.
    optional uint32 dump_interval_ms = 6;
  }

  // Sampling rate for all heaps not specified via heap_sampling_intervals.
  //
  // These are:
  // * All heaps if heap_sampling_intervals is empty.
  // * Those profiled due to all_heaps and not named in heaps if
  //   heap_sampling_intervals is not empty.
  // * The implicit libc.malloc heap if heaps is empty.
  //
  // Set to 1 for perfect accuracy.
  // Otherwise, sample every sample_interval_bytes on average.
  //
  // See
  // https://perfetto.dev/docs/data-sources/native-heap-profiler#sampling-interval
  // for more details.
  //
  // BUGS
  // Before Android 12, setting this to 0 would crash the target process.
  //
  // N.B. This must be explicitly set to a non-zero value for all heaps (with
  // this field or with heap_sampling_intervals), otherwise the producer will
  // not start.
  optional uint64 sampling_interval_bytes = 1;

  // If less than the given numbers of bytes are left free in the shared
  // memory buffer, increase sampling interval by a factor of two.
  // Adaptive sampling is disabled when set to 0.
  optional uint64 adaptive_sampling_shmem_threshold = 24;
  // Stop doubling the sampling_interval once the sampling interval has reached
  // this value.
  optional uint64 adaptive_sampling_max_sampling_interval_bytes = 25;

  // E.g. surfaceflinger, com.android.phone
  // This input is normalized in the following way: if it contains slashes,
  // everything up to the last slash is discarded. If it contains "@",
  // everything after the first @ is discared.
  // E.g. /system/bin/surfaceflinger@1.0 normalizes to surfaceflinger.
  // This transformation is also applied to the processes' command lines when
  // matching.
  repeated string process_cmdline = 2;

  // For watermark based triggering or local debugging.
  repeated uint64 pid = 4;

  // Only profile target if it was installed by one of the packages given.
  // Special values are:
  // * @system: installed on the system partition
  // * @product: installed on the product partition
  // * @null: sideloaded
  // Supported on Android 12+.
  repeated string target_installed_by = 26;

  // Which heaps to sample, e.g. "libc.malloc". If left empty, only samples
  // "malloc".
  //
  // Introduced in Android 12.
  repeated string heaps = 20;

  // Which heaps not to sample, e.g. "libc.malloc". This is useful when used in
  // combination with all_heaps;
  //
  // Introduced in Android 12.
  repeated string exclude_heaps = 27;

  optional bool stream_allocations = 23;

  // If given, needs to be the same length as heaps and gives the sampling
  // interval for the respective entry in heaps.
  //
  // Otherwise, sampling_interval_bytes is used.
  //
  // It is recommended to set sampling_interval_bytes to a reasonable default
  // value when using this, as a value of 0 for sampling_interval_bytes will
  // crash the target process before Android 12.
  //
  // Introduced in Android 12.
  //
  // All values must be non-zero or the producer will not start.
  repeated uint64 heap_sampling_intervals = 22;

  // Sample all heaps registered by target process. Introduced in Android 12.
  optional bool all_heaps = 21;

  // Profile all processes eligible for profiling on the system.
  // See
  // https://perfetto.dev/docs/data-sources/native-heap-profiler#heapprofd-targets
  // for which processes are eligible.
  //
  // On unmodified userdebug builds, this will lead to system crashes. Zygote
  // will crash when trying to launch a new process as it will have an
  // unexpected open socket to heapprofd.
  //
  // heapprofd will likely be overloaded by the amount of data for low
  // sampling intervals.
  optional bool all = 5;

  // Do not profile processes whose anon RSS + swap < given value.
  // Introduced in Android 11.
  optional uint32 min_anonymous_memory_kb = 15;

  // Stop profile if heapprofd memory usage goes beyond the given value.
  // Introduced in Android 11.
  optional uint32 max_heapprofd_memory_kb = 16;

  // Stop profile if heapprofd CPU time since start of this data-source
  // goes beyond given value.
  // Introduced in Android 11.
  optional uint64 max_heapprofd_cpu_secs = 17;

  // Do not emit function names for mappings starting with this prefix.
  // E.g. /system to not emit symbols for any system libraries.
  repeated string skip_symbol_prefix = 7;

  // Dump at a predefined interval.
  optional ContinuousDumpConfig continuous_dump_config = 6;

  // Size of the shared memory buffer between the profiled processes and
  // heapprofd. Defaults to 8 MiB. If larger than 500 MiB, truncated to 500
  // MiB.
  //
  // Needs to be:
  // * at least 8192,
  // * a power of two,
  // * a multiple of 4096.
  optional uint64 shmem_size_bytes = 8;

  // When the shmem buffer is full, block the client instead of ending the
  // trace. Use with caution as this will significantly slow down the target
  // process.
  optional bool block_client = 9;

  // If set, stop the trace session after blocking the client for this
  // timeout. Needs to be larger than 100 us, otherwise no retries are done.
  // Introduced in Android 11.
  optional uint32 block_client_timeout_us = 14;

  // Do not profile processes from startup, only match already running
  // processes.
  //
  // Can not be set at the same time as no_running.
  // Introduced in Android 11.
  optional bool no_startup = 10;

  // Do not profile running processes. Only match processes on startup.
  //
  // Can not be set at the same time as no_startup.
  // Introduced in Android 11.
  optional bool no_running = 11;

  // deprecated idle_allocations.
  reserved 12;

  // Cause heapprofd to emit a single dump at the end, showing the memory usage
  // at the point in time when the sampled heap usage of the process was at its
  // maximum. This causes ProfilePacket.HeapSample.self_max to be set, and
  // self_allocated and self_freed to not be set.
  // Introduced in Android 11.
  optional bool dump_at_max = 13;

  // FEATURE FLAGS. THERE BE DRAGONS.

  // Escape hatch if the session is being torn down because of a forked child
  // that shares memory space, but is not correctly identified as a vforked
  // child.
  // Introduced in Android 11.
  optional bool disable_fork_teardown = 18;

  // We try to automatically detect when a target applicatation vforks but then
  // does a memory allocation (or free). This auto-detection can be disabled
  // with this.
  // Introduced in Android 11.
  optional bool disable_vfork_detection = 19;
}