Semantic conventions for V8 JS engine runtime metrics

Status: Development

This document describes semantic conventions for V8 JS Engine Runtime metrics in OpenTelemetry. This engine is used in some JavaScript runtime such as Node.js and Deno.

• Metric: v8js.gc.duration
• Metric: v8js.memory.heap.space.available_size
• Metric: v8js.memory.heap.space.physical_size
• Metric: v8js.memory.heap.space.size
• Metric: v8js.memory.heap.used
• Metric: v8js.resource.active

Description: In-development V8 JS Engine Runtime metrics captured under v8js.

Metric: v8js.gc.duration

This metric is recommended.

This metric SHOULD be specified with ExplicitBucketBoundaries advisory parameter of [ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ].

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
v8js.gc.duration	Histogram	s	Garbage collection duration. [1]

[1]: The values can be retrieved from perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
v8js.gc.type		Required	string	The type of garbage collection.	major; minor; incremental (see more)

v8js.gc.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
incremental	Incremental (Incremental Marking).
major	Major (Mark Sweep Compact).
minor	Minor (Scavenge).
weakcb	Weak Callbacks (Process Weak Callbacks).

Metric: v8js.memory.heap.space.available_size

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
v8js.memory.heap.space.available_size	UpDownCounter	By	Heap space available size. [1]

[1]: Value can be retrieved from value space_available_size of v8.getHeapSpaceStatistics()

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
v8js.heap.space.name		Required	string	The name of the space type of heap memory. [1]	new_space; old_space; code_space (see more)

[1] v8js.heap.space.name: Value can be retrieved from value space_name of v8.getHeapSpaceStatistics(). The set of reported spaces depends on the V8 version the runtime embeds.

v8js.heap.space.name has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
code_large_object_space	Large object space for code objects.
code_space	Code memory space.
large_object_space	Large object memory space.
map_space	Map memory space. [2]
new_large_object_space	Large object space for young-generation objects.
new_space	New memory space.
old_space	Old memory space.
read_only_space	Read-only memory space, holding immutable objects created at startup.
shared_large_object_space	Large object space for shared objects.
shared_space	Memory space for objects shared across isolates (e.g. shared strings and structs).
shared_trusted_large_object_space	Large object space for shared trusted objects.
shared_trusted_space	Shared variant of the trusted memory space.
trusted_large_object_space	Large object space for trusted objects.
trusted_space	Memory space for trusted objects kept outside the V8 sandbox (e.g. bytecode).

[2]: Only reported by Node.js <= 19; V8 merged the map space into the old space in V8 11.x.

Metric: v8js.memory.heap.space.physical_size

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
v8js.memory.heap.space.physical_size	UpDownCounter	By	Committed size of a heap space. [1]

[1]: Value can be retrieved from value physical_space_size of v8.getHeapSpaceStatistics()

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
v8js.heap.space.name		Required	string	The name of the space type of heap memory. [1]	new_space; old_space; code_space (see more)

[1] v8js.heap.space.name: Value can be retrieved from value space_name of v8.getHeapSpaceStatistics(). The set of reported spaces depends on the V8 version the runtime embeds.

v8js.heap.space.name has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
code_large_object_space	Large object space for code objects.
code_space	Code memory space.
large_object_space	Large object memory space.
map_space	Map memory space. [2]
new_large_object_space	Large object space for young-generation objects.
new_space	New memory space.
old_space	Old memory space.
read_only_space	Read-only memory space, holding immutable objects created at startup.
shared_large_object_space	Large object space for shared objects.
shared_space	Memory space for objects shared across isolates (e.g. shared strings and structs).
shared_trusted_large_object_space	Large object space for shared trusted objects.
shared_trusted_space	Shared variant of the trusted memory space.
trusted_large_object_space	Large object space for trusted objects.
trusted_space	Memory space for trusted objects kept outside the V8 sandbox (e.g. bytecode).

[2]: Only reported by Node.js <= 19; V8 merged the map space into the old space in V8 11.x.

Metric: v8js.memory.heap.space.size

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
v8js.memory.heap.space.size	UpDownCounter	By	Total heap memory size pre-allocated for a heap space. [1]

[1]: The value can be retrieved from value space_size of v8.getHeapSpaceStatistics()

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
v8js.heap.space.name		Required	string	The name of the space type of heap memory. [1]	new_space; old_space; code_space (see more)

[1] v8js.heap.space.name: Value can be retrieved from value space_name of v8.getHeapSpaceStatistics(). The set of reported spaces depends on the V8 version the runtime embeds.

v8js.heap.space.name has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
code_large_object_space	Large object space for code objects.
code_space	Code memory space.
large_object_space	Large object memory space.
map_space	Map memory space. [2]
new_large_object_space	Large object space for young-generation objects.
new_space	New memory space.
old_space	Old memory space.
read_only_space	Read-only memory space, holding immutable objects created at startup.
shared_large_object_space	Large object space for shared objects.
shared_space	Memory space for objects shared across isolates (e.g. shared strings and structs).
shared_trusted_large_object_space	Large object space for shared trusted objects.
shared_trusted_space	Shared variant of the trusted memory space.
trusted_large_object_space	Large object space for trusted objects.
trusted_space	Memory space for trusted objects kept outside the V8 sandbox (e.g. bytecode).

[2]: Only reported by Node.js <= 19; V8 merged the map space into the old space in V8 11.x.

Metric: v8js.memory.heap.used

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
v8js.memory.heap.used	UpDownCounter	By	Heap Memory size allocated. [1]

[1]: The value can be retrieved from value space_used_size of v8.getHeapSpaceStatistics()

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
v8js.heap.space.name		Required	string	The name of the space type of heap memory. [1]	new_space; old_space; code_space (see more)

[1] v8js.heap.space.name: Value can be retrieved from value space_name of v8.getHeapSpaceStatistics(). The set of reported spaces depends on the V8 version the runtime embeds.

v8js.heap.space.name has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
code_large_object_space	Large object space for code objects.
code_space	Code memory space.
large_object_space	Large object memory space.
map_space	Map memory space. [2]
new_large_object_space	Large object space for young-generation objects.
new_space	New memory space.
old_space	Old memory space.
read_only_space	Read-only memory space, holding immutable objects created at startup.
shared_large_object_space	Large object space for shared objects.
shared_space	Memory space for objects shared across isolates (e.g. shared strings and structs).
shared_trusted_large_object_space	Large object space for shared trusted objects.
shared_trusted_space	Shared variant of the trusted memory space.
trusted_large_object_space	Large object space for trusted objects.
trusted_space	Memory space for trusted objects kept outside the V8 sandbox (e.g. bytecode).

[2]: Only reported by Node.js <= 19; V8 merged the map space into the old space in V8 11.x.

Metric: v8js.resource.active

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
v8js.resource.active	Gauge	{resource}	Gauge of the active resources that are currently keeping the event loop alive. [1]

[1]: The values can be retrieved from process.getActiveResourcesInfo()

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
v8js.resource.type		Required	string	The type of resource keeping the event loop active.	Immediate; TCPServerWrap; TCPWrap (see more)

v8js.resource.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
Immediate	Active setImmediate callbacks.
TCPServerWrap	Active TCP Servers.
TCPWrap	Active TCP connections.
Timeout	Active setTimeout or setInterval timers.
TTYWrap	Active Terminal I/O (stdin/stdout).