v8 12.4.254 (node 22.4.1)
V8 is Google's open source JavaScript engine
Loading...
Searching...
No Matches
v8-profiler.h
Go to the documentation of this file.
1// Copyright 2010 the V8 project authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef V8_V8_PROFILER_H_
6#define V8_V8_PROFILER_H_
7
8#include <limits.h>
9
10#include <memory>
11#include <unordered_set>
12#include <vector>
13
14#include "cppgc/common.h" // NOLINT(build/include_directory)
15#include "v8-local-handle.h" // NOLINT(build/include_directory)
16#include "v8-message.h" // NOLINT(build/include_directory)
17#include "v8-persistent-handle.h" // NOLINT(build/include_directory)
18
22namespace v8 {
23
24enum class EmbedderStateTag : uint8_t;
25class HeapGraphNode;
26struct HeapStatsUpdate;
27class Object;
28enum StateTag : uint16_t;
29
30using NativeObject = void*;
31using SnapshotObjectId = uint32_t;
32using ProfilerId = uint32_t;
33
36 size_t position;
37};
38
39namespace internal {
40class CpuProfile;
41} // namespace internal
42
43} // namespace v8
44
45#ifdef V8_OS_WIN
46template class V8_EXPORT std::vector<v8::CpuProfileDeoptFrame>;
47#endif
48
49namespace v8 {
50
53 const char* deopt_reason;
54 std::vector<CpuProfileDeoptFrame> stack;
55};
56
57} // namespace v8
58
59#ifdef V8_OS_WIN
60template class V8_EXPORT std::vector<v8::CpuProfileDeoptInfo>;
61#endif
62
63namespace v8 {
64
69 public:
70 struct LineTick {
72 int line;
73
75 unsigned int hit_count;
76 };
77
78 // An annotation hinting at the source of a CpuProfileNode.
80 // User-supplied script with associated resource information.
81 kScript = 0,
82 // Native scripts and provided builtins.
83 kBuiltin = 1,
84 // Callbacks into native code.
85 kCallback = 2,
86 // VM-internal functions or state.
87 kInternal = 3,
88 // A node that failed to symbolize.
89 kUnresolved = 4,
90 };
91
94
100 const char* GetFunctionNameStr() const;
101
103 int GetScriptId() const;
104
107
113 const char* GetScriptResourceNameStr() const;
114
120
125 int GetLineNumber() const;
126
131 int GetColumnNumber() const;
132
136 unsigned int GetHitLineCount() const;
137
143 bool GetLineTicks(LineTick* entries, unsigned int length) const;
144
148 const char* GetBailoutReason() const;
149
153 unsigned GetHitCount() const;
154
156 unsigned GetNodeId() const;
157
162
164 int GetChildrenCount() const;
165
167 const CpuProfileNode* GetChild(int index) const;
168
170 const CpuProfileNode* GetParent() const;
171
173 const std::vector<CpuProfileDeoptInfo>& GetDeoptInfos() const;
174
175 static const int kNoLineNumberInfo = Message::kNoLineNumberInfo;
176 static const int kNoColumnNumberInfo = Message::kNoColumnInfo;
177};
178
183 public:
184 enum WriteResult { kContinue = 0, kAbort = 1 };
185 virtual ~OutputStream() = default;
187 virtual void EndOfStream() = 0;
189 virtual int GetChunkSize() { return 1024; }
195 virtual WriteResult WriteAsciiChunk(char* data, int size) = 0;
202 return kAbort;
203 }
204};
205
211 public:
213 kJSON = 0 // See format description near 'Serialize' method.
214 };
217
220
225 int GetSamplesCount() const;
226
231 const CpuProfileNode* GetSample(int index) const;
232
238 int64_t GetSampleTimestamp(int index) const;
239
244 int64_t GetStartTime() const;
245
249 StateTag GetSampleState(int index) const;
250
255
261 int64_t GetEndTime() const;
262
267 void Delete();
268
286 SerializationFormat format = kJSON) const;
287};
288
290 // In the resulting CpuProfile tree, intermediate nodes in a stack trace
291 // (from the root to a leaf) will have line numbers that point to the start
292 // line of the function, rather than the line of the callsite of the child.
294 // In the resulting CpuProfile tree, nodes are separated based on the line
295 // number of their callsite in their parent.
297};
298
299// Determines how names are derived for functions sampled.
301 // Use the immediate name of functions at compilation time.
303 // Use more verbose naming for functions without names, inferred from scope
304 // where possible.
306};
307
309 // Enables logging when a profile is active, and disables logging when all
310 // profiles are detached.
312 // Enables logging for the lifetime of the CpuProfiler. Calls to
313 // StartRecording are faster, at the expense of runtime overhead.
315};
316
317// Enum for returning profiling status. Once StartProfiling is called,
318// we want to return to clients whether the profiling was able to start
319// correctly, or return a descriptive error.
321 kStarted,
324};
325
333};
334
339 public:
341
342 virtual ~DiscardedSamplesDelegate() = default;
343 virtual void Notify() = 0;
344
345 ProfilerId GetId() const { return profiler_id_; }
346
347 private:
348 friend internal::CpuProfile;
349
350 void SetId(ProfilerId id) { profiler_id_ = id; }
351
352 ProfilerId profiler_id_;
353};
354
359 public:
360 // Indicates that the sample buffer size should not be explicitly limited.
361 static const unsigned kNoSampleLimit = UINT_MAX;
362
379 CpuProfilingMode mode = kLeafNodeLineNumbers,
380 unsigned max_samples = kNoSampleLimit, int sampling_interval_us = 0,
381 MaybeLocal<Context> filter_context = MaybeLocal<Context>());
382
385
386 CpuProfilingMode mode() const { return mode_; }
387 unsigned max_samples() const { return max_samples_; }
388 int sampling_interval_us() const { return sampling_interval_us_; }
389
390 private:
391 friend class internal::CpuProfile;
392
393 bool has_filter_context() const { return !filter_context_.IsEmpty(); }
394 void* raw_filter_context() const;
395
396 CpuProfilingMode mode_;
397 unsigned max_samples_;
398 int sampling_interval_us_;
399 Global<Context> filter_context_;
400};
401
407 public:
413 static CpuProfiler* New(Isolate* isolate,
414 CpuProfilingNamingMode = kDebugNaming,
415 CpuProfilingLoggingMode = kLazyLogging);
416
422 static void CollectSample(Isolate* isolate);
423
427 void Dispose();
428
435
444
450 CpuProfilingOptions options,
451 std::unique_ptr<DiscardedSamplesDelegate> delegate = nullptr);
452
459 Local<String> title, CpuProfilingOptions options,
460 std::unique_ptr<DiscardedSamplesDelegate> delegate = nullptr);
461
474 Local<String> title, CpuProfilingMode mode, bool record_samples = false,
475 unsigned max_samples = CpuProfilingOptions::kNoSampleLimit);
476
482 CpuProfilingResult Start(Local<String> title, bool record_samples = false);
483
490 Local<String> title, CpuProfilingOptions options,
491 std::unique_ptr<DiscardedSamplesDelegate> delegate = nullptr);
492
505 Local<String> title, CpuProfilingMode mode, bool record_samples = false,
506 unsigned max_samples = CpuProfilingOptions::kNoSampleLimit);
507
514 bool record_samples = false);
515
520
526
532
533 private:
534 CpuProfiler();
535 ~CpuProfiler();
536 CpuProfiler(const CpuProfiler&);
537 CpuProfiler& operator=(const CpuProfiler&);
538};
539
545 public:
546 enum Type {
547 kContextVariable = 0, // A variable from a function context.
548 kElement = 1, // An element of an array.
549 kProperty = 2, // A named object property.
550 kInternal = 3, // A link that can't be accessed from JS,
551 // thus, its name isn't a real property name
552 // (e.g. parts of a ConsString).
553 kHidden = 4, // A link that is needed for proper sizes
554 // calculation, but may be hidden from user.
555 kShortcut = 5, // A link that must not be followed during
556 // sizes calculation.
557 kWeak = 6 // A weak reference (ignored by the GC).
558 };
559
561 Type GetType() const;
562
568
571
573 const HeapGraphNode* GetToNode() const;
574};
575
576
581 public:
582 enum Type {
583 kHidden = 0, // Hidden node, may be filtered when shown to user.
584 kArray = 1, // An array of elements.
585 kString = 2, // A string.
586 kObject = 3, // A JS object (except for arrays and strings).
587 kCode = 4, // Compiled code.
588 kClosure = 5, // Function closure.
589 kRegExp = 6, // RegExp.
590 kHeapNumber = 7, // Number stored in the heap.
591 kNative = 8, // Native object (not from V8 heap).
592 kSynthetic = 9, // Synthetic object, usually used for grouping
593 // snapshot items together.
594 kConsString = 10, // Concatenated string. A pair of pointers to strings.
595 kSlicedString = 11, // Sliced string. A fragment of another string.
596 kSymbol = 12, // A Symbol (ES6).
597 kBigInt = 13, // BigInt.
598 kObjectShape = 14, // Internal data used for tracking the shapes (or
599 // "hidden classes") of JS objects.
600 };
601
603 Type GetType() const;
604
611
617
619 size_t GetShallowSize() const;
620
622 int GetChildrenCount() const;
623
625 const HeapGraphEdge* GetChild(int index) const;
626};
627
632 public:
634 kJSON = 0 // See format description near 'Serialize' method.
635 };
636
638 const HeapGraphNode* GetRoot() const;
639
642
644 int GetNodesCount() const;
645
647 const HeapGraphNode* GetNode(int index) const;
648
651
657 void Delete();
658
686 SerializationFormat format = kJSON) const;
687};
688
689
695 public:
697 kContinue = 0,
698 kAbort = 1
699 };
700 virtual ~ActivityControl() = default;
705 virtual ControlOption ReportProgressValue(uint32_t done, uint32_t total) = 0;
706};
707
713 public:
714 struct Allocation {
718 size_t size;
719
723 unsigned int count;
724 };
725
729 struct Node {
735
741
747
752
758
764
768 uint32_t node_id;
769
775 std::vector<Node*> children;
776
780 std::vector<Allocation> allocations;
781 };
782
786 struct Sample {
790 uint32_t node_id;
791
795 size_t size;
796
800 unsigned int count;
801
806 uint64_t sample_id;
807 };
808
814 virtual Node* GetRootNode() = 0;
815 virtual const std::vector<Sample>& GetSamples() = 0;
816
817 virtual ~AllocationProfile() = default;
818
819 static const int kNoLineNumberInfo = Message::kNoLineNumberInfo;
820 static const int kNoColumnNumberInfo = Message::kNoColumnInfo;
821};
822
838 public:
839 class Node {
840 public:
848 enum class Detachedness : uint8_t {
849 kUnknown = 0,
850 kAttached = 1,
851 kDetached = 2,
852 };
853
854 Node() = default;
855 virtual ~Node() = default;
856 virtual const char* Name() = 0;
857 virtual size_t SizeInBytes() = 0;
863 virtual Node* WrapperNode() { return nullptr; }
864 virtual bool IsRootNode() { return false; }
866 virtual bool IsEmbedderNode() { return true; }
870 virtual const char* NamePrefix() { return nullptr; }
871
876 virtual NativeObject GetNativeObject() { return nullptr; }
877
884 virtual Detachedness GetDetachedness() { return Detachedness::kUnknown; }
885
893 virtual const void* GetAddress() { return nullptr; }
894
895 Node(const Node&) = delete;
896 Node& operator=(const Node&) = delete;
897 };
898
903 virtual Node* V8Node(const v8::Local<v8::Value>& value) = 0;
904
909 virtual Node* AddNode(std::unique_ptr<Node> node) = 0;
910
919 virtual void AddEdge(Node* from, Node* to, const char* name = nullptr) = 0;
920
921 virtual ~EmbedderGraph() = default;
922};
923
925 public:
926 virtual ~QueryObjectPredicate() = default;
927 virtual bool Filter(v8::Local<v8::Object> object) = 0;
928};
929
935 public:
937 QueryObjectPredicate* predicate,
938 std::vector<v8::Global<v8::Object>>* objects);
939
941 kSamplingNoFlags = 0,
942 kSamplingForceGC = 1 << 0,
943 kSamplingIncludeObjectsCollectedByMajorGC = 1 << 1,
944 kSamplingIncludeObjectsCollectedByMinorGC = 1 << 2,
945 };
946
953 typedef void (*BuildEmbedderGraphCallback)(v8::Isolate* isolate,
954 v8::EmbedderGraph* graph,
955 void* data);
956
966 v8::Isolate* isolate, const v8::Local<v8::Value>& v8_value,
967 uint16_t class_id, void* data);
968
971
973 const HeapSnapshot* GetHeapSnapshot(int index);
974
980
986
992
999
1005 static const SnapshotObjectId kUnknownObjectId = 0;
1006
1011 public:
1016 virtual const char* GetName(Local<Object> object) = 0;
1017
1018 protected:
1019 virtual ~ObjectNameResolver() = default;
1020 };
1021
1022 enum class HeapSnapshotMode {
1026 kRegular,
1030 kExposeInternals,
1031 };
1032
1033 enum class NumericsMode {
1038 kHideNumericValues,
1042 kExposeNumericValues
1043 };
1044
1045 struct HeapSnapshotOptions final {
1046 // Manually define default constructor here to be able to use it in
1047 // `TakeSnapshot()` below.
1048 // NOLINTNEXTLINE
1050
1054 ActivityControl* control = nullptr;
1058 ObjectNameResolver* global_object_name_resolver = nullptr;
1062 HeapSnapshotMode snapshot_mode = HeapSnapshotMode::kRegular;
1066 NumericsMode numerics_mode = NumericsMode::kHideNumericValues;
1072 };
1073
1080 const HeapSnapshotOptions& options = HeapSnapshotOptions());
1081
1089 ActivityControl* control,
1090 ObjectNameResolver* global_object_name_resolver = nullptr,
1091 bool hide_internals = true, bool capture_numeric_value = false);
1092
1102 void StartTrackingHeapObjects(bool track_allocations = false);
1103
1118 int64_t* timestamp_us = nullptr);
1119
1126
1152 bool StartSamplingHeapProfiler(uint64_t sample_interval = 512 * 1024,
1153 int stack_depth = 16,
1154 SamplingFlags flags = kSamplingNoFlags);
1155
1160
1168
1174
1175 void AddBuildEmbedderGraphCallback(BuildEmbedderGraphCallback callback,
1176 void* data);
1177 void RemoveBuildEmbedderGraphCallback(BuildEmbedderGraphCallback callback,
1178 void* data);
1179
1181
1187 static const uint16_t kPersistentHandleNoClassId = 0;
1188
1189 private:
1190 HeapProfiler();
1191 ~HeapProfiler();
1192 HeapProfiler(const HeapProfiler&);
1193 HeapProfiler& operator=(const HeapProfiler&);
1194};
1195
1201 HeapStatsUpdate(uint32_t index, uint32_t count, uint32_t size)
1202 : index(index), count(count), size(size) { }
1203 uint32_t index; // Index of the time interval that was changed.
1204 uint32_t count; // New value of count field for the interval with this index.
1205 uint32_t size; // New value of size field for the interval with this index.
1206};
1207
1208#define CODE_EVENTS_LIST(V) \
1209 V(Builtin) \
1210 V(Callback) \
1211 V(Eval) \
1212 V(Function) \
1213 V(InterpretedFunction) \
1214 V(Handler) \
1215 V(BytecodeHandler) \
1216 V(LazyCompile) /* Unused, use kFunction instead */ \
1217 V(RegExp) \
1218 V(Script) \
1219 V(Stub) \
1220 V(Relocation)
1221
1227 kUnknownType = 0
1228#define V(Name) , k##Name##Type
1230#undef V
1232
1237 public:
1239 size_t GetCodeSize();
1250 const char* GetComment();
1251
1252 static const char* GetCodeEventTypeName(CodeEventType code_event_type);
1253
1255};
1256
1261 public:
1267 explicit CodeEventHandler(Isolate* isolate);
1269
1278 virtual void Handle(CodeEvent* code_event) = 0;
1279
1284 void Enable();
1285
1290 void Disable();
1291
1292 private:
1295 CodeEventHandler& operator=(const CodeEventHandler&);
1296 void* internal_listener_;
1297};
1298
1299} // namespace v8
1300
1301
1302#endif // V8_V8_PROFILER_H_
virtual ~ActivityControl()=default
virtual ControlOption ReportProgressValue(uint32_t done, uint32_t total)=0
virtual ~AllocationProfile()=default
virtual Node * GetRootNode()=0
virtual const std::vector< Sample > & GetSamples()=0
virtual void Handle(CodeEvent *code_event)=0
virtual ~CodeEventHandler()
CodeEventHandler(Isolate *isolate)
int GetScriptLine()
CodeEventType GetCodeType()
size_t GetCodeSize()
Local< String > GetFunctionName()
int GetScriptColumn()
Local< String > GetScriptName()
uintptr_t GetCodeStartAddress()
const char * GetComment()
static const char * GetCodeEventTypeName(CodeEventType code_event_type)
uintptr_t GetPreviousCodeStartAddress()
int64_t GetStartTime() const
StateTag GetSampleState(int index) const
const CpuProfileNode * GetTopDownRoot() const
EmbedderStateTag GetSampleEmbedderState(int index) const
void Serialize(OutputStream *stream, SerializationFormat format=kJSON) const
int64_t GetSampleTimestamp(int index) const
Local< String > GetTitle() const
int GetSamplesCount() const
int64_t GetEndTime() const
const CpuProfileNode * GetSample(int index) const
const char * GetBailoutReason() const
const CpuProfileNode * GetParent() const
Local< String > GetFunctionName() const
int GetChildrenCount() const
const std::vector< CpuProfileDeoptInfo > & GetDeoptInfos() const
unsigned GetNodeId() const
const char * GetScriptResourceNameStr() const
bool IsScriptSharedCrossOrigin() const
Local< String > GetScriptResourceName() const
bool GetLineTicks(LineTick *entries, unsigned int length) const
int GetLineNumber() const
const CpuProfileNode * GetChild(int index) const
int GetColumnNumber() const
unsigned int GetHitLineCount() const
int GetScriptId() const
SourceType GetSourceType() const
const char * GetFunctionNameStr() const
unsigned GetHitCount() const
CpuProfilingResult Start(Local< String > title, bool record_samples=false)
CpuProfile * StopProfiling(Local< String > title)
CpuProfilingResult Start(Local< String > title, CpuProfilingOptions options, std::unique_ptr< DiscardedSamplesDelegate > delegate=nullptr)
static void CollectSample(Isolate *isolate)
CpuProfilingResult Start(Local< String > title, CpuProfilingMode mode, bool record_samples=false, unsigned max_samples=CpuProfilingOptions::kNoSampleLimit)
CpuProfile * Stop(ProfilerId id)
void SetSamplingInterval(int us)
CpuProfilingStatus StartProfiling(Local< String > title, CpuProfilingMode mode, bool record_samples=false, unsigned max_samples=CpuProfilingOptions::kNoSampleLimit)
CpuProfilingStatus StartProfiling(Local< String > title, bool record_samples=false)
static void UseDetailedSourcePositionsForProfiling(Isolate *isolate)
void SetUsePreciseSampling(bool)
CpuProfilingStatus StartProfiling(Local< String > title, CpuProfilingOptions options, std::unique_ptr< DiscardedSamplesDelegate > delegate=nullptr)
CpuProfilingResult Start(CpuProfilingOptions options, std::unique_ptr< DiscardedSamplesDelegate > delegate=nullptr)
static CpuProfiler * New(Isolate *isolate, CpuProfilingNamingMode=kDebugNaming, CpuProfilingLoggingMode=kLazyLogging)
unsigned max_samples() const
CpuProfilingOptions & operator=(CpuProfilingOptions &&)=default
CpuProfilingMode mode() const
int sampling_interval_us() const
CpuProfilingOptions(CpuProfilingMode mode=kLeafNodeLineNumbers, unsigned max_samples=kNoSampleLimit, int sampling_interval_us=0, MaybeLocal< Context > filter_context=MaybeLocal< Context >())
CpuProfilingOptions(CpuProfilingOptions &&)=default
virtual ~DiscardedSamplesDelegate()=default
ProfilerId GetId() const
virtual const char * NamePrefix()
virtual const char * Name()=0
virtual bool IsRootNode()
virtual Node * WrapperNode()
Node & operator=(const Node &)=delete
Node(const Node &)=delete
virtual const void * GetAddress()
virtual NativeObject GetNativeObject()
virtual ~Node()=default
virtual Detachedness GetDetachedness()
virtual size_t SizeInBytes()=0
virtual bool IsEmbedderNode()
virtual Node * V8Node(const v8::Local< v8::Value > &value)=0
virtual ~EmbedderGraph()=default
virtual void AddEdge(Node *from, Node *to, const char *name=nullptr)=0
virtual Node * AddNode(std::unique_ptr< Node > node)=0
const HeapGraphNode * GetToNode() const
Type GetType() const
Local< Value > GetName() const
const HeapGraphNode * GetFromNode() const
const HeapGraphEdge * GetChild(int index) const
Type GetType() const
SnapshotObjectId GetId() const
int GetChildrenCount() const
Local< String > GetName() const
size_t GetShallowSize() const
virtual const char * GetName(Local< Object > object)=0
const HeapSnapshot * TakeHeapSnapshot(ActivityControl *control, ObjectNameResolver *global_object_name_resolver=nullptr, bool hide_internals=true, bool capture_numeric_value=false)
bool StartSamplingHeapProfiler(uint64_t sample_interval=512 *1024, int stack_depth=16, SamplingFlags flags=kSamplingNoFlags)
SnapshotObjectId GetObjectId(Local< Value > value)
const HeapSnapshot * TakeHeapSnapshot(const HeapSnapshotOptions &options=HeapSnapshotOptions())
void RemoveBuildEmbedderGraphCallback(BuildEmbedderGraphCallback callback, void *data)
void DeleteAllHeapSnapshots()
EmbedderGraph::Node::Detachedness(*)(v8::Isolate *isolate, const v8::Local< v8::Value > &v8_value, uint16_t class_id, void *data) GetDetachednessCallback
AllocationProfile * GetAllocationProfile()
void StopTrackingHeapObjects()
void SetGetDetachednessCallback(GetDetachednessCallback callback, void *data)
void QueryObjects(v8::Local< v8::Context > context, QueryObjectPredicate *predicate, std::vector< v8::Global< v8::Object > > *objects)
SnapshotObjectId GetHeapStats(OutputStream *stream, int64_t *timestamp_us=nullptr)
const HeapSnapshot * GetHeapSnapshot(int index)
Local< Value > FindObjectById(SnapshotObjectId id)
void StartTrackingHeapObjects(bool track_allocations=false)
void StopSamplingHeapProfiler()
SnapshotObjectId GetObjectId(NativeObject value)
void AddBuildEmbedderGraphCallback(BuildEmbedderGraphCallback callback, void *data)
const HeapGraphNode * GetNodeById(SnapshotObjectId id) const
SnapshotObjectId GetMaxSnapshotJSObjectId() const
const HeapGraphNode * GetNode(int index) const
void Serialize(OutputStream *stream, SerializationFormat format=kJSON) const
int GetNodesCount() const
const HeapGraphNode * GetRoot() const
virtual WriteResult WriteHeapStatsChunk(HeapStatsUpdate *data, int count)
virtual WriteResult WriteAsciiChunk(char *data, int size)=0
virtual int GetChunkSize()
virtual void EndOfStream()=0
virtual ~OutputStream()=default
virtual bool Filter(v8::Local< v8::Object > object)=0
virtual ~QueryObjectPredicate()=default
EmbedderStackState
Definition common.h:15
void * NativeObject
Definition v8-profiler.h:30
CpuProfilingStatus
CpuProfilingLoggingMode
@ kLazyLogging
@ kEagerLogging
CpuProfilingMode
@ kLeafNodeLineNumbers
@ kCallerLineNumbers
StateTag
Definition v8-unwinder.h:36
uint32_t ProfilerId
Definition v8-profiler.h:32
CodeEventType
@ kUnknownType
CpuProfilingNamingMode
@ kDebugNaming
@ kStandardNaming
uint32_t SnapshotObjectId
Definition v8-profiler.h:31
std::vector< Node * > children
Local< String > script_name
std::vector< Allocation > allocations
const char * deopt_reason
Definition v8-profiler.h:53
std::vector< CpuProfileDeoptFrame > stack
Definition v8-profiler.h:54
const CpuProfilingStatus status
const ProfilerId id
HeapStatsUpdate(uint32_t index, uint32_t count, uint32_t size)
#define V(Name)
#define CODE_EVENTS_LIST(V)
#define V8_EXPORT
Definition v8config.h:753