v8 11.3.244 (node 20.3.0)
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 "v8-local-handle.h" // NOLINT(build/include_directory)
15#include "v8-message.h" // NOLINT(build/include_directory)
16#include "v8-persistent-handle.h" // NOLINT(build/include_directory)
17
21namespace v8 {
22
23enum class EmbedderStateTag : uint8_t;
24class HeapGraphNode;
25struct HeapStatsUpdate;
26class Object;
27enum StateTag : int;
28
29using NativeObject = void*;
30using SnapshotObjectId = uint32_t;
31using ProfilerId = uint32_t;
32
35 size_t position;
36};
37
38namespace internal {
39class CpuProfile;
40} // namespace internal
41
42} // namespace v8
43
44#ifdef V8_OS_WIN
45template class V8_EXPORT std::vector<v8::CpuProfileDeoptFrame>;
46#endif
47
48namespace v8 {
49
52 const char* deopt_reason;
53 std::vector<CpuProfileDeoptFrame> stack;
54};
55
56} // namespace v8
57
58#ifdef V8_OS_WIN
59template class V8_EXPORT std::vector<v8::CpuProfileDeoptInfo>;
60#endif
61
62namespace v8 {
63
68 public:
69 struct LineTick {
71 int line;
72
74 unsigned int hit_count;
75 };
76
77 // An annotation hinting at the source of a CpuProfileNode.
79 // User-supplied script with associated resource information.
80 kScript = 0,
81 // Native scripts and provided builtins.
82 kBuiltin = 1,
83 // Callbacks into native code.
84 kCallback = 2,
85 // VM-internal functions or state.
86 kInternal = 3,
87 // A node that failed to symbolize.
88 kUnresolved = 4,
89 };
90
93
99 const char* GetFunctionNameStr() const;
100
102 int GetScriptId() const;
103
106
112 const char* GetScriptResourceNameStr() const;
113
119
124 int GetLineNumber() const;
125
130 int GetColumnNumber() const;
131
135 unsigned int GetHitLineCount() const;
136
142 bool GetLineTicks(LineTick* entries, unsigned int length) const;
143
147 const char* GetBailoutReason() const;
148
152 unsigned GetHitCount() const;
153
155 unsigned GetNodeId() const;
156
161
163 int GetChildrenCount() const;
164
166 const CpuProfileNode* GetChild(int index) const;
167
169 const CpuProfileNode* GetParent() const;
170
172 const std::vector<CpuProfileDeoptInfo>& GetDeoptInfos() const;
173
174 static const int kNoLineNumberInfo = Message::kNoLineNumberInfo;
175 static const int kNoColumnNumberInfo = Message::kNoColumnInfo;
176};
177
182 public:
183 enum WriteResult { kContinue = 0, kAbort = 1 };
184 virtual ~OutputStream() = default;
186 virtual void EndOfStream() = 0;
188 virtual int GetChunkSize() { return 1024; }
194 virtual WriteResult WriteAsciiChunk(char* data, int size) = 0;
201 return kAbort;
202 }
203};
204
210 public:
212 kJSON = 0 // See format description near 'Serialize' method.
213 };
216
219
224 int GetSamplesCount() const;
225
230 const CpuProfileNode* GetSample(int index) const;
231
237 int64_t GetSampleTimestamp(int index) const;
238
243 int64_t GetStartTime() const;
244
248 StateTag GetSampleState(int index) const;
249
254
260 int64_t GetEndTime() const;
261
266 void Delete();
267
285 SerializationFormat format = kJSON) const;
286};
287
289 // In the resulting CpuProfile tree, intermediate nodes in a stack trace
290 // (from the root to a leaf) will have line numbers that point to the start
291 // line of the function, rather than the line of the callsite of the child.
293 // In the resulting CpuProfile tree, nodes are separated based on the line
294 // number of their callsite in their parent.
296};
297
298// Determines how names are derived for functions sampled.
300 // Use the immediate name of functions at compilation time.
302 // Use more verbose naming for functions without names, inferred from scope
303 // where possible.
305};
306
308 // Enables logging when a profile is active, and disables logging when all
309 // profiles are detached.
311 // Enables logging for the lifetime of the CpuProfiler. Calls to
312 // StartRecording are faster, at the expense of runtime overhead.
314};
315
316// Enum for returning profiling status. Once StartProfiling is called,
317// we want to return to clients whether the profiling was able to start
318// correctly, or return a descriptive error.
320 kStarted,
323};
324
332};
333
338 public:
340
341 virtual ~DiscardedSamplesDelegate() = default;
342 virtual void Notify() = 0;
343
344 ProfilerId GetId() const { return profiler_id_; }
345
346 private:
347 friend internal::CpuProfile;
348
349 void SetId(ProfilerId id) { profiler_id_ = id; }
350
351 ProfilerId profiler_id_;
352};
353
358 public:
359 // Indicates that the sample buffer size should not be explicitly limited.
360 static const unsigned kNoSampleLimit = UINT_MAX;
361
378 CpuProfilingMode mode = kLeafNodeLineNumbers,
379 unsigned max_samples = kNoSampleLimit, int sampling_interval_us = 0,
380 MaybeLocal<Context> filter_context = MaybeLocal<Context>());
381
384
385 CpuProfilingMode mode() const { return mode_; }
386 unsigned max_samples() const { return max_samples_; }
387 int sampling_interval_us() const { return sampling_interval_us_; }
388
389 private:
390 friend class internal::CpuProfile;
391
392 bool has_filter_context() const { return !filter_context_.IsEmpty(); }
393 void* raw_filter_context() const;
394
395 CpuProfilingMode mode_;
396 unsigned max_samples_;
397 int sampling_interval_us_;
398 Global<Context> filter_context_;
399};
400
406 public:
412 static CpuProfiler* New(Isolate* isolate,
413 CpuProfilingNamingMode = kDebugNaming,
414 CpuProfilingLoggingMode = kLazyLogging);
415
421 static void CollectSample(Isolate* isolate);
422
426 void Dispose();
427
434
443
449 CpuProfilingOptions options,
450 std::unique_ptr<DiscardedSamplesDelegate> delegate = nullptr);
451
458 Local<String> title, CpuProfilingOptions options,
459 std::unique_ptr<DiscardedSamplesDelegate> delegate = nullptr);
460
473 Local<String> title, CpuProfilingMode mode, bool record_samples = false,
474 unsigned max_samples = CpuProfilingOptions::kNoSampleLimit);
475
481 CpuProfilingResult Start(Local<String> title, bool record_samples = false);
482
489 Local<String> title, CpuProfilingOptions options,
490 std::unique_ptr<DiscardedSamplesDelegate> delegate = nullptr);
491
504 Local<String> title, CpuProfilingMode mode, bool record_samples = false,
505 unsigned max_samples = CpuProfilingOptions::kNoSampleLimit);
506
513 bool record_samples = false);
514
519
525
531
532 private:
533 CpuProfiler();
534 ~CpuProfiler();
535 CpuProfiler(const CpuProfiler&);
536 CpuProfiler& operator=(const CpuProfiler&);
537};
538
544 public:
545 enum Type {
546 kContextVariable = 0, // A variable from a function context.
547 kElement = 1, // An element of an array.
548 kProperty = 2, // A named object property.
549 kInternal = 3, // A link that can't be accessed from JS,
550 // thus, its name isn't a real property name
551 // (e.g. parts of a ConsString).
552 kHidden = 4, // A link that is needed for proper sizes
553 // calculation, but may be hidden from user.
554 kShortcut = 5, // A link that must not be followed during
555 // sizes calculation.
556 kWeak = 6 // A weak reference (ignored by the GC).
557 };
558
560 Type GetType() const;
561
567
570
572 const HeapGraphNode* GetToNode() const;
573};
574
575
580 public:
581 enum Type {
582 kHidden = 0, // Hidden node, may be filtered when shown to user.
583 kArray = 1, // An array of elements.
584 kString = 2, // A string.
585 kObject = 3, // A JS object (except for arrays and strings).
586 kCode = 4, // Compiled code.
587 kClosure = 5, // Function closure.
588 kRegExp = 6, // RegExp.
589 kHeapNumber = 7, // Number stored in the heap.
590 kNative = 8, // Native object (not from V8 heap).
591 kSynthetic = 9, // Synthetic object, usually used for grouping
592 // snapshot items together.
593 kConsString = 10, // Concatenated string. A pair of pointers to strings.
594 kSlicedString = 11, // Sliced string. A fragment of another string.
595 kSymbol = 12, // A Symbol (ES6).
596 kBigInt = 13, // BigInt.
597 kObjectShape = 14, // Internal data used for tracking the shapes (or
598 // "hidden classes") of JS objects.
599 kWasmObject = 15, // A WasmGC struct or array.
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
886 Node(const Node&) = delete;
887 Node& operator=(const Node&) = delete;
888 };
889
894 virtual Node* V8Node(const v8::Local<v8::Value>& value) = 0;
895
900 virtual Node* AddNode(std::unique_ptr<Node> node) = 0;
901
910 virtual void AddEdge(Node* from, Node* to, const char* name = nullptr) = 0;
911
912 virtual ~EmbedderGraph() = default;
913};
914
920 public:
922 kSamplingNoFlags = 0,
923 kSamplingForceGC = 1 << 0,
924 kSamplingIncludeObjectsCollectedByMajorGC = 1 << 1,
925 kSamplingIncludeObjectsCollectedByMinorGC = 1 << 2,
926 };
927
934 typedef void (*BuildEmbedderGraphCallback)(v8::Isolate* isolate,
935 v8::EmbedderGraph* graph,
936 void* data);
937
947 v8::Isolate* isolate, const v8::Local<v8::Value>& v8_value,
948 uint16_t class_id, void* data);
949
952
954 const HeapSnapshot* GetHeapSnapshot(int index);
955
961
967
973
980
986 static const SnapshotObjectId kUnknownObjectId = 0;
987
992 public:
997 virtual const char* GetName(Local<Object> object) = 0;
998
999 protected:
1000 virtual ~ObjectNameResolver() = default;
1001 };
1002
1003 enum class HeapSnapshotMode {
1007 kRegular,
1011 kExposeInternals,
1012 };
1013
1014 enum class NumericsMode {
1019 kHideNumericValues,
1023 kExposeNumericValues
1024 };
1025
1026 struct HeapSnapshotOptions final {
1027 // Manually define default constructor here to be able to use it in
1028 // `TakeSnapshot()` below.
1029 // NOLINTNEXTLINE
1031
1035 ActivityControl* control = nullptr;
1039 ObjectNameResolver* global_object_name_resolver = nullptr;
1043 HeapSnapshotMode snapshot_mode = HeapSnapshotMode::kRegular;
1047 NumericsMode numerics_mode = NumericsMode::kHideNumericValues;
1048 };
1049
1056 const HeapSnapshotOptions& options = HeapSnapshotOptions());
1057
1065 ActivityControl* control,
1066 ObjectNameResolver* global_object_name_resolver = nullptr,
1067 bool hide_internals = true, bool capture_numeric_value = false);
1068
1078 void StartTrackingHeapObjects(bool track_allocations = false);
1079
1094 int64_t* timestamp_us = nullptr);
1095
1102
1128 bool StartSamplingHeapProfiler(uint64_t sample_interval = 512 * 1024,
1129 int stack_depth = 16,
1130 SamplingFlags flags = kSamplingNoFlags);
1131
1136
1144
1150
1151 void AddBuildEmbedderGraphCallback(BuildEmbedderGraphCallback callback,
1152 void* data);
1153 void RemoveBuildEmbedderGraphCallback(BuildEmbedderGraphCallback callback,
1154 void* data);
1155
1157
1163 static const uint16_t kPersistentHandleNoClassId = 0;
1164
1165 private:
1166 HeapProfiler();
1167 ~HeapProfiler();
1168 HeapProfiler(const HeapProfiler&);
1169 HeapProfiler& operator=(const HeapProfiler&);
1170};
1171
1177 HeapStatsUpdate(uint32_t index, uint32_t count, uint32_t size)
1178 : index(index), count(count), size(size) { }
1179 uint32_t index; // Index of the time interval that was changed.
1180 uint32_t count; // New value of count field for the interval with this index.
1181 uint32_t size; // New value of size field for the interval with this index.
1182};
1183
1184#define CODE_EVENTS_LIST(V) \
1185 V(Builtin) \
1186 V(Callback) \
1187 V(Eval) \
1188 V(Function) \
1189 V(InterpretedFunction) \
1190 V(Handler) \
1191 V(BytecodeHandler) \
1192 V(LazyCompile) /* Unused, use kFunction instead */ \
1193 V(RegExp) \
1194 V(Script) \
1195 V(Stub) \
1196 V(Relocation)
1197
1203 kUnknownType = 0
1204#define V(Name) , k##Name##Type
1206#undef V
1208
1213 public:
1215 size_t GetCodeSize();
1226 const char* GetComment();
1227
1228 static const char* GetCodeEventTypeName(CodeEventType code_event_type);
1229
1231};
1232
1237 public:
1243 explicit CodeEventHandler(Isolate* isolate);
1245
1254 virtual void Handle(CodeEvent* code_event) = 0;
1255
1260 void Enable();
1261
1266 void Disable();
1267
1268 private:
1271 CodeEventHandler& operator=(const CodeEventHandler&);
1272 void* internal_listener_;
1273};
1274
1275} // namespace v8
1276
1277
1278#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 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)
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
void * NativeObject
Definition v8-profiler.h:29
CpuProfilingStatus
CpuProfilingLoggingMode
@ kLazyLogging
@ kEagerLogging
CpuProfilingMode
@ kLeafNodeLineNumbers
@ kCallerLineNumbers
StateTag
Definition v8-unwinder.h:36
uint32_t ProfilerId
Definition v8-profiler.h:31
CodeEventType
@ kUnknownType
CpuProfilingNamingMode
@ kDebugNaming
@ kStandardNaming
uint32_t SnapshotObjectId
Definition v8-profiler.h:30
std::vector< Node * > children
Local< String > script_name
std::vector< Allocation > allocations
const char * deopt_reason
Definition v8-profiler.h:52
std::vector< CpuProfileDeoptFrame > stack
Definition v8-profiler.h:53
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:719