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.

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 of [ 0.01, 0.1, 1, 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

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.limit

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
v8js.memory.heap.limit	UpDownCounter	By	Total heap memory size pre-allocated. [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

[1] v8js.heap.space.name: Value can be retrieved from value space_name of v8.getHeapSpaceStatistics()

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_space	Code memory space.
large_object_space	Large object memory space.
map_space	Map memory space.
new_space	New memory space.
old_space	Old memory space.

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

[1] v8js.heap.space.name: Value can be retrieved from value space_name of v8.getHeapSpaceStatistics()

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_space	Code memory space.
large_object_space	Large object memory space.
map_space	Map memory space.
new_space	New memory space.
old_space	Old memory space.

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

[1] v8js.heap.space.name: Value can be retrieved from value space_name of v8.getHeapSpaceStatistics()

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_space	Code memory space.
large_object_space	Large object memory space.
map_space	Map memory space.
new_space	New memory space.
old_space	Old memory space.

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

[1] v8js.heap.space.name: Value can be retrieved from value space_name of v8.getHeapSpaceStatistics()

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_space	Code memory space.
large_object_space	Large object memory space.
map_space	Map memory space.
new_space	New memory space.
old_space	Old memory space.