咨询V8 Profiler日志文件行结构及node --prof日志官方文档

Great question—this is something many custom tool builders grapple with when working with the logs generated by node --prof. Let’s break this down step by step:

1. Basic Line Structure of V8 Profiler Logs #

Each line in the log represents a single event record, structured as:

[record-type] [space-separated fields]

The first token identifies the type of record, and the subsequent fields are specific to that event. Here are some common record types and their key fields to get you started:

• tick: The most frequent record, representing a sampling tick. Fields typically include timestamp, thread ID, program counter (PC) address, and a chain of stack frame addresses (each mapping to compiled code).
• code-creation: Logs when V8 generates compiled code (e.g., JS functions, builtins). Fields include code type (like JS, builtin, or bytecode), start/end memory addresses, and the name of the code/function.
• gc: Tracks garbage collection events. Fields cover GC type (e.g., scavenge, mark-sweep-compact), duration, memory before/after, and pause times.
• map-change: Records changes to object maps (V8’s internal type system). Fields include the object’s address, old map address, new map address, and related type info.
• cpu-profiler-start/cpu-profiler-stop: Marks the start/end of the profiling session, with metadata like sampling interval.

2. Official Documentation for Log Format #

Unfortunately, V8 does not publish a public, comprehensive document detailing every record type and field. The log format is considered an internal implementation detail, so it can (and does) change between V8 versions.

That said, the most authoritative source is the V8 source code itself. Look for these key files:

• src/profiler/profiler-log.cc: Defines how each event is written to the log.
• src/profiler/log-parser.cc: Contains the logic to parse the log back into structured data (used by tools like node --prof-process).
  These files explicitly list every record type, their field order, and what each field represents.

3. What Other Tool Developers Use as Reference #

Most custom tool builders rely on a mix of these resources:

• V8 Source Code: As mentioned above, this is the single most reliable reference. Tools like the built-in node --prof-process are directly built on the parsing logic in V8’s source.
• Community Tooling: Reverse-engineer existing open-source tools (like npm packages for parsing node --prof logs) to see how they handle different record types. Many of these projects document their findings in comments or READMEs.
• Empirical Testing: Generate logs for controlled scenarios (e.g., running a simple function with known behavior) and compare the log entries to the actual runtime events. This is how many developers fill in gaps when the source code is unclear.

A quick tip: Use node --prof-process your-log-file.log to generate a human-readable report, then cross-reference that with the raw log to map fields to their real-world meaning.

内容的提问来源于stack exchange，提问作者Logan R. Kearsley