blob: aab6920f307d3b6fdeebd3fdd76531d05e630836 [file] [log] [blame]
// Copyright 2017 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.
module memory_instrumentation.mojom;
import "mojo/public/mojom/base/big_string.mojom";
import "mojo/public/mojom/base/process_id.mojom";
import "mojo/public/mojom/base/time.mojom";
// Common structs:
enum DumpType {
enum LevelOfDetail {
enum ProcessType {
enum MemoryMapOption {
// Do not fetch any information about mapped regions in the virtual address
// space.
// Only fetch information on code modules, e.g. Chrome Binary, system
// libraries.
// Fetch information for every single mapped region.
// These structs are internal only (only for the communication between
// the service and the ClientProcess library).
// See corresponding types in //base/trace_event for comments.
struct RequestArgs {
uint64 dump_guid;
DumpType dump_type;
LevelOfDetail level_of_detail;
struct RawAllocatorDumpEdge {
uint64 source_id;
uint64 target_id;
int32 importance;
bool overridable;
union RawAllocatorDumpEntryValue {
uint64 value_uint64;
string value_string;
struct RawAllocatorDumpEntry {
string name;
string units;
RawAllocatorDumpEntryValue value;
struct RawAllocatorDump {
uint64 id;
string absolute_name;
bool weak;
LevelOfDetail level_of_detail;
array<RawAllocatorDumpEntry> entries;
struct RawProcessMemoryDump {
LevelOfDetail level_of_detail;
array<RawAllocatorDumpEdge> allocator_dump_edges;
array<RawAllocatorDump> allocator_dumps;
struct VmRegion {
const uint32 kProtectionFlagsRead = 4;
const uint32 kProtectionFlagsWrite = 2;
const uint32 kProtectionFlagsExec = 1;
const uint32 kProtectionFlagsMayshare = 128;
uint64 start_address;
uint64 size_in_bytes;
uint64 module_timestamp;
// Unique module debug identifier to retrieve debug information.
string module_debugid;
string module_debug_path;
uint32 protection_flags;
string mapped_file;
// private_dirty_resident + private_clean_resident + shared_dirty_resident +
// shared_clean_resident = resident set size.
uint64 byte_stats_private_dirty_resident;
uint64 byte_stats_private_clean_resident;
uint64 byte_stats_shared_dirty_resident;
uint64 byte_stats_shared_clean_resident;
uint64 byte_stats_swapped;
// For multiprocess accounting.
uint64 byte_stats_proportional_resident;
// Platform-specific data that will be used to compute the
// PrivateMemoryFootprint.
struct PlatformPrivateFootprint {
uint64 phys_footprint_bytes = 0;
// macOS 10.12+
uint64 internal_bytes = 0;
// macOS [all versions]
uint64 compressed_bytes = 0;
uint64 rss_anon_bytes = 0;
// Linux, Android, ChromeOS
uint64 vm_swap_bytes = 0;
// On Windows,
uint64 private_bytes = 0;
// On iOS,
// TBD:
struct RawOSMemDump {
uint32 resident_set_kb = 0;
PlatformPrivateFootprint platform_private_footprint;
array<VmRegion> memory_maps;
// Each bit corresponds to a page. The bit is set if the page
// is mapped and resident in memory.
array<uint8> native_library_pages_bitmap;
// These structs are public:
struct OSMemDump {
uint32 resident_set_kb = 0;
// This is roughly private, anonymous, non-discardable, resident or swapped
// memory in kilobytes. For more details, see
uint32 private_footprint_kb = 0;
// This is roughly non-private, anonymous, non-discardable, resident memory
// in kilobytes. For more details, see
uint32 shared_footprint_kb = 0;
// This is private swapped memory in kilobytes reported on Linux and Android
// only.
uint32 private_footprint_swap_kb = 0;
// This struct contains information about a particular allocator dump
// (e.g. cc/resource_memory).
struct AllocatorMemDump {
// The entries for the allocator which are of scalar types (i.e. not strings).
// Examples include: effective_size, size, object_count.
map<string, uint64> numeric_entries;
// This struct is used for the public-facing API
// Coordinator::RequestGlobalMemoryDump().
struct ProcessMemoryDump {
ProcessType process_type;
OSMemDump os_dump;
// The chrome allocator dumps specified by the input args.
// (See GlobalRequestArgs.allocator_dump_names).
map<string, AllocatorMemDump> chrome_allocator_dumps;
// |pid| is necessary to correlate a ProcessMemoryDump with the URLs for the
// process, which is obtained from the ResourceCoordinator service. In a
// future world where both ResourceCoordinator and MemoryInstrumentation are
// less in flux, they will probably be merged into a single service, and this
// parameter can be removed.
mojo_base.mojom.ProcessId pid;
// Shows which services the given process is running, to help separate out
// the statistics for a given service. Clients should look through the entire
// list since there may be other entities used internally listed, too.
array<string> service_names;
// Metrics aggregated across all processes.
struct AggregatedMetrics {
uint32 native_library_resident_kb = 0;
// This struct is returned by the public-facing API
// Coordinator::RequestGlobalMemoryDump().
struct GlobalMemoryDump {
// This time stamp precedes any of the data captured in |process_dumps|. Since
// dumps are queued, and since at most one dump is captured at a time, the
// start time of a global dump may lag the request time substantially.
mojo_base.mojom.TimeTicks start_time;
array<ProcessMemoryDump> process_dumps;
AggregatedMetrics aggregated_metrics;
// This is the interface implemented by the per-process client library. This
// allows a process to contribute to memory-infra dumps. There should be at
// most one instance of this per hosting process.
interface ClientProcess {
// When |success| == true the dump is appended in the process-local trace
// buffer of the target process and an ACK. A summary of the dump is also
// returned in case of success.
RequestChromeMemoryDump(RequestArgs args) =>
(bool success, uint64 dump_id, RawProcessMemoryDump? raw_process_memory_dump);
// Requests an OSMemDump for each pid in |pids|.
// The Memory-infra service deals with two kinds of information:
// 1) Chrome's view of its own memory use (recorded as
// |chrome_allocator_dumps|)
// 2) The OS's view of Chrome's memory use (recorded as OSMemDumps)
// Both of these are collected per process. On most platforms each process
// can make the system calls to collect its own OSMemDump however on some
// platforms *cough* Linux *cough* due to sandboxing only the browser
// process can collect OSMemDumps. This API allows for these two cases.
// On most platforms we send this message to each ClientProcess with
// with one pid - kNullProcessId - meaning return just your own OSMemDump.
// On Linux we call this once on the browser process ClientProcess passing
// the pids for all processes.
// See
RequestOSMemoryDump(MemoryMapOption option, array<mojo_base.mojom.ProcessId> pids) =>
(bool success, map<mojo_base.mojom.ProcessId, RawOSMemDump> dumps);
struct HeapProfileResult {
mojo_base.mojom.ProcessId pid;
mojo_base.mojom.BigString json;
// HeapProfilers expose a single interface to memory_instrumentation, allowing
// the latter to query for heap dumps when necessary.
// This interface is NOT implemented in resource_coordinator but by the
// profiling service in chrome/profiler. The profiling service registers itself
// with the Coordinator (see RegisterHeapProfiler) and is invoked when a memory
// dump is requested (via Coordinator::RequestGlobalMemoryDump).
interface HeapProfiler {
// Dumps the memory log of all profiled processes into BigString's.
// The contents of each BigString is a JSON string compatible with
// TRACE_EVENT* macros. Processes that fail to dump will be omitted from
// |result|. When |strip_path_from_mapped_files| is true, only the base name
// of mapped files is emitted. This prevents usernames from sneaking into the
// trace.
// |strip_path_from_mapped_files| should only be true for traces that will be
// uploaded to the crash servers - this strips potential PII, but prevents
// symbolization of local builds.
DumpProcessesForTracing(bool strip_path_from_mapped_files) =>
(array<HeapProfileResult> results);
// Implemented by resource_coordinator to provide additional information needed
// by the HeapProfiler.
interface HeapProfilerHelper {
// Broadcasts a RequestOSMemoryDump-only request for all registered client
// processes and retrieves only their memory maps.
GetVmRegionsForHeapProfiler(array<mojo_base.mojom.ProcessId> pids) =>
(map<mojo_base.mojom.ProcessId, array<VmRegion>> vm_regions);
// The memory-infra service implements this interface. There is one instance for
// the whole system. The coordinator maintains a list of registered client
// processes and polls them whenever a global dump is required.
interface Coordinator {
// Registers a client process.
RegisterClientProcess(ClientProcess client_process, ProcessType process_type);
// Broadcasts a dump request to all registered client processes and returns a
// global dump which includes allocator dumps specified in |allocator_dump_names|.
// For example, given an allocator dump name such as "malloc" or "cc/resource_memory",
// this method returns all information corresponding to this name including numeric
// entries which contain fields such as "size" and "effective_size".
RequestGlobalMemoryDump(DumpType dump_type,
LevelOfDetail level_of_detail,
array<string> allocator_dump_names) =>
(bool success, GlobalMemoryDump? global_memory_dump);
// Sends a dump request to the client process given by the specified pid and
// returns a summarized dump back or null if there was a failure.
RequestGlobalMemoryDumpForPid(mojo_base.mojom.ProcessId pid,
array<string> allocator_dump_names) =>
(bool success, GlobalMemoryDump? global_memory_dump);
// Requesting a null pid is the same as requesting all pids.
// The returned dump only contains OS metrics. |chrome_allocator_dumps| will
// be empty.
RequestPrivateMemoryFootprint(mojo_base.mojom.ProcessId pid) =>
(bool success, GlobalMemoryDump? global_memory_dump);
// Broadcasts a dump request to all registered client processes and injects the
// dump in the trace buffer (if tracing is enabled).
RequestGlobalMemoryDumpAndAppendToTrace(DumpType dump_type,
LevelOfDetail level_of_detail) =>
(bool success, uint64 dump_id);
// When a heap profiler is registered, heap dumps will be added to the trace
// any time RequestGlobalMemoryDumpAndAppendToTrace is called.
// This is cleaner than having the memory_instrumentation service talk
// directly to the HeapProfiler, since that will spawn the HeapProfiler in a
// new process if it isn't already running.
RegisterHeapProfiler(HeapProfiler heap_profiler);