1 #ifndef __MONO_PROFLOG_H__
2 #define __MONO_PROFLOG_H__
5 #define MONO_PROFILER_UNSTABLE_GC_ROOTS
6 #include <mono/metadata/profiler.h>
8 #define BUF_ID 0x4D504C01
9 #define LOG_HEADER_ID 0x4D505A01
10 #define LOG_VERSION_MAJOR 2
11 #define LOG_VERSION_MINOR 0
12 #define LOG_DATA_VERSION 14
15 * Changes in major/minor versions:
16 * version 1.0: removed sysid field from header
17 * added args, arch, os fields to header
19 * Changes in data versions:
20 * version 2: added offsets in heap walk
21 * version 3: added GC roots
22 * version 4: added sample/statistical profiling
23 * version 5: added counters sampling
24 * version 6: added optional backtrace in sampling info
25 * version 8: added TYPE_RUNTIME and JIT helpers/trampolines
26 * version 9: added MONO_PROFILER_CODE_BUFFER_EXCEPTION_HANDLING
27 * version 10: added TYPE_COVERAGE
28 * version 11: added thread ID to TYPE_SAMPLE_HIT
29 added more load/unload events
32 load/unload for appdomain
33 load/unload for contexts
34 load/unload/name for assemblies
35 removed TYPE_LOAD_ERR flag (profiler never generated it, now removed from the format itself)
36 added TYPE_GC_HANDLE_{CREATED,DESTROYED}_BT
37 TYPE_JIT events are no longer guaranteed to have code start/size info (can be zero)
38 * version 12: added MONO_COUNTER_PROFILER
39 * version 13: added MONO_GC_EVENT_{PRE_STOP_WORLD_LOCKED,POST_START_WORLD_UNLOCKED}
40 added TYPE_META + TYPE_SYNC_POINT
41 removed il and native offset in TYPE_SAMPLE_HIT
42 methods in backtraces are now encoded as proper method pointers
43 removed flags in backtrace format
44 removed flags in metadata events
45 changed the following fields to a single byte rather than leb128
46 TYPE_GC_EVENT: event_type, generation
47 TYPE_HEAP_ROOT: root_type
49 TYPE_SAMPLE_HIT: sample_type
50 TYPE_CLAUSE: clause_type
51 TYPE_SAMPLE_COUNTERS_DESC: type, unit, variance
52 TYPE_SAMPLE_COUNTERS: type
53 added time fields to all events that were missing one
57 TYPE_SAMPLE_COUNTERS_DESC
59 TYPE_COVERAGE_STATEMENT
61 TYPE_COVERAGE_ASSEMBLY
62 moved the time field in TYPE_SAMPLE_HIT to right after the event byte, now encoded as a regular time field
63 changed the time field in TYPE_SAMPLE_COUNTERS to be encoded as a regular time field (in nanoseconds)
64 added TYPE_GC_FINALIZE_{START,END,OBJECT_START,OBJECT_END}
65 * version 14: added event field to TYPE_MONITOR instead of encoding it in the extended info
66 all TYPE_MONITOR events can now contain backtraces
67 changed address field in TYPE_SAMPLE_UBIN to be based on ptr_base
68 added an image pointer field to assembly load events
69 added an exception object field to TYPE_CLAUSE
70 class unload events no longer exist (they were never emitted)
71 removed type field from TYPE_SAMPLE_HIT
72 removed MONO_GC_EVENT_{MARK,RECLAIM}_{START,END}
79 * The file is composed by a header followed by 0 or more buffers.
80 * Each buffer contains events that happened on a thread: for a given thread
81 * buffers that appear later in the file are guaranteed to contain events
82 * that happened later in time. Buffers from separate threads could be interleaved,
84 * Buffers are not required to be aligned.
87 * [id: 4 bytes] constant value: LOG_HEADER_ID
88 * [major: 1 byte] [minor: 1 byte] major and minor version of the log profiler
89 * [format: 1 byte] version of the data format for the rest of the file
90 * [ptrsize: 1 byte] size in bytes of a pointer in the profiled program
91 * [startup time: 8 bytes] time in milliseconds since the unix epoch when the program started
92 * [timer overhead: 4 bytes] approximate overhead in nanoseconds of the timer
93 * [flags: 4 bytes] file format flags, should be 0 for now
94 * [pid: 4 bytes] pid of the profiled process
95 * [port: 2 bytes] tcp port for server if != 0
96 * [args size: 4 bytes] size of args
97 * [args: string] arguments passed to the profiler
98 * [arch size: 4 bytes] size of arch
99 * [arch: string] architecture the profiler is running on
100 * [os size: 4 bytes] size of os
101 * [os: string] operating system the profiler is running on
103 * The multiple byte integers are in little-endian format.
106 * [buffer header] [event]*
107 * Buffers have a fixed-size header followed by 0 or more bytes of event data.
108 * Timing information and other values in the event data are usually stored
109 * as uleb128 or sleb128 integers. To save space, as noted for each item below,
110 * some data is represented as a difference between the actual value and
111 * either the last value of the same type (like for timing information) or
112 * as the difference from a value stored in a buffer header.
114 * For timing information the data is stored as uleb128, since timing
115 * increases in a monotonic way in each thread: the value is the number of
116 * nanoseconds to add to the last seen timing data in a buffer. The first value
117 * in a buffer will be calculated from the time_base field in the buffer head.
119 * Object or heap sizes are stored as uleb128.
120 * Pointer differences are stored as sleb128, instead.
122 * If an unexpected value is found, the rest of the buffer should be ignored,
123 * as generally the later values need the former to be interpreted correctly.
125 * buffer header format:
126 * [bufid: 4 bytes] constant value: BUF_ID
127 * [len: 4 bytes] size of the data following the buffer header
128 * [time_base: 8 bytes] time base in nanoseconds since an unspecified epoch
129 * [ptr_base: 8 bytes] base value for pointers
130 * [obj_base: 8 bytes] base value for object addresses
131 * [thread id: 8 bytes] system-specific thread ID (pthread_t for example)
132 * [method_base: 8 bytes] base value for MonoMethod pointers
135 * [extended info: upper 4 bits] [type: lower 4 bits]
136 * [time diff: uleb128] nanoseconds since last timing
138 * The data that follows depends on type and the extended info.
139 * Type is one of the enum values in mono-profiler-log.h: TYPE_ALLOC, TYPE_GC,
140 * TYPE_METADATA, TYPE_METHOD, TYPE_EXCEPTION, TYPE_MONITOR, TYPE_HEAP.
141 * The extended info bits are interpreted based on type, see
142 * each individual event description below.
143 * strings are represented as a 0-terminated utf8 sequence.
146 * [num: uleb128] number of frames following
147 * [frame: sleb128]* mum MonoMethod* as a pointer difference from the last such
148 * pointer or the buffer method_base
152 * exinfo: zero or TYPE_ALLOC_BT
153 * [ptr: sleb128] class as a byte difference from ptr_base
154 * [obj: sleb128] object address as a byte difference from obj_base
155 * [size: uleb128] size of the object in the heap
156 * If exinfo == TYPE_ALLOC_BT, a backtrace follows.
160 * exinfo: one of TYPE_GC_EVENT, TYPE_GC_RESIZE, TYPE_GC_MOVE, TYPE_GC_HANDLE_CREATED[_BT],
161 * TYPE_GC_HANDLE_DESTROYED[_BT], TYPE_GC_FINALIZE_START, TYPE_GC_FINALIZE_END,
162 * TYPE_GC_FINALIZE_OBJECT_START, TYPE_GC_FINALIZE_OBJECT_END
163 * if exinfo == TYPE_GC_RESIZE
164 * [heap_size: uleb128] new heap size
165 * if exinfo == TYPE_GC_EVENT
166 * [event type: byte] GC event (MONO_GC_EVENT_* from profiler.h)
167 * [generation: byte] GC generation event refers to
168 * if exinfo == TYPE_GC_MOVE
169 * [num_objects: uleb128] number of object moves that follow
170 * [objaddr: sleb128]+ num_objects object pointer differences from obj_base
171 * num is always an even number: the even items are the old
172 * addresses, the odd numbers are the respective new object addresses
173 * if exinfo == TYPE_GC_HANDLE_CREATED[_BT]
174 * [handle_type: uleb128] MonoGCHandleType enum value
175 * upper bits reserved as flags
176 * [handle: uleb128] GC handle value
177 * [objaddr: sleb128] object pointer differences from obj_base
178 * If exinfo == TYPE_GC_HANDLE_CREATED_BT, a backtrace follows.
179 * if exinfo == TYPE_GC_HANDLE_DESTROYED[_BT]
180 * [handle_type: uleb128] MonoGCHandleType enum value
181 * upper bits reserved as flags
182 * [handle: uleb128] GC handle value
183 * If exinfo == TYPE_GC_HANDLE_DESTROYED_BT, a backtrace follows.
184 * if exinfo == TYPE_GC_FINALIZE_OBJECT_{START,END}
185 * [object: sleb128] the object as a difference from obj_base
187 * type metadata format:
188 * type: TYPE_METADATA
189 * exinfo: one of: TYPE_END_LOAD, TYPE_END_UNLOAD (optional for TYPE_THREAD and TYPE_DOMAIN,
190 * doesn't occur for TYPE_CLASS)
191 * [mtype: byte] metadata type, one of: TYPE_CLASS, TYPE_IMAGE, TYPE_ASSEMBLY, TYPE_DOMAIN,
192 * TYPE_THREAD, TYPE_CONTEXT
193 * [pointer: sleb128] pointer of the metadata type depending on mtype
194 * if mtype == TYPE_CLASS
195 * [image: sleb128] MonoImage* as a pointer difference from ptr_base
196 * [name: string] full class name
197 * if mtype == TYPE_IMAGE
198 * [name: string] image file name
199 * if mtype == TYPE_ASSEMBLY
200 * [image: sleb128] MonoImage* as a pointer difference from ptr_base
201 * [name: string] assembly name
202 * if mtype == TYPE_DOMAIN && exinfo == 0
203 * [name: string] domain friendly name
204 * if mtype == TYPE_CONTEXT
205 * [domain: sleb128] domain id as pointer
206 * if mtype == TYPE_THREAD && exinfo == 0
207 * [name: string] thread name
209 * type method format:
211 * exinfo: one of: TYPE_LEAVE, TYPE_ENTER, TYPE_EXC_LEAVE, TYPE_JIT
212 * [method: sleb128] MonoMethod* as a pointer difference from the last such
213 * pointer or the buffer method_base
214 * if exinfo == TYPE_JIT
215 * [code address: sleb128] pointer to the native code as a diff from ptr_base
216 * [code size: uleb128] size of the generated code
217 * [name: string] full method name
219 * type exception format:
220 * type: TYPE_EXCEPTION
221 * exinfo: zero, TYPE_CLAUSE, or TYPE_THROW_BT
222 * if exinfo == TYPE_CLAUSE
223 * [clause type: byte] MonoExceptionEnum enum value
224 * [clause index: uleb128] index of the current clause
225 * [method: sleb128] MonoMethod* as a pointer difference from the last such
226 * pointer or the buffer method_base
227 * [object: sleb128] the exception object as a difference from obj_base
229 * [object: sleb128] the exception object as a difference from obj_base
230 * If exinfo == TYPE_THROW_BT, a backtrace follows.
232 * type runtime format:
234 * exinfo: one of: TYPE_JITHELPER
235 * if exinfo == TYPE_JITHELPER
236 * [type: byte] MonoProfilerCodeBufferType enum value
237 * [buffer address: sleb128] pointer to the native code as a diff from ptr_base
238 * [buffer size: uleb128] size of the generated code
239 * if type == MONO_PROFILER_CODE_BUFFER_SPECIFIC_TRAMPOLINE
240 * [name: string] buffer description name
242 * type monitor format:
244 * exinfo: zero or TYPE_MONITOR_BT
245 * [type: byte] MonoProfilerMonitorEvent enum value
246 * [object: sleb128] the lock object as a difference from obj_base
247 * If exinfo == TYPE_MONITOR_BT, a backtrace follows.
251 * exinfo: one of TYPE_HEAP_START, TYPE_HEAP_END, TYPE_HEAP_OBJECT, TYPE_HEAP_ROOT
252 * if exinfo == TYPE_HEAP_OBJECT
253 * [object: sleb128] the object as a difference from obj_base
254 * [class: sleb128] the object MonoClass* as a difference from ptr_base
255 * [size: uleb128] size of the object on the heap
256 * [num_refs: uleb128] number of object references
257 * each referenced objref is preceded by a uleb128 encoded offset: the
258 * first offset is from the object address and each next offset is relative
259 * to the previous one
260 * [objrefs: sleb128]+ object referenced as a difference from obj_base
261 * The same object can appear multiple times, but only the first time
262 * with size != 0: in the other cases this data will only be used to
263 * provide additional referenced objects.
264 * if exinfo == TYPE_HEAP_ROOT
265 * [num_roots: uleb128] number of root references
266 * [num_gc: uleb128] number of major gcs
267 * [object: sleb128] the object as a difference from obj_base
268 * [root_type: byte] the root_type: MonoProfileGCRootType (profiler.h)
269 * [extra_info: uleb128] the extra_info value
270 * object, root_type and extra_info are repeated num_roots times
274 * exinfo: one of TYPE_SAMPLE_HIT, TYPE_SAMPLE_USYM, TYPE_SAMPLE_UBIN, TYPE_SAMPLE_COUNTERS_DESC, TYPE_SAMPLE_COUNTERS
275 * if exinfo == TYPE_SAMPLE_HIT
276 * [thread: sleb128] thread id as difference from ptr_base
277 * [count: uleb128] number of following instruction addresses
278 * [ip: sleb128]* instruction pointer as difference from ptr_base
279 * [mbt_count: uleb128] number of managed backtrace frames
280 * [method: sleb128]* MonoMethod* as a pointer difference from the last such
281 * pointer or the buffer method_base (the first such method can be also indentified by ip, but this is not neccessarily true)
282 * if exinfo == TYPE_SAMPLE_USYM
283 * [address: sleb128] symbol address as a difference from ptr_base
284 * [size: uleb128] symbol size (may be 0 if unknown)
285 * [name: string] symbol name
286 * if exinfo == TYPE_SAMPLE_UBIN
287 * [address: sleb128] address where binary has been loaded as a difference from ptr_base
288 * [offset: uleb128] file offset of mapping (the same file can be mapped multiple times)
289 * [size: uleb128] memory size
290 * [name: string] binary name
291 * if exinfo == TYPE_SAMPLE_COUNTERS_DESC
292 * [len: uleb128] number of counters
294 * [section: uleb128] section of counter
295 * if section == MONO_COUNTER_PERFCOUNTERS:
296 * [section_name: string] section name of counter
297 * [name: string] name of counter
298 * [type: byte] type of counter
299 * [unit: byte] unit of counter
300 * [variance: byte] variance of counter
301 * [index: uleb128] unique index of counter
302 * if exinfo == TYPE_SAMPLE_COUNTERS
304 * [index: uleb128] unique index of counter
307 * [type: byte] type of counter value
310 * [0: byte] 0 -> value is null
312 * [1: byte] 1 -> value is not null
313 * [value: string] counter value
315 * [value: uleb128/sleb128/double] counter value, can be sleb128, uleb128 or double (determined by using type)
317 * type coverage format
318 * type: TYPE_COVERAGE
319 * exinfo: one of TYPE_COVERAGE_METHOD, TYPE_COVERAGE_STATEMENT, TYPE_COVERAGE_ASSEMBLY, TYPE_COVERAGE_CLASS
320 * if exinfo == TYPE_COVERAGE_METHOD
321 * [assembly: string] name of assembly
322 * [class: string] name of the class
323 * [name: string] name of the method
324 * [signature: string] the signature of the method
325 * [filename: string] the file path of the file that contains this method
326 * [token: uleb128] the method token
327 * [method_id: uleb128] an ID for this data to associate with the buffers of TYPE_COVERAGE_STATEMENTS
328 * [len: uleb128] the number of TYPE_COVERAGE_BUFFERS associated with this method
329 * if exinfo == TYPE_COVERAGE_STATEMENTS
330 * [method_id: uleb128] an the TYPE_COVERAGE_METHOD buffer to associate this with
331 * [offset: uleb128] the il offset relative to the previous offset
332 * [counter: uleb128] the counter for this instruction
333 * [line: uleb128] the line of filename containing this instruction
334 * [column: uleb128] the column containing this instruction
335 * if exinfo == TYPE_COVERAGE_ASSEMBLY
336 * [name: string] assembly name
337 * [guid: string] assembly GUID
338 * [filename: string] assembly filename
339 * [number_of_methods: uleb128] the number of methods in this assembly
340 * [fully_covered: uleb128] the number of fully covered methods
341 * [partially_covered: uleb128] the number of partially covered methods
342 * currently partially_covered will always be 0, and fully_covered is the
343 * number of methods that are fully and partially covered.
344 * if exinfo == TYPE_COVERAGE_CLASS
345 * [name: string] assembly name
346 * [class: string] class name
347 * [number_of_methods: uleb128] the number of methods in this class
348 * [fully_covered: uleb128] the number of fully covered methods
349 * [partially_covered: uleb128] the number of partially covered methods
350 * currently partially_covered will always be 0, and fully_covered is the
351 * number of methods that are fully and partially covered.
355 * exinfo: one of: TYPE_SYNC_POINT
356 * if exinfo == TYPE_SYNC_POINT
357 * [type: byte] MonoProfilerSyncPointType enum value
372 /* extended type for TYPE_HEAP */
373 TYPE_HEAP_START = 0 << 4,
374 TYPE_HEAP_END = 1 << 4,
375 TYPE_HEAP_OBJECT = 2 << 4,
376 TYPE_HEAP_ROOT = 3 << 4,
377 /* extended type for TYPE_METADATA */
378 TYPE_END_LOAD = 2 << 4,
379 TYPE_END_UNLOAD = 4 << 4,
380 /* extended type for TYPE_GC */
381 TYPE_GC_EVENT = 1 << 4,
382 TYPE_GC_RESIZE = 2 << 4,
383 TYPE_GC_MOVE = 3 << 4,
384 TYPE_GC_HANDLE_CREATED = 4 << 4,
385 TYPE_GC_HANDLE_DESTROYED = 5 << 4,
386 TYPE_GC_HANDLE_CREATED_BT = 6 << 4,
387 TYPE_GC_HANDLE_DESTROYED_BT = 7 << 4,
388 TYPE_GC_FINALIZE_START = 8 << 4,
389 TYPE_GC_FINALIZE_END = 9 << 4,
390 TYPE_GC_FINALIZE_OBJECT_START = 10 << 4,
391 TYPE_GC_FINALIZE_OBJECT_END = 11 << 4,
392 /* extended type for TYPE_METHOD */
395 TYPE_EXC_LEAVE = 3 << 4,
397 /* extended type for TYPE_EXCEPTION */
398 TYPE_THROW_NO_BT = 0 << 7,
399 TYPE_THROW_BT = 1 << 7,
400 TYPE_CLAUSE = 1 << 4,
401 /* extended type for TYPE_ALLOC */
402 TYPE_ALLOC_NO_BT = 0 << 4,
403 TYPE_ALLOC_BT = 1 << 4,
404 /* extended type for TYPE_MONITOR */
405 TYPE_MONITOR_NO_BT = 0 << 7,
406 TYPE_MONITOR_BT = 1 << 7,
407 /* extended type for TYPE_SAMPLE */
408 TYPE_SAMPLE_HIT = 0 << 4,
409 TYPE_SAMPLE_USYM = 1 << 4,
410 TYPE_SAMPLE_UBIN = 2 << 4,
411 TYPE_SAMPLE_COUNTERS_DESC = 3 << 4,
412 TYPE_SAMPLE_COUNTERS = 4 << 4,
413 /* extended type for TYPE_RUNTIME */
414 TYPE_JITHELPER = 1 << 4,
415 /* extended type for TYPE_COVERAGE */
416 TYPE_COVERAGE_ASSEMBLY = 0 << 4,
417 TYPE_COVERAGE_METHOD = 1 << 4,
418 TYPE_COVERAGE_STATEMENT = 2 << 4,
419 TYPE_COVERAGE_CLASS = 3 << 4,
420 /* extended type for TYPE_META */
421 TYPE_SYNC_POINT = 0 << 4,
425 /* metadata type byte for TYPE_METADATA */
435 SYNC_POINT_PERIODIC = 0,
436 SYNC_POINT_WORLD_STOP = 1,
437 SYNC_POINT_WORLD_START = 2,
438 } MonoProfilerSyncPointType;
441 MONO_PROFILER_MONITOR_CONTENTION = 1,
442 MONO_PROFILER_MONITOR_DONE = 2,
443 MONO_PROFILER_MONITOR_FAIL = 3,
444 } MonoProfilerMonitorEvent;
447 MONO_PROFILER_GC_HANDLE_CREATED = 0,
448 MONO_PROFILER_GC_HANDLE_DESTROYED = 1,
452 MONO_PROFILER_HEAPSHOT_NONE = 0,
453 MONO_PROFILER_HEAPSHOT_MAJOR = 1,
454 MONO_PROFILER_HEAPSHOT_ON_DEMAND = 2,
455 MONO_PROFILER_HEAPSHOT_X_GC = 3,
456 MONO_PROFILER_HEAPSHOT_X_MS = 4,
457 } MonoProfilerHeapshotMode;
459 // If you alter MAX_FRAMES, you may need to alter SAMPLE_BLOCK_SIZE too.
460 #define MAX_FRAMES 32
462 //The following flags control emitting individual events
463 #define PROFLOG_EXCEPTION_EVENTS (1 << 0)
464 #define PROFLOG_MONITOR_EVENTS (1 << 1)
465 #define PROFLOG_GC_EVENTS (1 << 2)
466 #define PROFLOG_GC_ALLOCATION_EVENTS (1 << 3)
467 #define PROFLOG_GC_MOVE_EVENTS (1 << 4)
468 #define PROFLOG_GC_ROOT_EVENTS (1 << 5)
469 #define PROFLOG_GC_HANDLE_EVENTS (1 << 6)
470 #define PROFLOG_GC_FINALIZATION_EVENTS (1 << 7)
471 #define PROFLOG_COUNTER_EVENTS (1 << 8)
472 #define PROFLOG_SAMPLE_EVENTS (1 << 9)
473 #define PROFLOG_JIT_EVENTS (1 << 10)
475 #define PROFLOG_ALLOC_ALIAS (PROFLOG_GC_EVENTS | PROFLOG_GC_ALLOCATION_EVENTS | PROFLOG_GC_MOVE_EVENTS)
476 #define PROFLOG_HEAPSHOT_ALIAS (PROFLOG_GC_EVENTS | PROFLOG_GC_ROOT_EVENTS)
477 #define PROFLOG_LEGACY_ALIAS (PROFLOG_EXCEPTION_EVENTS | PROFLOG_MONITOR_EVENTS | PROFLOG_GC_EVENTS | PROFLOG_GC_MOVE_EVENTS | PROFLOG_GC_ROOT_EVENTS | PROFLOG_GC_HANDLE_EVENTS | PROFLOG_GC_FINALIZATION_EVENTS | PROFLOG_COUNTER_EVENTS)
480 //Events explicitly enabled
483 //Events explicitly disabled
486 // Actual mask the profiler should use. Can be changed at runtime.
489 // Whether to do method prologue/epilogue instrumentation. Only used at startup.
490 gboolean enter_leave;
492 // Whether to collect code coverage by instrumenting basic blocks.
493 gboolean collect_coverage;
495 //Emit a report at the end of execution
498 //Enable profiler internal debugging
501 //Where to compress the output file
504 // Heapshot mode (every major, on demand, XXgc, XXms). Can be changed at runtime.
505 MonoProfilerHeapshotMode hs_mode;
507 // Heapshot frequency in milliseconds (for MONO_HEAPSHOT_X_MS). Can be changed at runtime.
508 unsigned int hs_freq_ms;
510 // Heapshot frequency in number of collections (for MONO_HEAPSHOT_X_GC). Can be changed at runtime.
511 unsigned int hs_freq_gc;
513 // Whether to do a heapshot on shutdown.
514 gboolean hs_on_shutdown;
516 // Sample frequency in Hertz. Only used at startup.
519 // Maximum number of frames to collect. Can be changed at runtime.
522 // Max depth to record enter/leave events. Can be changed at runtime.
525 //Name of the generated mlpd file
526 const char *output_filename;
528 //Filter files used by the code coverage mode
529 GPtrArray *cov_filter_files;
531 // Port to listen for profiling commands (e.g. "heapshot" for on-demand heapshot).
534 // Maximum number of SampleHit structures. We'll drop samples if this number is not sufficient.
535 int max_allocated_sample_hits;
537 // Sample mode. Only used at startup.
538 MonoProfilerSampleMode sampling_mode;
541 void proflog_parse_args (ProfilerConfig *config, const char *desc);
543 #endif /* __MONO_PROFLOG_H__ */