1// This proto is used for analysis of TensorFlow runtime memory profile.
2syntax = "proto3";
3
4package tensorflow.profiler;
5
6// The memory activity that causes change of memory state.
7enum MemoryActivity {
8  UNKNOWN_ACTIVITY = 0;
9  // Memory allocation in heap.
10  ALLOCATION = 1;
11  // Memory deallocation in heap.
12  DEALLOCATION = 2;
13  // Memory reservation for stack.
14  RESERVATION = 3;
15  // Expansion of existing memory allocation.
16  EXPANSION = 4;
17}
18
19// The aggregated memory stats including heap, stack, free memory and
20// fragmentation at a specific time.
21message MemoryAggregationStats {
22  // Memory usage by stack reservation, in bytes.
23  int64 stack_reserved_bytes = 1;
24  // Memory usage by heap allocation, in bytes.
25  int64 heap_allocated_bytes = 2;
26  // Free memory available for allocation or reservation, in bytes.
27  int64 free_memory_bytes = 3;
28  // Fragmentation value within [0, 1].
29  double fragmentation = 4;
30  // The peak memory usage over the entire program (lifetime of memory
31  // allocator). It monotonically increases with upper limit as memory capacity.
32  int64 peak_bytes_in_use = 5;
33}
34
35// The metadata associated with each memory allocation/deallocation. It can
36// also be interpreted as the metadata for the delta of memory state.
37// Next ID: 10
38message MemoryActivityMetadata {
39  // The activity associated with the MemoryProfileSnapshot.
40  MemoryActivity memory_activity = 1;
41  // The requested memory size in bytes from the caller of memory allocation.
42  // Should be a positive number.
43  int64 requested_bytes = 2;
44  // The allocated (block/chunk) size for the memory allocation.
45  // Should be a positive number.
46  int64 allocation_bytes = 3;
47  // Starting address of the allocated memory chunk/block.
48  uint64 address = 4;
49  // TensorFlow Op name for the memory activity.
50  string tf_op_name = 5;
51  // Step Id at which the memory activity occurred.
52  int64 step_id = 6;
53  // Tensor memory region type including "output", "temp", "persist", and
54  // "dynamic".
55  string region_type = 7;
56  // From enum DataType defined in tensorflow/core/framework/types.proto.
57  string data_type = 8;
58  // Tensor shape printed in string, e.g. "[3, 3, 512, 512]".
59  string tensor_shape = 9;
60}
61
62// Profile snapshot of the TensorFlow memory at runtime, including
63// MemoryAggregationStats (memory usage breakdown etc.), and
64// MemoryActivityMetadata (allocation or deallocation, TF Op name etc.).
65message MemoryProfileSnapshot {
66  // Memory activity timestamp.
67  int64 time_offset_ps = 1;
68  // The memory aggregation stats at the snapshot time.
69  MemoryAggregationStats aggregation_stats = 2;
70  // The metadata for the memory activity at the snapshot time.
71  MemoryActivityMetadata activity_metadata = 3;
72}
73
74// The summary of memory profile within the profiling window duration.
75message MemoryProfileSummary {
76  // The peak memory usage over the entire program (lifetime of memory
77  // allocator).
78  int64 peak_bytes_usage_lifetime = 1;
79  // The peak memory usage stats within the profiling window.
80  MemoryAggregationStats peak_stats = 2;
81  // The timestamp for peak memory usage within the profiling window.
82  int64 peak_stats_time_ps = 3;
83  // The memory capacity of the allocator.
84  int64 memory_capacity = 4;
85}
86
87// The active memory allocations at the peak memory usage.
88message ActiveAllocation {
89  // The index of a snapshot in the time-sorted list, used to fetch the
90  // MemoryActivityMetadata at front end from the memory_profile_snapshots list.
91  int64 snapshot_index = 1;
92  // The index of MemoryActivityMetadata in the special_allocations list.
93  int64 special_index = 2;
94  // Number of occurrences for identical memory allocations.
95  int64 num_occurrences = 3;
96}
97
98// Memory profile snapshots per memory allocator.
99message PerAllocatorMemoryProfile {
100  // A list of MemoryProfileSnapshots sorted by time_offset_ps.
101  repeated MemoryProfileSnapshot memory_profile_snapshots = 1;
102  // The summary of memory profile (e.g. the peak memory usage).
103  MemoryProfileSummary profile_summary = 2;
104  // The rows in the table of active allocations at peak memory usage within
105  // profiling window.
106  repeated ActiveAllocation active_allocations = 3;
107  // The special allocations (e.g. pre-allocated heap memory, stack reservation)
108  // that are not captured in the MemoryActivityMetadata of
109  // memory_profile_snapshots. Need to handle separately.
110  repeated MemoryActivityMetadata special_allocations = 4;
111}
112
113// Data for memory usage analysis in one host.
114message MemoryProfile {
115  // A map from memory allocator's id to PerAllocatorMemoryProfile for memory
116  // usage analysis on this host.
117  map<string /*memory_id*/, PerAllocatorMemoryProfile>
118      memory_profile_per_allocator = 1;
119  // Number of hosts profiled, used to populate host selection list at front
120  // end.
121  int32 num_hosts = 2;
122  // Ids for profiled memory allocators, used to populate memory selection list
123  // at front end.
124  repeated string memory_ids = 3;
125  reserved 4;
126}
127