# Semantic conventions for CPython runtime metrics **Status**: [Development][DocumentStatus] This document describes semantic conventions for CPython Runtime metrics in OpenTelemetry. - [CPython garbage collection](#cpython-garbage-collection) - [Metric: `cpython.gc.collections`](#metric-cpythongccollections) - [Metric: `cpython.gc.collected_objects`](#metric-cpythongccollected_objects) - [Metric: `cpython.gc.uncollectable_objects`](#metric-cpythongcuncollectable_objects) ## CPython garbage collection **Status**: [development][DocumentStatus] **Description:** CPython metrics related to garbage collection, captured under the namespace `cpython.gc.*`. ### Metric: `cpython.gc.collections` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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()`](https://docs.python.org/3/library/gc.html#gc.get_stats). | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`cpython.gc.generation`](/docs/registry/attributes/cpython.md) | 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][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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()`](https://docs.python.org/3/library/gc.html#gc.get_stats). | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`cpython.gc.generation`](/docs/registry/attributes/cpython.md) | 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][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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()`](https://docs.python.org/3/library/gc.html#gc.get_stats). | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`cpython.gc.generation`](/docs/registry/attributes/cpython.md) | 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 |  | [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.42.0/specification/document-status.md [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended