Semantic conventions for CPython runtime metrics

Status: Development

This document describes semantic conventions for CPython Runtime metrics in OpenTelemetry.

CPython Garbage Collection

Status: development

Description: CPython metrics related to garbage collection, captured under the namespace cpython.gc.*.

Metric: cpython.gc.collections

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
cpython.gc.collections	Counter	{collection}	The number of times a generation was collected since interpreter start. [1]

[1]: This metric reports data from gc.stats().

Attribute	Type	Description	Examples	Requirement Level	Stability
cpython.gc.generation	int	Value of the garbage collector collection generation.	0; 1; 2	Required

cpython.gc.generation 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
0	Generation 0
1	Generation 1
2	Generation 2

Metric: cpython.gc.collected_objects

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
cpython.gc.collected_objects	Counter	{object}	The total number of objects collected inside a generation since interpreter start. [1]

[1]: This metric reports data from gc.stats().

Attribute	Type	Description	Examples	Requirement Level	Stability
cpython.gc.generation	int	Value of the garbage collector collection generation.	0; 1; 2	Required

cpython.gc.generation 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
0	Generation 0
1	Generation 1
2	Generation 2

Metric: cpython.gc.uncollectable_objects

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
cpython.gc.uncollectable_objects	Counter	{object}	The total number of objects which were found to be uncollectable inside a generation since interpreter start. [1]

[1]: This metric reports data from gc.stats().

Attribute	Type	Description	Examples	Requirement Level	Stability
cpython.gc.generation	int	Value of the garbage collector collection generation.	0; 1; 2	Required

cpython.gc.generation 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
0	Generation 0
1	Generation 1
2	Generation 2